Airtable Sync integration: Sync API
  • 25 Jan 2023
  • 6 Minutes to read
  • Dark
    Light

Airtable Sync integration: Sync API

  • Dark
    Light

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 availabilityPro or Enterprise plans 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 file 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.

So on and so forth

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

File size

  • Files must be 5MB or less
  • A maximum of 10,000 records (rows) can be synced at this time. Your file can contain more than 10,000 rows, but only 10,000 will be synced

File format

  • The first row of the CSV file will be parsed as a header row which will appear as field names in your synced table. No other rows can perform this function.
  • All column names in the header row must be case-insensitive and unique.
  • All column names in the header row must be non-empty strings.
  • The header row cannot contain more than 500 columns.
  • 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?