DEV Community

Rahul Sharma
Rahul Sharma

Posted on

CF7 to Airtable Linked Record Field Not Populating: A Complete Troubleshooting Guide

You have connected Contact Form 7 to Airtable through the "Contact Form to Any API" plugin. Standard fields populate correctly: the Name, Email, and Message columns fill in as expected. But the linked record field the one that should connect this new record to an existing record in another table stays empty.

Or worse, Airtable returns an INVALID_RECORD_ID error, even though you are certain the record ID is correct.

This is one of the most common and confusing failures in Airtable integrations. The problem is not authentication. It is not the endpoint URL. It is the payload format for linked record fields, which is fundamentally different from every other field type.

This guide explains exactly why linked record fields fail and how to format the payload correctly.

Why Linked Record Fields Are Different

Airtable's linked record field does not store text. It stores an array of record IDs from the target table. Each ID is a string like recXE6yQpMi1NyWRx.

The confusion arises because Airtable's API accepts the record ID in two different formats depending on context:

For the Web API (which the plugin uses): The value must be an array of record ID strings: ["recXE6yQpMi1NyWRx"].

For Airtable's scripting environment or certain middleware tools: The value is an array of objects: [{"id": "recXE6yQpMi1NyWRx"}].

If you use the object format in a Web API request which is what the plugin sends Airtable rejects the request with INVALID_RECORD_ID, even though the ID itself is correct.

This is the single most common reason linked record fields fail to populate.

Failure #1: The Payload Uses the Wrong Array Format

What you see: Airtable returns an INVALID_RECORD_ID error, or the linked record field is created but empty.

Why it happens: You are sending the record ID as an object ([{"id": "recXXX"}]) instead of a plain string array (["recXXX"]). The Web API expects the string array format.

The fix:

In the plugin's JSON Payload configuration, the linked record field must be formatted as a simple array of strings:

{
  "fields": {
    "Your_Linked_Field_Name": ["recXE6yQpMi1NyWRx"]
  }
}
Enter fullscreen mode Exit fullscreen mode

Not:

{
  "fields": {
    "Your_Linked_Field_Name": [{"id": "recXE6yQpMi1NyWRx"}]
  }
}
Enter fullscreen mode Exit fullscreen mode

The second format is used in Airtable's scripting API and in some middleware tools, but it is not valid for direct Web API calls.

How to verify: After updating the payload format, submit a test form. Check the plugin's API Logs. A 200 OK response with the linked field populated means the format is correct.

If no request appears in the logs at all, the problem is earlier in the pipeline. For a deeper breakdown of that scenario, see this guide on Contact Form 7 data not reaching the API.

Failure #2: The Record ID Is Not Actually Correct

What you see: Airtable returns INVALID_RECORD_ID. You are certain the ID is correct, but the API disagrees.

Why it happens: The record ID you are using may belong to a different table, or the record may have been deleted. Airtable record IDs are table-specific. A valid ID from Table A will fail if used in a linked field pointing to Table B.

Additionally, if you are passing the record ID through a CF7 hidden field, verify that the value is not being truncated or altered by form processing.

The fix:

Step 1: In Airtable, open the target table (the table the linked field points to). Click on the record you want to link. The record ID is visible in the URL or in the record detail panel. It starts with rec.

Step 2: Copy the ID exactly. Do not add spaces, quotes, or brackets inside the string.

Step 3: If the ID is coming from a CF7 field, test the form with a hardcoded record ID first. Replace the CF7 tag with the literal ID:

{
  "fields": {
    "Linked_Record": ["recXE6yQpMi1NyWRx"]
  }
}
Enter fullscreen mode Exit fullscreen mode

If the hardcoded version works but the CF7 tag version does not, the problem is with how the field value is being passed or formatted.

For a deeper dive into JSON structure mapping and field value formatting, read this guide on Contact Form 7 JSON mapping.

Failure #3: The Linked Field Name Is Wrong

What you see: The record is created, but the linked field is empty. No error is returned.

Why it happens: Airtable silently ignores fields that do not exist on the table. If the field name in your payload does not match the exact field name in Airtable including capitalization and spacing the value is discarded.

The fix:

Step 1: In Airtable, open the table and check the exact field name. Copy it exactly as shown.

Step 2: Update the JSON Payload key to match. The key must be the field name, not the field ID, unless you are using field IDs explicitly.

For example, if the field is named Linked Project, your payload must use "Linked Project", not "linked_project" or "LinkedProject".

Step 3: Submit a test form and verify the link populates.

Failure #4: The Plugin Is Sending the Wrong Content-Type

What you see: Airtable returns a 400 Bad Request error with a message about invalid request format.

Why it happens: Airtable's API requires Content-Type: application/json. If the plugin is configured to send form-encoded data or another content type, Airtable rejects the request.

The fix:

In the plugin's Request Headers configuration, ensure the following header is present:

Content-Type: application/json
Enter fullscreen mode Exit fullscreen mode

This header must be set explicitly. Some API integrations default to a different content type, which causes Airtable to reject the payload before it even evaluates the linked record field.

For a comprehensive breakdown of authentication headers and content types across different APIs, see this guide on Contact Form 7 API authentication errors.

The Debugging Checklist

Step Action What It Reveals
1 Check the plugin's API Logs Was a request sent? What response code and body?
2 Verify the payload format for the linked field Is it ["recXXX"] or [{"id": "recXXX"}]?
3 Test with a hardcoded record ID Isolates CF7 field mapping issues from format issues
4 Verify the record ID against the target table Is the ID valid for the linked table?
5 Check the field name exact match Does the payload key match the Airtable field name?
6 Verify Content-Type header Is it application/json?

Beyond the Link: One Form, Multiple Destinations

Once your Airtable linked record integration works, you might want to send the same submission to other tools: a CRM, an email marketing platform, or a project management board.

A good connector plugin supports multiple API integrations from a single form submission. You can create an Airtable record with linked fields, add a HubSpot contact, and create a Monday.com item, all from one CF7 submission. For a cost comparison, see this article on Zapier vs a dedicated API plugin.

Key Takeaways

Airtable's Web API expects linked record values as a string array: ["recXXX"], not [{"id": "recXXX"}].

The object format is for Airtable's scripting environment, not the Web API. Using it in the plugin payload causes INVALID_RECORD_ID errors.

The record ID must belong to the target table. A valid ID from a different table will fail.

Field names must match exactly. Airtable silently ignores fields that do not exist on the table.

Start with a hardcoded record ID. Once the link works with a literal ID, replace it with the CF7 tag to isolate mapping issues.

With the correct array format, a valid record ID from the target table, and an exact field name match, your CF7 submissions will populate Airtable linked record fields reliably.

Top comments (0)