Update a custom field
Update a custom field’s display name, description, editability, default list visibility, or status. At least one property must be provided.
- Archive / restore: set
status: "archived"to archive a field (its values are retained but it stops appearing in default field lists), orstatus: "active"to restore it. - System fields are read-only — passing a standard field name (e.g.
email) instead of a custom field’s UUID returns400(System fields are read-only). Theapi_nameandvalue_typeof a custom field cannot be changed. - Integration-managed fields reject
display_name,description, andstatusedits (400); onlyis_editableandshow_in_people_list_defaultcan be changed.
Authorizations
Workspace API key, e.g. Authorization: Bearer tented_.... Create keys in Workspace Settings → API Keys.
Path Parameters
Custom field definition ID (field_definition_id from the list or create response).
Body
At least one property is required.
New human-readable label.
1 - 255New description, or null to clear it.
1000Whether values can be edited manually in the UI.
Whether the field appears as a column in the People list by default.
Set archived to archive the field, active to restore it.
active, archived Response
The updated custom field definition.
A contact field definition. Standard fields include only the six required properties; custom fields include the full definition metadata.
standard for built-in contact fields (read-only, always active), custom for workspace custom fields.
standard, custom Stable identifier used in API payloads, import mappings, and merge tags (e.g. email, firstName, or a custom field's snake_case name).
Human-readable label.
Value type. Standard fields may use email/phone; custom fields are string, number, boolean, or date.
string, number, boolean, date, email, phone Whether values can be edited manually in the UI. Always false for standard fields.
Field status. Standard fields are always active.
active, archived Custom field definition ID — the path parameter for PATCH /v1/contact-fields/{fieldDefinitionId}. Custom fields only.
Optional description of what the field stores. Custom fields only.
Who owns the field: org_managed (created in the UI or via this API — fully editable) or integration_managed (owned by a connected integration — name, description, and status are locked). Custom fields only.
org_managed, integration_managed How the field was created. Custom fields only.
manual_ui, import_csv, integration Integration provider that created the field, when applicable. Custom fields only.
Provider-side reference for the field, when applicable. Custom fields only.
Who created the field. tented-api for fields created via this API. Custom fields only.
Import session the field was created from, when provenance_kind is import_csv. Custom fields only.
Whether the field appears as a column in the People list by default. Custom fields only.
Creation time. Custom fields only.
Last update. Custom fields only.