List the custom field schema

GET

/v1/custom-fields

• Production

The workspace’s custom field definitions - the keys accepted by the customFields object on a contact, and what each one means. Read this once at the start of an import so you write values under keys the CRM already renders. Requires scope contacts:read.

Authorizations

• bearerAuth

Parameters

Header Parameters

X-Workspace-Id

integer

Act on this workspace’s shared CRM pool. Membership is verified on every request, so an id you do not belong to falls back to personal scope rather than widening access. Omit it to use your default workspace. Applies to every CRM endpoint, not only the ones that list it here.

Responses

200

Custom field definitions.

object

items

Array<object>

One user-defined field. The definition lives here, the value on the contact.

object

id

integer

fieldKey

The key to use inside a contact’s customFields object.

string

label

string

fieldType

string

Allowed values: text number date select checkbox

optionsJson

JSON array of option strings

string

nullable

order

integer

nextCursor

integer

nullable

hasMore

boolean

401

Missing or invalid bearer token.

Standard error envelope for all v1 error responses.

object

error

Machine-readable error code.

string

Allowed values: bad_request not_found conflict unauthorized forbidden payment_required provider_rejected rate_limited internal_error

message

Human-readable explanation of the error.

string

details

Optional structured context (field-level validation errors, etc.).

nullable

Example

{
  "error": "unauthorized",
  "message": "Invalid bearer principal"
}

403

The API key does not have the required scope for this operation.

Standard error envelope for all v1 error responses.

object

error

Machine-readable error code.

string

Allowed values: bad_request not_found conflict unauthorized forbidden payment_required provider_rejected rate_limited internal_error

message

Human-readable explanation of the error.

string

details

Optional structured context (field-level validation errors, etc.).

nullable

Example

{
  "error": "forbidden",
  "message": "scope contacts:write is required"
}