Airtable Integration

The Airtable integration allows you to automatically save form submissions to your Airtable base, creating structured records that you can organize, filter, and visualize.

Overview

When a form is submitted, Axiforms will:

1. Connect to Airtable using OAuth (no manual token entry needed)
2. Map form fields to Airtable fields
3. Create a new record with the submission data
4. Handle different field types automatically (text, email, number, date, etc.)

Setting Up Airtable Integration

Step 1: Connect Your Airtable Account

1. Navigate to your form's Settings → Integrations
2. Click on Airtable
3. Click Connect to Airtable
4. You'll be redirected to Airtable to authorize Axiforms
5. Grant access to the bases you want to use
6. You'll be redirected back to Axiforms

Step 2: Select a Base

1. After connecting, you'll see a dialog to select a base
2. Click Choose Base to see your available bases
3. Select a base from the list
4. Or enter the Base ID manually if you prefer

To find your Base ID:

• Open your Airtable base
• Look at the URL: https://airtable.com/{BASE_ID}/...
• Copy the {BASE_ID} part (usually starts with app)

Step 3: Select a Table

1. After selecting a base, choose a table from the dropdown
2. The table should already have the fields you want to map to

Step 4: Map Form Fields

1. Click Add Field to start mapping

2. For each form field:

   • Select the Form Field from your form
   • Select the Airtable Column from the dropdown (you'll see the column type displayed, e.g., "Name (Text)", "Status (Single select)")
   • The column type is shown next to each column name to help you choose the right one

3. Enable the integration

4. Click Create Integration or Update Integration

Note: The dropdown shows all available columns from your selected table, along with their types (Text, Single select, Number, etc.) to help you make the correct mapping.

Field Mapping

How Field Mapping Works

Field mappings connect your form responses to Airtable columns. The integration is flexible - you can map any form field to any Airtable column type, and values will be automatically converted to match the column's type.

Key Points:

• Form Field: The field from your Axiforms form (e.g., Short text, Email, Number, etc.)
• Airtable Column: The column in your Airtable table (you select from a dropdown)
• Column Type: Shown in the dropdown (e.g., "Status (Single select)", "Name (Text)")
• Value Conversion: Values are automatically formatted according to the Airtable column type, not the form field type

Flexible Mapping

The integration respects your existing Airtable column types. For example:

• You can map a text field to a Single select column - the text value will be used as the select option
• You can map a number field to a Number column - values are converted to numbers
• You can map a text field to a Text column - values are saved as strings
• You can map multiple choice to a Multiple select column - arrays are handled automatically

Example Mapping

Value Conversion Rules

The integration automatically converts values based on the Airtable column type:

• Text columns: Any value converted to string
• Single select: Text value must match an existing option exactly (case-insensitive matching)
  • If value doesn't match, the field is skipped (not saved) to prevent Airtable API errors
• Multiple select: Array values saved as multiple selections (each value must match an option)
• Number columns: Numeric values converted to numbers
• Email columns: Email addresses validated
• Date columns: Dates formatted to ISO 8601
• Checkbox columns: Boolean values (true/false)

Important: Single Select Validation

Single select columns require exact option matching:

• Form values must match one of the options defined in Airtable
• Matching is case-insensitive (e.g., "Active" matches "active")
• If a value doesn't match any option, the field is skipped (not saved) and a warning is logged
• This prevents Airtable API errors and ensures data integrity

Example:

• Airtable Status column has options: "Todo", "In Progress", "Done"
• Form submits: "Planned" → Field is skipped (not saved)
• Form submits: "Todo" → Field is saved as "Todo"
• Form submits: "todo" → Field is saved as "Todo" (case-insensitive match)

Best Practice: Use a Text column if you need flexible values that don't match predefined options, or ensure your form values match the Airtable options.

Creating Fields in Airtable

Recommended: Create all Airtable columns before mapping:

1. Open your Airtable base
2. Go to the table you want to use
3. Add columns if needed (click the "+" button)
4. Set the correct column types (Text, Single select, Number, Date, etc.)
5. Column names are selected from a dropdown, so they must exist in your table

Auto-Creation: If a mapped column doesn't exist, Axiforms will automatically create it with a sensible default type (usually "Text" for flexibility). However, it's better to create columns manually to ensure the correct types.

How Value Conversion Works

Understanding Column Types

The integration uses the Airtable column type to determine how to format values. When you select a column in the mapping dropdown, you'll see its type displayed (e.g., "Name (Text)", "Status (Single select)").

Important: Values are converted based on the Airtable column type, not your form field type. This means you have flexibility in mapping:

• A text form field → Single select column (text value used as option)
• A number form field → Number column (value converted to number)
• A text form field → Text column (value saved as string)
• Multiple choice → Multiple select (array saved as selections)

Supported Airtable Column Types

The integration handles these Airtable column types:

Text Columns

• Text: Plain text values (single line)
• Long text: Multi-line text values
• URL: URL values
• Phone: Phone number values
• Any text value is converted to string

Selection Columns

• Single select: Text value used as the select option (must match an existing option)
  • Important: If the value doesn't match any existing option in Airtable, the field will be skipped (not saved) to prevent errors
  • Example: If Airtable has options "Todo", "In Progress", "Done", but form submits "Planned", the field will be skipped
  • Solution: Ensure form values match Airtable options exactly, or use a Text column instead
• Multiple select: Array values saved as multiple selections
  • Each value in the array must match an existing option (mismatched values are skipped)

Numeric Columns

• Number: Numeric values (integers and decimals)
• Currency: Currency values
• Percent: Percentage values
• Rating: Rating values
• Numeric values are converted appropriately

Date Columns

• Date: Date values (ISO 8601 format)
• Date & Time: Date with time
• Dates are formatted to ISO 8601

Other Columns

• Email: Email addresses (validated)
• Checkbox: Boolean values (true/false)
• Attachments: File attachments (URLs or attachment objects)

Data Format

Record Structure

When a record is created, it contains:

{
  "fields": {
    "Name": "John Doe",
    "Email": "john@example.com",
    "Score": 85,
    "Submitted": "2024-01-15T10:30:00.000Z"
  }
}

Value Conversion Examples

Here's how different form values are converted based on Airtable column types:

Text to Single Select

• Form value: "Active" (text field)
• Airtable column: Status (Single select with options: "Active", "Inactive", "Pending")
• Result: "Active" (used as select option - must match exactly)
• If value doesn't match: If form submits "Planned" but Airtable only has "Active", "Inactive", "Pending", the field will be skipped (not saved) to prevent Airtable API errors

Text to Number

• Form value: "42" (text field)
• Airtable column: Score (Number)
• Result: 42 (converted to number)

Multiple Choice to Multiple Select

• Form value: ["Option A", "Option B"] (multiple choice)
• Airtable column: Tags (Multiple select)
• Result: ["Option A", "Option B"] (saved as array)

Text to Text

• Form value: "John Doe" (text field)
• Airtable column: Name (Text)
• Result: "John Doe" (saved as string)

Empty Values

• Empty or null values: Saved as null or omitted from the record

Security

OAuth Security

• Automatic token management: Axiforms handles token refresh automatically
• Scope limitation: You control which bases Axiforms can access during OAuth
• Revoke access: You can revoke access at any time from Airtable settings
• No manual token handling: No need to manage tokens manually

Best Practices

1. Grant access only to the bases you need
2. Regularly review connected apps in Airtable settings
3. Revoke access if you no longer use the integration

Troubleshooting

"Failed to create record" error

Possible causes:

• Column name doesn't exist in Airtable table
• Invalid value for column type (e.g., non-numeric value for Number column)
• Invalid field value (e.g., invalid email format for Email column)
• OAuth connection doesn't have write permissions
• Base ID or table name is incorrect
• Single select value doesn't match an existing option (field will be skipped, not saved)

Solutions:

1. Verify the column exists in your Airtable table (use the dropdown to select it)
2. Check that values can be converted to the column type:
   • Text values → Text columns (OK)
   • Text values → Single select columns (only if value matches an existing option)
   • Numeric values → Number, Currency columns (OK)
   • Text values → Number columns (only if text is numeric)
   • Single select: If value doesn't match any option, the field will be skipped (not saved) - check logs for warnings
3. Ensure OAuth connection has all required permissions
4. Verify base ID and table name are correct
5. Check Airtable API rate limits (5 requests per second)

Single Select Value Mismatch

Problem: Your form submits a value that doesn't match any option in an Airtable Single select column.

Example:

• Airtable Status column has options: "Todo", "In Progress", "Done"
• Your form submits: "Planned"
• Result: The Status field is skipped (not saved) to prevent Airtable API errors

What happens:

• The integration validates the value against available options
• If no match is found, the field is skipped (not saved)
• A warning is logged: Value "Planned" doesn't match any option in single select field
• The record is still created, but without that field

Solutions:

1. Update your form values to match Airtable options:

   • Change form options to match Airtable: "Todo", "In Progress", "Done"
   • Or use a dropdown/select field in your form with matching options

2. Update Airtable options to include the form value:

   • Add "Planned" as an option in your Airtable Single select column
   • Then future submissions with "Planned" will work

3. Use a Text column instead:

   • Change the Airtable column from Single select to Text
   • This allows any value to be saved (no validation)

4. Check matching rules:

   • Matching is case-insensitive: "Todo" matches "todo" or "TODO"
   • The value must match exactly (after case normalization)
   • Whitespace matters: "In Progress" ≠ "InProgress"

OAuth connection issues

If connection fails:

• Ensure you have an Airtable account
• Check that you granted all required permissions
• Try disconnecting and reconnecting
• Verify Axiforms is not blocked by your organization's security policies

Field mapping errors

If specific fields aren't saving:

• Verify the column exists in your Airtable table (use the dropdown to see available columns)
• Check that values can be converted to the column type:
  • For Single select: Ensure the value matches an existing option in Airtable (case-insensitive)
    • If value doesn't match, the field will be skipped (check server logs for warnings)
    • See "Single Select Value Mismatch" section below for detailed solutions
  • For Number: Ensure the value is numeric (or can be converted to a number)
  • For Email: Ensure the value is a valid email format
• Check the column type displayed in the dropdown matches your expectations
• If auto-created, the column might have the wrong type - create it manually in Airtable with the correct type

Rate limiting

Airtable has API rate limits:

• 5 requests per second per base
• Axiforms handles rate limiting automatically
• Multiple submissions may queue briefly during high traffic

Best Practices

1. Pre-create columns: Create all Airtable columns before mapping to ensure correct types
2. Use the dropdown: Always select columns from the dropdown to see available options and types
3. Check column types: Pay attention to the column type shown in the dropdown (e.g., "Status (Single select)")
4. Understand value conversion: Remember that values are converted based on the Airtable column type, not your form field type
5. Match single select values: For Single select columns, ensure form values match existing options in Airtable
6. Test mappings: Submit a test form before going live to verify data is saved correctly
7. Monitor records: Check your Airtable base regularly to ensure data is flowing correctly
8. Set up views: Create filtered views in Airtable for easier data analysis

Mapping Tips

• Text fields are flexible: Text form fields can be mapped to Text, Single select, or other text-based columns
• Single select requires matching: When mapping to Single select columns, ensure form values match the Airtable options exactly
  • If values don't match, the field will be skipped (not saved)
  • Consider using a Text column if you need flexible values
• Numbers must be numeric: Map number fields to Number columns, or ensure text values can be converted to numbers
• Arrays for multiple selects: Multiple choice or checkbox fields work well with Multiple select columns
• Dates are auto-formatted: Date fields are automatically formatted to ISO 8601 for Date columns

Advanced Usage

Multiple Forms, One Base

Use the same Airtable base for multiple forms:

1. Create separate tables for each form
2. Configure each form to use its own table
3. Or use a single table with a "Form Name" field to distinguish submissions

Linked Records

To create linked records in Airtable:

1. Create a lookup field in your table
2. Map form values to the linked record field name
3. Ensure the value matches an existing record ID or name

Formulas and Automation

Leverage Airtable features:

• Formula fields: Calculate values based on other fields
• Automations: Trigger workflows when records are created
• Views: Create filtered and sorted views
• Interfaces: Build custom interfaces for viewing data

Column Type Best Practices

When creating columns in Airtable:

• Email columns: Use Email type for email addresses (values are validated)
• Date columns: Use Date or Date & Time for proper date handling (auto-formatted to ISO 8601)
• Number columns: Use Number type for calculations and sorting (values converted to numbers)
• Single select columns: Use for fixed options (form values must match existing options)
• Multiple select columns: Use for tags, categories, or multiple selections (arrays supported)
• Text columns: Use for flexible text values (most flexible, accepts any text)

Remember: The integration uses your Airtable column type to format values, so choose column types that match how you want the data stored.

API Reference

Axiforms uses the Airtable REST API to create records:

POST https://api.airtable.com/v0/{baseId}/{tableName}
Authorization: Bearer {personal_access_token}
Content-Type: application/json

{
  "fields": {
    "Field Name": "value"
  }
}

For more information, see the Airtable API documentation.