Set up an API POST request - Airtable

The Data Collections allow you to create API requests to any database or tool with an available REST API.

Here is how to create a POST request to create data in the external database from your app.

Example Figma file

Here is the Figma file used in the example.

Example Database

We'll use an Airtable base as an example. In case you're using another backend tool, you need to read the API documentation to see how to construct the request (both the URL and body).

Duplicate this Airtable base as the database to send data. We will follow Airtable's API documentation to set up the POST request below. Here, we'll see an example request with the JSON body we need to use to add a new record to the table.

How to set up a POST request

1. In Data Library, click + New Collection and select Airtable Wizard.

2. Follow the wizard to create a new API collection, with two sample GET requests targeting the Airtable base.

3. After completing the tutorial, one GET list and one GET detail requests will be created. Duplicate the GET List request, edit the request name to help you identify it + change the request type to POST.

4. Change the POST request URL in case you need to do that. In this example, we'll keep the same URL as in the GET list request. The URL is targeting the Scores table of the Airtable base.

5. The API documentation specifies any Headers, Parameters, and/or Body value needed in order to make the POST request. In this example, Airtable requires an Authorization header field, as it uses the bearer token method to authenticate the request.

For Header: **H "Authorization: Bearer YOUR_API_KEY".

In this example, as we used the Airtable wizard and provided the API key there, this value will be already set for us. In case you're using another backend tool, read the documentation to see how you should authenticate your requests.

6. The type of the body of the request is indicated by the Content-Type header.

For Body: Airtable indicates H "Content-Type: application/json". Therefore, under Body, select JSON to indicate which data will be sent in the POST request.

6A. Copy one record data from the Example Request in the API documentation. Make sure you have the same amount of opening and closing brackets. You can use a JSON validator to make sure the JSON snippet you copied is syntactically correct, and avoid getting errors later on.

6B. Now, we'll replace the values in the example request body with variables, keeping the same key names ("Name" and "Score" in this case), as these are the names of the Airtable columns.

To define a variable, we'll use this notation: ${input}. In our case, we'll define the variables ${name} and ${score}, but you can use whatever variable name you wish. Permitted characters: lowercase a-z, uppercase A-Z, 0 to 9, underscore (_) and dash (-). No spacing.

Later on, when binding the UI elements of our app to the API requests, we'll specify which elements are bound to which variables. For instance, if we have a form connected to this post request, we'll bind each input field to one of the variables we defined in the JSON body.

{
  "records": [
    {
      "fields": {
        "Name": "${name}",
        "Score": ${score}
      }
    }
  ]
}

6C. Finally, we'll send a test request against our database, to make sure the request is built correctly. For that, we'll go to the Test Values section inside the API request, and indicate mock data for the variables we previously defined. The Key name for the test value must match the name we defined for the variable (case-sensitive).

The example content will appear in your database in the next step if the POST request is set up correctly.

7. Once we've set the values, press Send. A new record will be created in our table, with the data we specified as test value.

If the request was sent successfully, you'll get a response message, containing the data received from the API endpoint. The received data will depend on the configuration of the backend tool. In this example, we'll receive the data corresponding to the row we just created.

On the other hand, if the request was not successful, you will get an HTTP error as a response. In this case, review and double check your JSON body and URL to be correct.