TOOL API

search_candidate_linked_records

Searches for records that are valid candidates for a linked-record (foreign-key) field, returning each candidate's record ID along with the fields the linked-record field is configured to display (the same fields shown on the in-product card). Use this to find the record ID to put in a linked-record field when calling submit_form or update_records_for_table. Use list_pages_for_base to find the pageId if needed. Use get_form_schema (for forms) to discover the linked field's fieldId. Pass the fieldId of the linked-record field you are filling (not the table it links to — the foreign table is resolved automatically). The pageId must be a page that surfaces the linked field: for submit_form this is the form's pageId; for update_records_for_table pass the interface page that shows the record/field being edited. Pass interfaceId when the page lives inside an interface; omit it for a standalone form. A linked-record field's candidates can be restricted by dynamic filters that reference the record's OTHER field values, so you must supply those values for the filters to apply: when filling a NEW record (e.g. for submit_form), always pass fields with the other values you have so far or plan to submit; when editing an EXISTING record, pass recordId, plus fields for any other values you are changing in the same update (a value in fields takes precedence over the record's stored value; anything not in fields falls back to the stored value). If you pass neither, the filters are evaluated against blank values and the results may include records that are not actually selectable, or miss ones that are.

productivityOAuth1 credits

Call information

Tool slug: airtable.search_candidate_linked_records
Provider: Airtable
Average response: 0 ms
Calls in 7 days: 0

Input parameters

baseIdrequired

The ID of the base containing the page and the linked-record field. Must start with "app" and is 17 characters long. Example: "appZfrNIUEip5MazD". Do not substitute user-facing names for baseId. To get baseId, use the search_bases or list_bases tool.

pageIdrequired

The ID of the page that surfaces the linked-record field. Must start with "pag" and is 17 characters long. Example: "pagXxYyZzAaBbCcDd".

interfaceId

The ID of the interface containing the page, or null/omitted for a standalone form (one that is not inside an interface). Must start with "pbd" and is 17 characters long.

fieldIdrequired

The ID of the linked-record (foreign-key) field whose candidate records you want to search. Field IDs must start with "fld" and is 17 characters long. Example: "fldGlRtkBNWfYnPOV". Do not substitute user-facing names for IDs. To get fieldId, use the list_tables_for_base tool.

queryrequired

The text to search candidate records by. Matching is case-insensitive against each record's display name. Pass an empty string to list candidates without filtering.

limit

The maximum number of records to return. The server may return fewer. Defaults to a small page size when omitted.

fields

The values entered so far (or planned) for the OTHER fields of the record being filled. The linked field's cross-field dynamic record-selection filters are evaluated against these values, and omitting them can return records that are not actually selectable. When searching candidates for a new record (e.g. a submit_form submission), always pass every other field value you know. When editing an existing record (recordId provided), pass the values you are changing in the same update — each value here overrides the record's stored value, and fields not passed fall back to the stored values. Field IDs must start with "fld" and is 17 characters long. Example: "fldGlRtkBNWfYnPOV". Do not substitute user-facing names for IDs. To get fieldId, use the list_tables_for_base tool.

recordId

The ID of the EXISTING record being updated, when searching linked records in the context of an existing record (e.g. for update_records_for_table). The record's stored values are used to apply the linked field's cross-field dynamic record-selection filters, except for values you also pass in fields, which take precedence — so pass both when the update changes a value those filters depend on. Must start with "rec" and is 17 characters long. Example: "recZOTa3BDHxlJNzf". Do not substitute user-facing names for IDs To get recordId, use the list_records_for_table tool or display_records_for_table tools.