# Connecting Airtable

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

## Overview

The Airtable connection is a two-stage flow: first authenticate (OAuth or Personal Access Token), then map your tables. The table mapping step tells Trailspark which of your Airtable tables contain contacts, companies, and deals — Airtable's open schema means Trailspark can't infer this on its own.

## Prerequisites

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

## Stage 1: Authenticate

### Option 1: OAuth (Recommended)

1. Go to **Settings** > **CRM Integration**
2. Click **Connect Airtable** on the Airtable card
3. On the **Airtable Configuration** page, click **Connect with OAuth**
4. Airtable opens and asks you to authorize Trailspark
5. Select the workspace and bases to grant access to, then click **Grant access**

You are redirected back to Trailspark to proceed with table mapping.

### Option 2: Personal Access Token

If your organization restricts OAuth connections, use a Personal Access Token (PAT).

**Create a token in Airtable:**

1. Go to [airtable.com/create/tokens](https://airtable.com/create/tokens) (or **Account** > **Developer hub** > **Personal access tokens**)
2. Click **Create new token**
3. Name the token (e.g., "Trailspark Integration")
4. Under **Scopes**, add:
   - `data.records:read`
   - `schema.bases:read`
5. Under **Access**, add the base that contains your CRM data
6. Click **Create token** and copy it immediately — Airtable only shows it once

**Enter the token in Trailspark:**

1. On the **Airtable Configuration** page, paste the token into the **Personal Access Token** field
2. Click **Save Token**

> [!TIP]
> OAuth handles token refresh automatically. Personal Access Tokens must be regenerated manually if they expire or are revoked.

## Stage 2: Map Tables

After authenticating, Trailspark shows the **Map Airtable Tables** wizard. This step maps your Airtable tables to the CRM object types Trailspark expects.

### Select a Base

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

### Map Core Tables

| Table Mapping | Required | Description |
| - | - | - |
| **Contacts Table** | Yes | The table containing people or leads |
| **Companies Table** | Yes | The table containing organizations or accounts |
| **Deals Table** | No | The table containing deals or opportunities |

After selecting Contacts and Companies, you can also set the **Contact-to-Company Link Field** (Recommended) — a linked record field on the Contacts table that connects each contact to their company.

### Configure Deal Fields

If you select a Deals table, additional fields appear for deal metadata:

| Field | Required | Description |
| - | - | - |
| **Deal → Contact Link Field** | Yes | Linked record field on Deals connecting to Contacts |
| **Deal → Company Link Field** | No | Linked record field on Deals connecting to Companies |
| **Contact → Deals Link Field** | Recommended | Linked record field on the Contacts table that connects back to Deals — used for contact-based deal lookups |
| **Won Indicator Field** | Recommended | The field that marks a deal as won — supports date, checkbox, or text/select field types |
| **Close Date Field** | Required (if Won Indicator is not a date) | The field containing the deal close date |
| **Stage Field** | No | The field containing deal stage, for display and filtering |
| **Amount / Value Field** | Recommended | The field containing deal value, for deal size calculations |

**Won Indicator behavior by field type:**

- **Checkbox** — a deal is won when the checkbox is checked
- **Date / DateTime** — a deal is won when the field has a value; that date is also used as the close date
- **Single Select / Text** — enter the values that mean won (e.g., `Closed Won, Won`) in the **Won Values** field that appears

### Save

Click **Save Table Mapping**. Trailspark validates the configuration and confirms it is saved. The **Field Mapping** and **Destinations** tabs on the main CRM Integration page become available.

To reconfigure tables later, click **Reconfigure Tables** on the **Connect** tab, or go back to **Settings** > **Integrations** > **Airtable** and click **Reconfigure Table Mapping**.

## After Connecting

Trailspark fetches your Airtable field schema after table mapping is saved. Open the **Field Mapping** tab to map your Contacts and Companies fields to Trailspark's scoring fields.

If your Airtable schema changes, click **Refresh Fields** on the **Connect** tab to pull the latest field list.

## Troubleshooting

### "Table Mapping Required" alert on the Connect tab

Table mapping was not completed after authenticating. Click **Configure Tables** to run the mapping wizard.

### Empty results after connecting

- Confirm the base you selected contains records in the mapped tables
- If using a PAT, verify it has both `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

Open **Field Mapping** to confirm your Airtable fields are mapped to the correct Trailspark fields. Airtable's open schema means Trailspark cannot auto-detect fields that use non-standard names.

### "No closed-won deals found"

- Confirm the **Won Indicator Field** is configured and points to the correct field
- For text/select won indicators, verify the **Won Values** list includes the exact strings used in your data (e.g., `Closed Won` not `closed won`)
- If your won indicator is a date field, Trailspark expects the field to have a non-null value for won deals

## Next Steps

- [Field Mapping](https://docs.trailspark.ai/crm-integration/field-mapping) — map Airtable fields to Trailspark's scoring fields
- [Buying Groups Overview](https://docs.trailspark.ai/buying-groups/buying-groups-overview) — how Trailspark uses contact data for role detection
- [Destinations Overview](https://docs.trailspark.ai/destinations-rules/destinations-overview) — write evaluation results back to Airtable