Airtable Sync integration: Sync API
  • 23 Aug 2023
  • 6 Minutes to read
  • Dark
    Light
  • PDF

Airtable Sync integration: Sync API

  • Dark
    Light
  • PDF

Article Summary

Learn how to use the Airtable Sync integration feature to bring information from external applications into a single, centralized table within Airtable. This article covers how to sync CSV formatted data into Airtable via API calls authorized by utilizing Personal Access Tokens


Introduction

Plan availabilityBusiness and Enterprise Scale access only
Permissions

Owners/Creators - In order to create or update synced tables, you'll need to have creator permissions in the base where you are setting up the sync. Additionally, you'll need creator permissions in the base to set up a PAT for use during the setup process.

Platform(s)Web/Browser, Mac app, and Windows app
Related reading

Setup

Below, we'll walk you through the general setup process for API syncs. It's important to note that this sync is intended for workflows that involve utilizing CSVs to sync information into Airtable via an API endpoint. If you are wondering about best practices for CSV formatting, then hop below before proceeding. Otherwise, if you are familiar with our CSV guidelines, then feel free to start setting things up!

Step 1: Add a new synced table to a base

Click the + Add or import option next to the last table in the base. Then, click on the more sources... option at the bottom of that drop-down.

Step 2: Find the Sync API option

Next, you'll see a popover menu where you can either scroll to the Sync API feature or search it by clicking the Find a source option.

Step 3: Send your first API request

This will open up the Sync API configuration window. Once you are ready, click Set up to move to the next screen. If you haven't set up a personal access token with data.records:write and schema.bases:write scopes before, then you can click Create a token → to generate one. Otherwise, you can use a previously configured token in the cURL request. You'll want to click the COPY button and configure the API request before you can proceed with additional sync setup steps.

Note
You'll want to replace the ${PERSONAL ACCESS TOKEN} portion of the cURL request we provide with a PAT that is configured with the relevant scope described above. 

Once you've successfully sent the first API request to this endpoint the "Waiting to receive API request..." message will change to "✓ API request received" and you'll be able to click Next.

Step 4: Customize how the data will be imported

There are three main sections to complete before creating the synced table. The first section allows you to: 

  1. Choose which fields from the example CSV you sent via API request to sync into Airtable. Choosing All fields will also allow additional columns in the CSV to be added in the future. Choosing Specific fields will only allow those fields to sync into Airtable in the future. 
  2. You can drag the fields around to order them. 
  3. Finally, clicking the drop-down in each field will allow you to choose the field type of each column from the CSV. 

There are 10 field types that we support in the field customization step:

Single Line Text
Email
Long text field
Number
Date
Duration
Phone number
Currency
URL
Percent
Step 5: Choose a unique identifier

In this section of the setup process, you'll choose a field that will act as the primary key for the table of data that you are generating. This provides Airtable with the logic to ensure that the correct records in Airtable are updated, created, or prevented from being duplicated. Common industry-standard examples for this include:

  • Name fields that will always be unique
  • Electronic Identifier Serial Publication codes (EISPs)
  • Unique Product Identifiers (UPIs), Electronic Product Codes (EPCs), or Universal Product Codes (UPCs)
  • International eBook Identifier Numbers (IEINs) or International Standard Book Numbers (ISBNs)
  • Stock keeping units (SKUs)
  • Bates numbering or European Case Law Identifiers (ECLIs)

Not every case will match the examples above, so use your best judgment to choose the unique identifier for your situation. Click the Select an option drop-down menu and choose a field that will uniquely identify records.

Step 6: Confirm sync settings

The final part of the setup process is to set how often the synced table will be updated and how the records will be deleted or maintained over time. By default the synced table will be set to:

  • Update method- Automatically update whenever an API request is received
    • Alternatively, this can be changed to Only sync changes when requested in which case the table would need to be synced manually and would only sync the data contained within the most recent API request sent.
  • Deletion- Records that are no longer present in the CSV request body sent in the most recently sent API will be deleted
    • Alternatively, this can be changed to Leave the records in this table which would essentially cause the data from CSV API requests to compound over time. It's important to remember that synced records cannot be manually deleted. Choosing which setting to use is fully contingent upon your individual needs.

You can click Change next to either option to adjust the settings.

Step 7: Create the synced table

Once you are satisfied with the sync setup, click the Create table button. Depending upon the size of the initial CSV sent to Airtable, this may take a moment.

Once the table has been created, it's a good idea to look through the table and make sure everything looks correct. If you do need to make any changes now or in the future, then click the drop-down menu next to the name of your synced table and then choose the Update sync configuration option.


CSV formatting guidelines

Size limits

  • The request body must be 2MB or less.
  • A maximum of 10,000 records (rows) can be synced. Your request can contain more than 10,000 rows, but only the first 10,000 will be synced.
  • A maximum of 500 fields (columns) are supported. Your request cannot contain more than 500 columns or the sync will fail.

Format

  • The HTTP header Content-Type: text/csv is required.
  • The request body should be a plaintext CSV string delimited with commas.
  • The first row of the CSV request body will be parsed as a header row and will appear as field names in your synced table. No other rows can be used as the header row.
  • Field names in the header row must not be empty.
  • Field names in the header row must be case-insensitive and unique.
  • The primary field and unique ID must be present in the header row.


API scopes

This sync integration requires an Airtable PAT that has the following scopes enabled

Scope nameScope purpose
data.records:writeCreate, edit, and delete records
schema.bases:writeEdit the structure of a base, like adding new fields or tables


FAQs

Can I use an API key to set up this sync integration?

No, this integration will not work with API keys. Airtable has introduced personal access tokens that are used instead.

Are there any limits to be aware of?
  • The CSV data can contain up to 10k rows, 500 columns, and the HTTP request's size is limited to 2 MB.
  • There is a rate limit of 1 request, per 10 minutes, per base for this endpoint.
Are there any developer docs related to this feature?
Is there a way to populate attachment fields with a Sync API integration?

Not directly. The Sync API integration supports the following field types:

Single line text, Email, Long text field, Number, Date, Duration, Phone number, Currency, URL, and Percent.

Right now, likely the best workaround is to sync publicly accessible image URLs to a single text field and then configure an automation to append attachment URLs to an additional attachment field. There is a community thread where you can find more information about this workaround here.


Was this article helpful?