Airtable

Sync data to Airtable bases and tables. Use Zeotap to push model results, audience lists, or enriched customer data into Airtable for collaboration, reporting, and operational workflows.

Prerequisites

• An Airtable account (Free, Team, Business, or Enterprise plan)
• An Airtable personal access token with appropriate scopes
• A base and table to write data to

Permissions

Your personal access token must have the following scopes:

• data.records:read — required for connection testing and schema introspection
• data.records:write — required for creating and updating records
• schema.bases:read — required for schema introspection (discovering table fields)

The token must also have access to the specific base you want to sync to. You can configure this when creating the token at airtable.com/create/tokens.

Authentication

Airtable uses a Personal Access Token for authentication.

1. Go to airtable.com/create/tokens
2. Click Create new token
3. Give the token a descriptive name (e.g., “Zeotap Sync”)
4. Add the scopes: data.records:read, data.records:write, schema.bases:read
5. Under Access, add the specific base(s) you want to sync to
6. Click Create token and copy the token (it starts with pat...)
7. In Zeotap, paste the token into the Personal Access Token field

Configuration

Airtable does not require additional configuration fields beyond authentication.

Target Settings

Supported Operations

Sync Modes

Audience Sync Modes

Airtable does not have a native list or audience membership concept, so audience sync modes are not supported.

Features

• Field Mapping: Yes — map source columns to Airtable field names
• Schema Introspection: Yes — Zeotap reads the table’s field definitions via the Airtable metadata API

Required Mapping Fields

Airtable does not require specific mapping fields. However, for upsert and update sync modes, you must configure a primary key field that matches a unique field in your Airtable table.

Default Destination Fields

These are suggested defaults. Your actual Airtable table may have different fields — Zeotap discovers them automatically via schema introspection.

How It Works

Zeotap writes data to the specified Airtable table via the Airtable REST API v0:

1. Insert mode: Records are created using POST /v0/{baseId}/{tableName} with up to 10 records per request
2. Upsert mode: Records are created or updated using PATCH /v0/{baseId}/{tableName} with the performUpsert parameter. The fieldsToMergeOn array specifies which field(s) to match on for deduplication
3. Update mode: Same as upsert — existing records matched by the primary key field are updated, and unmatched records are created

Batching

Airtable limits API requests to 10 records per request. Zeotap automatically chunks larger batches into groups of 10 and sends them sequentially to respect this limit.

Error Handling

• Each chunk of 10 records is sent as an atomic request. If any record in a chunk fails, the entire chunk is marked as failed.
• The writer retries on transient errors (HTTP 429 rate limits and 5xx server errors) with exponential backoff.
• Detailed error information is captured per chunk and reported in the sync run results.

Rate Limits

Airtable enforces a rate limit of 5 requests per second per base across all pricing tiers. This means:

• Maximum throughput: ~50 records/second (5 requests x 10 records/request)
• If the rate limit is exceeded, Airtable returns HTTP 429. Zeotap automatically retries with a 30-second backoff.
• For large datasets (>10,000 records), syncs may take several minutes due to rate limiting.

Best Practices

1. Use unique fields for upsert: When using upsert mode, ensure the primary key field contains unique values in your Airtable table. Airtable’s performUpsert matches on field values, not record IDs.
2. Keep tables focused: Airtable bases have a limit of 50,000 records on the free plan and 100,000 on paid plans. For large datasets, consider filtering data before syncing.
3. Name fields consistently: Use the exact Airtable field names in your field mapping. Field names are case-sensitive.
4. Monitor API usage: Airtable’s free plan allows 1,000 API calls per month. For frequent syncs, use a Team or Business plan.
5. Use table IDs for stability: Table names can be renamed by collaborators. Using table IDs (e.g., tblXXXXXXXX) in the Target Settings ensures syncs continue working even if the table is renamed.

Troubleshooting

Authentication failed: invalid personal access token

Verify that your personal access token is correct and has not been revoked. Tokens start with pat. Generate a new token at airtable.com/create/tokens if needed.

Access denied: token lacks required scopes

Your personal access token must have the data.records:read, data.records:write, and schema.bases:read scopes. Edit the token’s scopes in your Airtable account settings.

Base or table not found

Double-check the Base ID and Table Name in your target settings. The Base ID starts with app and can be found in the Airtable URL. The table name must match exactly (case-sensitive) or use the table ID (starts with tbl).

Rate limited (HTTP 429)

Airtable enforces 5 requests per second per base. Zeotap retries automatically with backoff, but very large syncs may be slow. Avoid running multiple syncs to the same base simultaneously.

Upsert not matching existing records

Ensure the primary key field name in your sync configuration exactly matches the field name in Airtable (case-sensitive). The field must contain unique values for upsert matching to work correctly.

Field type mismatch

If records fail to create or update, check that the values you’re sending match the expected field types in Airtable. For example, sending a string to a number field will cause an error. Use field mapping transforms to convert data types before syncing.

Records exceeding base limits

Airtable bases have record limits based on your plan (50,000 for free, 100,000 for paid). If your sync would exceed these limits, records may fail to create. Consider filtering your data or upgrading your Airtable plan.