TrailSpark

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 (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
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 MappingRequiredDescription
Contacts TableYesThe table containing people or leads
Companies TableYesThe table containing organizations or accounts
Deals TableNoThe 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:

FieldRequiredDescription
Deal → Contact Link FieldYesLinked record field on Deals connecting to Contacts
Deal → Company Link FieldNoLinked record field on Deals connecting to Companies
Contact → Deals Link FieldRecommendedLinked record field on the Contacts table that connects back to Deals — used for contact-based deal lookups
Won Indicator FieldRecommendedThe field that marks a deal as won — supports date, checkbox, or text/select field types
Close Date FieldRequired (if Won Indicator is not a date)The field containing the deal close date
Stage FieldNoThe field containing deal stage, for display and filtering
Amount / Value FieldRecommendedThe 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