API Guide

With both Flatfile's Portal and Concierge, you have the ability to pull imports from the Flatfile API for your account using either the Rest API or GraphQL API. Each has some different steps to take when using it, and the differences between the two are listed below. We also have an API endpoint reference to check on the endpoints, but some better steps for working with each are listed below.

No matter which API you plan to use, there is one common step that you'll have to do before you can pull data from either. Within your Flatfile Dashboard, you'll open the menu and click the "Account" option. Under the "Account Settings" section, you will see a "Manage Access Keys" button. When you click on this, you will see your access keys (if you have any already) and a button that says "Create access key". When you click that button, it will have you provide a reference name for the key and then will create the keys. You'll see a screen with your Access Key ID and your Secret Access Key. Please make sure to note your Secret Access Key as once you hit "Continue," you will no longer be able to access this secret and would have to create another key to obtain a new secret. Once you've obtained your Access Key ID and your Secret Access Key, you can continue on using whichever API you choose to utilize.

Using the REST API

For using the REST API, there are different required and optional query parameters with each endpoint that you can note here, but in each of the GET request endpoints being used with the REST API, you will need to use your Access Key and Access Secret separated by a + inside a "X-Api-Key" key within the headers like in the below example using the rest/batches endpoint.

const getBatches = async () => {
  const response = await fetch(
    "https://api.us.flatfile.io/rest/batches?licenseKey=YOUR_LICENSE_KEY",
    {
      method: "GET",
      headers: {
        "Content-Type": "application/json",
        "X-Api-Key": "Access_Key_ID+Secret_Access_Key",
      },
    },
  );
  return response.json();
};

Note: We use the more recent fetch API in this example, but any way of doing an HTTP request will work.

Using the GraphQL API

Before you begin: The very first thing you have to do is get your bearer token. To do this, you will use the Rest API endpoint api.us.flatfile.io/auth/access-key/exchange to take the Access Key Id and Secret Access Key to exchange for a token to use. For this endpoint, we will use a POST request with the accessKeyId, secretAccessKey and an expiration request in expiresIn to get the bearer token back.

const accessTokenExchange = async () => {
  const response = await fetch("https://api.us.flatfile.io/auth/access-key/exchange", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      accessKeyId: "Access_Key_Id",
      secretAccessKey: "Secret_Access_Key",
      expiresIn: 86400, // default: 43200 (12 hours) minimum: 60 (1 minute) maximum: 86400 (24 hours)
    }),
  });
  return response.json();
};

Once you get back this new token, you can use that within your GraphQL setup to process request from our GraphQL endpoint (https://api.us.flatfile.io/graphql).

With GraphQL, querying all of the same batches we called above on the REST API might look like this:

query {
  getBatches(licenseKey: "YOUR_LICENSE_KEY") {
    data {
      id
    }
  }
}

Using cURL

When using cURL, you will need to follow a similar structure as with the REST API in that you need to provide your license key in the URL and setting the X-Api-Key header with a format of Access_Key_ID+Secret_Access_Key .

curl -H "X-Api-Key: Access_Key_ID+Secret_Access_Key" https://api.us.flatfile.io/rest/batches?licenseKey=YOUR_LICENSE_KEY

This cURL request would return the batches similar to the above REST and GraphQL APIs.