Table settings
Create, rename, archive, or delete a lookup table, and inspect its settings.
List table settings
GET /v1/lookup-tables/configurations
Lists the settings of the tables this key can use in full: fields, lookups, versions and work in progress. A page holds a few tables; send next_cursor as cursor for the next.
Requires lookup_tables:config:read. The connection also needs access to the relevant tables, objects, or workflows.
MCP action: list_lookup_table_settings. 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 |
|---|---|---|---|---|
cursor |
query | No | string |
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 |
array of 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 | |
pagination |
object | Yes | |
pagination.next_cursor |
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.
Add table
POST /v1/lookup-tables
Adds a table with its fields. key is the table's permanent key. A field's key is made from its name when you leave it out. Needs an API key that can use every table.
Requires lookup_tables:config:write. The connection also needs access to the relevant tables, objects, or workflows.
MCP action: create_lookup_table. 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 |
|---|---|---|---|---|
name |
JSON body | Yes | string | |
key |
JSON body | Yes | string | |
fields |
JSON body | Yes | array of object | |
fields[].name |
Within the JSON value | Within this object | string | |
fields[].key |
Within the JSON value | No | string | |
fields[].type |
Within the JSON value | Within this object | "text", "number", "boolean", "date", "timestamp", "email", "phone", "domain", "url", "member", "record" |
|
fields[].workflow_readable |
Within the JSON value | No | boolean | |
request_key |
Header: Idempotency-Key |
Yes | string |
Response
| HTTP status | Result |
|---|---|
201 |
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. |
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.
Get table settings
GET /v1/lookup-tables/{table_id}/configuration
Gets a table's settings: fields, lookups, its version and any work in progress. Send version as expected_version when you change the table.
Requires lookup_tables:config:read. The connection also needs access to the relevant tables, objects, or workflows.
MCP action: get_lookup_table_settings. 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 |
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.
Rename table
PATCH /v1/lookup-tables/{table_id}/configuration
Renames a table, at the version you read. The old name 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_table_name. 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 | |
name |
JSON body | Yes | string |
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.
Archive table
POST /v1/lookup-tables/{table_id}/archive
Archives a table, at the version you read: workflows and API keys can no longer use it, and it can't be restored. This can't be undone.
Requires lookup_tables:config:write. The connection also needs access to the relevant tables, objects, or workflows.
MCP action: archive_lookup_table. 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 |
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" |
Yes | |
data.id |
string | Yes | |
data.archived |
true |
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.
Delete table
DELETE /v1/lookup-tables/{table_id}
Deletes a table and all its rows, at the version you read. This can't be undone.
Requires lookup_tables:config:write and lookup_tables:delete. The connection also needs access to the relevant tables, objects, or workflows.
MCP action: delete_lookup_table. 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 |
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" |
Yes | |
data.id |
string | Yes | |
data.deleted |
true |
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.
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.