Workflow lookups
Choose the fields workflows use to find rows and preview the returned values.
Add lookup
POST /v1/lookup-tables/{table_id}/definitions
Lets workflows find rows by one field's value, at the table version you read. Every row must have a different value in that field, and the field's type is locked for good. This can't be undone. A large table's lookup is answered with 202: get the settings until pending_work is null.
Requires lookup_tables:config:write. The connection also needs access to the relevant tables, objects, or workflows.
MCP action: create_lookup. Its argument names match the fields below; an HTTP header is passed using its argument name in MCP.
Parameters
| Name | Send in | Required | Type or allowed values | Notes |
|---|---|---|---|---|
table_id |
path | Yes | string | |
expected_version |
JSON body | Yes | integer | |
field_id |
JSON body | Yes | string (uuid) | |
request_key |
Header: Idempotency-Key |
Yes | string |
Response
| HTTP status | Result |
|---|---|
200 |
The requested result. Asynchronous work returns an operation to poll. |
202 |
The requested result. Asynchronous work returns an operation to poll. |
Required fields are required within their containing object. Notes identify fields that apply only to a particular response alternative.
| Response field | Type | Required in object | Notes |
|---|---|---|---|
data |
object | Yes | |
data.object |
"lookup_table_configuration" |
Yes | |
data.id |
string | Yes | |
data.name |
string | Yes | |
data.kind |
"generic", "member_metadata", "status_metadata", "app_owned" |
Yes | |
data.version |
integer | Yes | |
data.fields |
array of object | Yes | |
data.fields[].object |
"lookup_field" |
Yes | |
data.fields[].id |
string | Yes | |
data.fields[].key |
string | Yes | |
data.fields[].name |
string | Yes | |
data.fields[].type |
"text", "number", "boolean", "date", "timestamp", "email", "phone", "domain", "url", "member", "record" |
Yes | |
data.fields[].workflow_readable |
boolean | Yes | |
data.fields[].managed_by |
"customer", "attio", "slack", "system" |
Yes | |
data.fields[].type_locked |
boolean | Yes | |
data.fields[].version |
integer | Yes | |
data.lookups |
array of object | Yes | |
data.lookups[].object |
"lookup_definition" |
Yes | |
data.lookups[].id |
string | Yes | |
data.lookups[].field_id |
string | Yes | |
data.lookups[].default |
boolean | Yes | |
data.pending_work |
object or null | Yes | |
data.pending_work.kind |
"starter", "lookup_key", "field_type" |
Yes | When data.pending_work.kind is "starter", "lookup_key", "field_type". |
data.pending_work.state |
"running", "failed" |
Yes | When data.pending_work.kind is "starter", "lookup_key", "field_type". |
data.pending_work.problem |
string or null | Yes | When data.pending_work.kind is "starter", "lookup_key", "field_type". |
data.import_id |
string or null | Yes |
Accepted work can continue after the request returns. Follow its returned status or operation until it finishes; accepting work does not mean every item succeeded. See operation status.
Errors
| HTTP status | Meaning |
|---|---|
400 |
One of: credential_in_url, invalid_parameter, unknown_parameter, invalid_request. |
401 |
One of: missing_credential, invalid_credential, credential_expired, credential_revoked. |
402 |
One of: payment_overdue. |
403 |
The current permissions, plan or policy do not allow this request. |
404 |
One of: not_found. |
409 |
The request conflicts with current resource state, authorization or an earlier request. Read the error code and current resource before retrying. |
410 |
The requested resource or retained recovery data has expired. |
413 |
One of: request_too_large. |
422 |
A field, filter or selection cannot be used for this request. |
423 |
One of: organization_reopening. |
428 |
One of: customer_agreement_required. |
429 |
One of: rate_limited. |
503 |
One of: service_unavailable. |
See errors and recovery and safe retries before repeating a write.
Remove lookup
DELETE /v1/lookup-tables/{table_id}/definitions/{definition_id}
Removes a lookup, at the table version you read. Workflow steps that use it stop finding rows. This can't be undone.
Requires lookup_tables:config:write. The connection also needs access to the relevant tables, objects, or workflows.
MCP action: delete_lookup. Its argument names match the fields below; an HTTP header is passed using its argument name in MCP.
Parameters
| Name | Send in | Required | Type or allowed values | Notes |
|---|---|---|---|---|
table_id |
path | Yes | string | |
definition_id |
path | Yes | string | |
expected_version |
query | Yes | integer |
Response
| HTTP status | Result |
|---|---|
200 |
The requested result. Asynchronous work returns an operation to poll. |
Required fields are required within their containing object. Notes identify fields that apply only to a particular response alternative.
| Response field | Type | Required in object | Notes |
|---|---|---|---|
data |
object | Yes | |
data.object |
"lookup_table_configuration" |
Yes | |
data.id |
string | Yes | |
data.name |
string | Yes | |
data.kind |
"generic", "member_metadata", "status_metadata", "app_owned" |
Yes | |
data.version |
integer | Yes | |
data.fields |
array of object | Yes | |
data.fields[].object |
"lookup_field" |
Yes | |
data.fields[].id |
string | Yes | |
data.fields[].key |
string | Yes | |
data.fields[].name |
string | Yes | |
data.fields[].type |
"text", "number", "boolean", "date", "timestamp", "email", "phone", "domain", "url", "member", "record" |
Yes | |
data.fields[].workflow_readable |
boolean | Yes | |
data.fields[].managed_by |
"customer", "attio", "slack", "system" |
Yes | |
data.fields[].type_locked |
boolean | Yes | |
data.fields[].version |
integer | Yes | |
data.lookups |
array of object | Yes | |
data.lookups[].object |
"lookup_definition" |
Yes | |
data.lookups[].id |
string | Yes | |
data.lookups[].field_id |
string | Yes | |
data.lookups[].default |
boolean | Yes | |
data.pending_work |
object or null | Yes | |
data.pending_work.kind |
"starter", "lookup_key", "field_type" |
Yes | When data.pending_work.kind is "starter", "lookup_key", "field_type". |
data.pending_work.state |
"running", "failed" |
Yes | When data.pending_work.kind is "starter", "lookup_key", "field_type". |
data.pending_work.problem |
string or null | Yes | When data.pending_work.kind is "starter", "lookup_key", "field_type". |
data.import_id |
string or null | Yes |
Errors
| HTTP status | Meaning |
|---|---|
400 |
One of: credential_in_url, invalid_parameter, unknown_parameter, invalid_request, invalid_cursor. |
401 |
One of: missing_credential, invalid_credential, credential_expired, credential_revoked. |
402 |
One of: payment_overdue. |
403 |
The current permissions, plan or policy do not allow this request. |
404 |
One of: not_found. |
409 |
The request conflicts with current resource state, authorization or an earlier request. Read the error code and current resource before retrying. |
410 |
The requested resource or retained recovery data has expired. |
413 |
One of: request_too_large. |
422 |
A field, filter or selection cannot be used for this request. |
423 |
One of: organization_reopening. |
428 |
One of: customer_agreement_required. |
429 |
One of: rate_limited. |
503 |
One of: service_unavailable. |
See errors and recovery and safe retries before repeating a write.
Choose default lookup
PUT /v1/lookup-tables/{table_id}/default-lookup
Chooses the lookup workflows use unless a step names another, at the table version you read. The previous default is not kept. This can't be undone.
Requires lookup_tables:config:write. The connection also needs access to the relevant tables, objects, or workflows.
MCP action: update_lookup_default. Its argument names match the fields below; an HTTP header is passed using its argument name in MCP.
Parameters
| Name | Send in | Required | Type or allowed values | Notes |
|---|---|---|---|---|
table_id |
path | Yes | string | |
expected_version |
JSON body | Yes | integer | |
definition_id |
JSON body | Yes | string (uuid) |
Response
| HTTP status | Result |
|---|---|
200 |
The requested result. Asynchronous work returns an operation to poll. |
Required fields are required within their containing object. Notes identify fields that apply only to a particular response alternative.
| Response field | Type | Required in object | Notes |
|---|---|---|---|
data |
object | Yes | |
data.object |
"lookup_table_configuration" |
Yes | |
data.id |
string | Yes | |
data.name |
string | Yes | |
data.kind |
"generic", "member_metadata", "status_metadata", "app_owned" |
Yes | |
data.version |
integer | Yes | |
data.fields |
array of object | Yes | |
data.fields[].object |
"lookup_field" |
Yes | |
data.fields[].id |
string | Yes | |
data.fields[].key |
string | Yes | |
data.fields[].name |
string | Yes | |
data.fields[].type |
"text", "number", "boolean", "date", "timestamp", "email", "phone", "domain", "url", "member", "record" |
Yes | |
data.fields[].workflow_readable |
boolean | Yes | |
data.fields[].managed_by |
"customer", "attio", "slack", "system" |
Yes | |
data.fields[].type_locked |
boolean | Yes | |
data.fields[].version |
integer | Yes | |
data.lookups |
array of object | Yes | |
data.lookups[].object |
"lookup_definition" |
Yes | |
data.lookups[].id |
string | Yes | |
data.lookups[].field_id |
string | Yes | |
data.lookups[].default |
boolean | Yes | |
data.pending_work |
object or null | Yes | |
data.pending_work.kind |
"starter", "lookup_key", "field_type" |
Yes | When data.pending_work.kind is "starter", "lookup_key", "field_type". |
data.pending_work.state |
"running", "failed" |
Yes | When data.pending_work.kind is "starter", "lookup_key", "field_type". |
data.pending_work.problem |
string or null | Yes | When data.pending_work.kind is "starter", "lookup_key", "field_type". |
data.import_id |
string or null | Yes |
Errors
| HTTP status | Meaning |
|---|---|
400 |
One of: credential_in_url, invalid_parameter, unknown_parameter. |
401 |
One of: missing_credential, invalid_credential, credential_expired, credential_revoked. |
402 |
One of: payment_overdue. |
403 |
The current permissions, plan or policy do not allow this request. |
404 |
One of: not_found. |
409 |
The request conflicts with current resource state, authorization or an earlier request. Read the error code and current resource before retrying. |
410 |
The requested resource or retained recovery data has expired. |
413 |
One of: request_too_large. |
422 |
A field, filter or selection cannot be used for this request. |
423 |
One of: organization_reopening. |
428 |
One of: customer_agreement_required. |
429 |
One of: rate_limited. |
503 |
One of: service_unavailable. |
See errors and recovery and safe retries before repeating a write.
Preview workflow lookup
POST /v1/lookup-tables/{table_id}/workflow-preview
Finds the row a lookup returns for a value, with only the fields a workflow step can read.
Requires lookup_tables:config:read and lookup_tables:read. The connection also needs access to the relevant tables, objects, or workflows.
MCP action: check_lookup_workflow_result. Its argument names match the fields below; an HTTP header is passed using its argument name in MCP.
Parameters
| Name | Send in | Required | Type or allowed values | Notes |
|---|---|---|---|---|
table_id |
path | Yes | string | |
definition_id |
JSON body | Yes | string (uuid) | |
value |
JSON body | Yes | string or number or boolean or object | |
value.objectId |
Within the JSON value | Within this object | string (uuid) | Alternative 4. |
value.recordId |
Within the JSON value | Within this object | string (uuid) | Alternative 4. |
Response
| HTTP status | Result |
|---|---|
200 |
The requested result. Asynchronous work returns an operation to poll. |
Required fields are required within their containing object. Notes identify fields that apply only to a particular response alternative.
| Response field | Type | Required in object | Notes |
|---|---|---|---|
data |
object | Yes | |
data.found |
false |
Yes | Alternative 1. |
data.table_id |
string | Yes | |
data.found |
true |
Yes | Alternative 2. |
data.row_id |
string | Yes | Alternative 2. |
data.values |
object | Yes | Alternative 2. |
references |
array of object | Yes | |
references[].provider |
"attio" |
Yes | |
references[].workspace_id |
string or null | Yes | |
references[].object_id |
string or null | Yes | |
references[].object_slug |
string or null | Yes | |
references[].records |
array of object | Yes | |
references[].records[].record_id |
string | Yes | |
references[].records[].web_url |
string (uri) or null | Yes | |
references[].records[].attributes |
array of object | Yes | |
references[].records[].attributes[].attribute_id |
string or null | Yes | |
references[].records[].attributes[].attribute_slug |
string or null | Yes | |
references[].records[].via |
array of object | Yes | |
references[].records[].via[].source_object_id |
string or null | Yes | |
references[].records[].via[].source_object_slug |
string or null | Yes | |
references[].records[].via[].source_record_id |
string | Yes | |
references[].records[].via[].attribute_id |
string or null | Yes | |
references[].records[].via[].attribute_slug |
string or null | Yes | |
references[].records[].via[].target_object_id |
string or null | Yes | |
references[].records[].via[].target_object_slug |
string or null | Yes | |
references[].records[].via[].target_record_id |
string | Yes | |
references[].lookup_hint |
object | Yes | |
references[].lookup_hint.resource |
"records" |
Yes | |
references[].lookup_hint.object |
string | Yes | |
references[].lookup_hint.record_ids |
array of string | Yes |
Errors
| HTTP status | Meaning |
|---|---|
400 |
One of: credential_in_url, invalid_parameter, unknown_parameter. |
401 |
One of: missing_credential, invalid_credential, credential_expired, credential_revoked. |
402 |
One of: payment_overdue. |
403 |
The current permissions, plan or policy do not allow this request. |
404 |
One of: not_found. |
409 |
The request conflicts with current resource state, authorization or an earlier request. Read the error code and current resource before retrying. |
410 |
The requested resource or retained recovery data has expired. |
413 |
One of: request_too_large. |
422 |
A field, filter or selection cannot be used for this request. |
423 |
One of: organization_reopening. |
428 |
One of: customer_agreement_required. |
429 |
One of: rate_limited. |
503 |
One of: service_unavailable. |
See errors and recovery and safe retries before repeating a write.
The public OpenAPI document lists generally available API families. Alpha operations may not appear in that document; their request and response fields are listed on this page. Use the API Playground to inspect a real response with your connection's access.