# Connecting Airtable

> Source: https://docs.trailspark.ai/docs/connecting-airtable

## Overview

The Airtable integration connects TrailSpark to your Airtable base, treating it as a full CRM. After authenticating, you map which tables contain your Contacts, Companies, and Deals, then configure which fields TrailSpark should use for deal analysis.

Unlike traditional CRMs with fixed schemas, Airtable bases vary widely. TrailSpark's table mapping wizard lets you tell it exactly where your data lives.

## Prerequisites

- An **Airtable** account with at least one base containing contact/company data
- **Admin** or **Owner** role in TrailSpark

## Connect to Airtable

TrailSpark supports two authentication methods.

### Option 1: OAuth (Recommended)

1. Go to **Settings** > **CRM Integration**
2. Click **Connect** on the Airtable card
3. You will be redirected to Airtable to authorize TrailSpark
4. Select the workspace and bases to grant access to
5. Click **Grant access**

After authorization, you are redirected back to TrailSpark to configure table mapping.

### Option 2: Personal Access Token

If you prefer not to use OAuth, you can connect with a Personal Access Token (PAT).

#### Create a token in Airtable

1. Go to [airtable.com/create/tokens](https://airtable.com/create/tokens) (or navigate to **Account** > **Developer hub** > **Personal access tokens**)
2. Click **Create new token**
3. Give the token a name (e.g., "TrailSpark Integration")
4. Under **Scopes**, add:
   - `data.records:read` -- read records from your base
   - `schema.bases:read` -- read table and field schema
5. Under **Access**, click **Add a base** and select the base that contains your CRM data. You can grant access to a specific base or all bases in your workspace
6. Click **Create token**
7. **Copy the token immediately** -- Airtable only shows it once

#### Enter the token in TrailSpark

1. Go to **Settings** > **CRM Integration** > click **Connect** on Airtable
2. On the Airtable config page, choose **Use Personal Access Token**
3. Paste the token and click **Save Token**

> [!TIP]
> OAuth is recommended because it handles token refresh automatically. Personal Access Tokens must be regenerated manually if they expire.

## Configure Table Mapping

After authenticating, TrailSpark prompts you to map your Airtable tables. This step tells TrailSpark which tables and fields correspond to CRM concepts.

### 1. Select Your Base

Choose which Airtable base contains your CRM data. If your account has access to multiple bases, they are listed in the dropdown.

### 2. Map Core Tables

| Mapping | Required | Description |
|---------|----------|-------------|
| **Contacts Table** | Yes | The table containing people/leads (e.g., "Contacts", "Leads", "People") |
| **Companies Table** | Yes | The table containing organizations/accounts (e.g., "Companies", "Accounts") |
| **Deals Table** | No | The table containing deals/opportunities (e.g., "Deals", "Opportunities") |
| **Contact → Company Link** | No | A linked record field on the Contacts table that connects to the Companies table |

### 3. Configure Deal Fields

If you select a Deals table, TrailSpark needs to know which fields contain deal metadata. Four additional selectors appear:

| Field | Required | Type | Description |
|-------|----------|------|-------------|
| **Deal → Contact Link** | Yes | Linked Record | The field linking each deal to a contact record |
| **Deal → Company Link** | No | Linked Record | The field linking each deal to a company record |
| **Stage Field** | Yes | Single Select / Text | The field containing deal stage (e.g., "Closed Won", "Negotiation") |
| **Close Date Field** | Yes | Date | The field containing the deal close date |

> [!WARNING]
> If the Stage or Close Date fields are not mapped, TrailSpark cannot perform closed-won analysis or deal size statistics for ICP creation.

### 4. Save

Click **Save Table Mapping**. TrailSpark validates the configuration and confirms the mapping is saved. You can return to reconfigure at any time from **Settings** > **CRM Integration** > **Reconfigure Tables**.

## What Gets Synced

### Contacts

Name, email, job title, phone, and any other fields in your Contacts table. TrailSpark detects common field names automatically and supports custom mappings via [Field Mapping](/docs/field-mapping).

### Companies

Company name, industry, employee count, website, and other company fields. TrailSpark checks for common field name variants including `Name`, `Company Name`, `Account Name`, `Employees`, `Employee Count`, `Employee Size`, and `Industry`.

### Deals

If a Deals table is configured, TrailSpark syncs deal name, stage, amount, close date, and probability. Deal data is used for:

- **Closed-won analysis** -- identifying which contacts are associated with won deals
- **Deal size statistics** -- calculating median, average, and percentile deal values
- **SparkSense ICP creation** -- building your Ideal Customer Profile from historical win patterns

### Linked Records

Airtable uses linked record fields to connect tables. TrailSpark follows these links to associate contacts with their companies and deals. The Contact → Company link and Deal → Contact link fields you configure during table mapping enable this resolution.

## Airtable Field Names

Because Airtable schemas are user-defined, TrailSpark checks multiple common field name variants when reading data:

| Data Type | Field Names Checked |
|-----------|-------------------|
| Contact name | `First Name`, `Last Name`, `Full Name`, `Name` |
| Contact email | `Email`, `email` |
| Contact title | `Title`, `Job Title`, `Role` |
| Company name | `Name`, `Company Name`, `Account Name` |
| Employee count | `Employees`, `Employee Count`, `Employee Size`, `Number of Employees`, `Size` |
| Industry | `Industry`, `industry` |
| Deal name | `Name`, `Deal Name`, `Opportunity Name` |
| Deal amount | `Amount`, `Deal Value` |
| Deal probability | `Probability`, `Probability (%)` |

For fields that don't match any of these names, use [Field Mapping](/docs/field-mapping) to configure explicit mappings.

## Rate Limiting

Airtable's API allows 5 requests per second per base. TrailSpark throttles requests automatically to stay within this limit. Large bases with thousands of records may take longer to process during SparkSense analysis.

## Reconfiguring

To change your table mapping after the initial setup:

1. Go to **Settings** > **CRM Integration**
2. Click **Reconfigure Tables** on the Airtable card
3. Update your table and field selections
4. Click **Save Table Mapping**

Your field mapping configuration (configured on the **Field Mapping** tab in **Settings** > **CRM Integration**) is preserved when you reconfigure tables.

## Disconnecting

To disconnect Airtable, go to **Settings** > **CRM Integration** and click **Disconnect**. Existing data remains in TrailSpark. If you used OAuth, you can also revoke access from your [Airtable account settings](https://airtable.com/account).

## Troubleshooting

### "No CRM data found" in SparkSense

- Verify your Deals table has records with a **Close Date** within the past 180 days
- Confirm the **Stage Field** and **Close Date Field** are mapped correctly in table configuration
- Check that the **Deal → Contact Link** field points to your Contacts table

### Empty results after connecting

- Ensure the base you selected actually contains data in the mapped tables
- If using a PAT, verify the token has `data.records:read` and `schema.bases:read` scopes
- If using OAuth, verify you granted access to the correct base during authorization

### Field data not appearing in evaluations

- Check [Field Mapping](/docs/field-mapping) to ensure your Airtable fields are mapped to the correct TrailSpark fields
- If your field names don't match the common variants listed above, explicit field mapping is required

### "Rate limit exceeded" errors

Airtable limits API requests to 5 per second. If you see rate limit errors, wait a moment and retry. TrailSpark handles throttling automatically, but concurrent usage from other Airtable integrations can consume your quota.

## Next Steps

- [Field Mapping](/docs/field-mapping) -- configure how Airtable fields map to TrailSpark
- [Airtable Destination](/docs/airtable-destination) -- write evaluation results back to Airtable