---
title: "Airtable Sync integration: Sync API"
slug: "airtable-sync-integration-sync-api"
description: "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 PATs. "
updated: 2025-11-12T22:36:41Z
published: 2025-11-12T22:36:41Z
---

> ## Documentation Index
> Fetch the complete documentation index at: https://support.airtable.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Airtable Sync integration: Sync API

| **Plan availability** | Business and Enterprise Scale access only |
| --- | --- |
| **Permissions** | **Owners/Creators** - 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** | - [**Sync - Basic setup**](/docs/airtable-sync-basic-setup) - If you haven’t set up a sync before, we recommend first reading this article to become familiarized with how the Airtable Sync feature generally works. - [**Airtable Sync FAQs**](/docs/airtable-sync-faqs) - Answers to common questions that might help unblock you if you are encountering issues. - [**Airtable Sync integration: Emailed data**](/docs/airtable-sync-integration-emailed-data) - An alternative way of bringing CSV data into Airtable. - [**Importing CSV data into an existing base**](/docs/import-csv-data-into-an-existing-base) - Manually import CSV data into a base. Great for when you only need to import CSV data to create the initial structure of a table in Airtable. |

Learn how to use the Airtable Sync integration feature to bring information from an external application into Airtable as a new table in your base. Sync integrations are always a one way sync from the external application into an Airtable base, so changes made in Airtable **cannot** be synced back to the external application that you are syncing with.

This article covers how to sync CSV formatted data into Airtable via API calls authorized by utilizing [Personal Access Tokens](https://support.airtable.com/docs/creating-and-using-api-keys-and-access-tokens#personal-access-tokens-basic-actions).

## Setting up API syncs in Airtable

> [!CAUTION]
> Note
> 
> If you are wondering about best practices for CSV formatting, then [check the section below](/v1/docs/airtable-sync-integration-sync-api#csv-formatting-guidelines) before proceeding. Otherwise, if you are familiar with our CSV guidelines, then feel free to start setting things up.

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**.

1. Visit your home screen and select the base where want to add an API sync, or, create a new base.
2. Click the **+ Add or import** button next to the last table in the base.
  1. In bases with more than 3 tables, this will just appear as a **+** button.
3. Scroll to the bottom of the options. Below “Add from other sources,” click the **xx more sources…** button.
4. Next, you'll see a popover menu where you can either scroll to the **Sync API**feature or search for it by clicking into the **Find a source** option and search for “Sync API.”
5. This will open up the Sync API configuration window. Once you are ready, click **Set up** to move to the next screen.
  1. 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.
  2. Otherwise, you can use a previously configured token in the cURL request.
  3. You'll want to click the **COPY** button and configure the API request before you can proceed with additional sync setup steps.

> [!CAUTION]
> Note
> 
> You'll need to replace the `${PERSONAL ACCESS TOKEN}` portion of the cURL request we provide with a PAT that is configured with the relevant scopes described above.
6. 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**.
7. There next portion of the setup process has to do with field configurations:
  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, number, date, duration, phone number, currency, URL, and percent.
8. 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:

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.
  - 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)
9. The final part of the setup process determines 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:

You can click **Change** next to either option to adjust the settings.
  - **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.
10. Once you are satisfied with the sync setup, click the **Create table** button.
  1. Depending upon the size of the initial CSV sent to Airtable, this may take a moment.
  2. Once the table has been created, it's a good idea to look through the table and make sure everything looks correct.
  3. 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.

Formatting:

- 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 name | Scope purpose |
| --- | --- |
| `data.records:write` | Create, edit, and delete records |
| `schema.bases:write` | Edit 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 20 requests, per 5 minutes, per base for this endpoint.

**Are there any developer docs related to this feature?**

Yes, [you can find that here](https://airtable.com/developers/web/api/post-sync-api-endpoint).

**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](https://community.airtable.com/t5/show-tell/native-url-to-attachment/td-p/116584).

**Why do base records synced via the AP that I deleted, and later re-added with the same values, have the identical record IDs as the original record I deleted?**

When records synced via Airtable’s API are deleted from a base and later re-added with the same values, the new records retain the same record IDs as the previously deleted ones because record IDs are reused if the new records share the same underlying resource ID and the re-add occurs within the retention window. The default retention period is 30 days. After the retention period, re-created records are assigned new record IDs. The retention period is configurable and may vary by application.