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)
- Go to Settings > CRM Integration
- Click Connect on the Airtable card
- You will be redirected to Airtable to authorize TrailSpark
- Select the workspace and bases to grant access to
- 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
- Go to airtable.com/create/tokens (or navigate to Account > Developer hub > Personal access tokens)
- Click Create new token
- Give the token a name (e.g., "TrailSpark Integration")
- Under Scopes, add:
data.records:read-- read records from your baseschema.bases:read-- read table and field schema
- 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
- Click Create token
- Copy the token immediately -- Airtable only shows it once
Enter the token in TrailSpark
- Go to Settings > CRM Integration > click Connect on Airtable
- On the Airtable config page, choose Use Personal Access Token
- Paste the token and click Save Token
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 |
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.
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 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:
- Go to Settings > CRM Integration
- Click Reconfigure Tables on the Airtable card
- Update your table and field selections
- 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.
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:readandschema.bases:readscopes - If using OAuth, verify you granted access to the correct base during authorization
Field data not appearing in evaluations
- Check 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 -- configure how Airtable fields map to TrailSpark
- Airtable Destination -- write evaluation results back to Airtable