Response field mapping

Response field mapping is where you control which data from your API response gets imported into Airtable and how it maps to your table's fields.

Set up response field mapping

Initial setup

When you create a request for the first time:

1. Click Save & Run on your request configuration.

2. The Response Field Mapping modal will open, showing all available fields from the API response along with a preview of the records.

Map your fields

For each response field, you can:

• Select or deselect fields - Only data from selected fields will be imported when the request runs.

• Map to existing fields - Select Existing field and choose a field from the dropdown to use an existing column in your table.

• Map to new fields - Select New field, enter a field name, and choose a field type. Data Fetcher automatically suggests appropriate field types based on the response data.

• Search for fields - Use the Find field input to quickly locate specific fields in large responses.

Once you've configured your mappings, click Save & Run. Data Fetcher will create any new fields and import your data.

Managing field mappings

Reopen field mapping

After your initial setup, you can modify field mappings anytime by clicking Open field mapping on your request.

Refresh fields

When your API response changes (for example, due to parameter updates), you can refresh available fields without using your monthly usage limits:

1. Click Open field mapping.

2. Click Refresh fields in the top-right corner.

The field mappings also refresh automatically when you change Response data transformations, Response JMESPath, or Max response records.

Additional field options

Transform data with formulas

Apply transformations to field values before they reach your output table using formulas. Reference the original value as value in your formula (e.g., upper(value)).

1. Click the settings icon next to any field to open field settings.

2. Enter your formula in the Formula input.

3. Click Save.

You can find a full list of available formulas here and test them in our JavaScript Formula Playground.

Create linked records

Data Fetcher can automatically create and update linked records during imports. This is useful when you have related data, such as tasks linked to users.

Use an existing linked field:

1. Select Existing field and choose a linked field from your output table.

2. By default, Data Fetcher uses the primary field in the linked table to find records. To change this, click the field settings icon and select a different field under Linked table field.

Create a new linked field:

1. Select New field, enter a field name, and set the field type to Link.

2. Click the field settings icon and select a table to link to under Linked table.

When the request runs, Data Fetcher will create links by looking for response values in the linked table. If no matching record is found, it will create a new record automatically.

Link to multiple records

Enable comma-separated values to create multiple linked records:

1. Click the field settings icon next to the field name.

2. Under Allow multiple links, select Allow.

Create missing linked records

By default, Data Fetcher creates missing records in linked tables. You can disable this for read-only tables:

1. Click the settings icon next to the field name.

2. Under Create missing records, enable or disable Create.

Handle attachment fields

Map remote file URLs (PNG, SVG, PDF, etc.) directly to Airtable attachment fields by selecting Attachment as the field type.

Add to existing attachments instead of overwriting:

1. Click the settings icon next to the attachment field.

2. Under Attachment write mode, enable Add to existing.

3. Click Save.

Only write if cell is empty:

1. Click the settings icon next to the attachment field.

2. Under Write the attachment only if the cell is empty, enable Only if empty.

3. Click Save.

Working with response data

View raw response

Data Fetcher converts API responses into tabular format, but you can view the original JSON or XML:

1. Click the settings sidebar icon (➡️) on the left side.

2. Click Response preview to display the raw response.

For JSON responses: Click any value to toggle whether it's imported. Click the arrow next to field names to navigate directly to that field in the response.

Note: For paginated requests and Run on Multiple Record requests, the response field mapping shows only the first request's response data.

Copy or download response

You can copy the JSON response to your clipboard or download it, which is helpful when working with JMESPath expressions:

1. Click the settings sidebar icon (➡️) on the left side.

2. Click Response preview.

3. Click Copy or Download.

Access advanced settings

You can access the Advanced settings in the Response Field Mapping settings side bar:

1. Click the settings sidebar icon (➡️) on the left side.

2. Click Advanced settings.

3. Make changes to Response data transformations, Response JMESPath, or Max response records and see the effects straight away.

Troubleshooting tips

• Data Fetcher suggests field types based on response data, but you can modify these suggestions (for example, changing from Number to Currency)

• Be cautious when changing suggested data types, as incompatible values can cause import errors (for example, mapping text like "sdlf3421asd" to a Number field will fail)