GET/v1/custom-fieldsbeta

List custom fields

Needs: Read your data (mcp:read)
Plan: Any plan with API access
Limits: 300 a minute per key
Undo: Nothing to undo: this only reads.

Lists the custom fields contacts can carry: the key you use in attributes, the label your team sees, the type and, for choice fields, the allowed options.

Try it

Query (4)

searchoptionalstring

Key or label contains this text.

typeoptionalstring

Only fields of this type.

cursoroptionalstring

The `next_cursor` from the previous page. Cursors expire after 24 hours.

limitoptionalinteger

How many items per page (1–100).

This only reads. It uses your real data and changes nothing.

curl -X GET 'https://mcp.wa-api.cloud/v1/custom-fields' \
  -H "Authorization: Bearer $API_KEY"

The code reads your key from $API_KEY.

Parameters

Parameters
Field	Type	What it is
search	string · query	Key or label contains this text.1–100 characters
type	string · query	Only fields of this type.one of: `text`, `textarea`, `select`, `multiselect`, `checkbox`, `radio`, `date`, `datetime`, `number`, `email`, `url`, `phone`, `int`, `float`, `boolean`, `decimal`
cursor	string · query	The `next_cursor` from the previous page. Cursors expire after 24 hours.1–2048 characters
limit	integer · query	How many items per page (1–100).1–100 · default `25`

Headers

Headers
Field	Type	What it is
Authorizationrequired	header	`Bearer $API_KEY` — your API key.
Api-Version	header	The API version to use, e.g. `2026-10-01`. Default: the version your key is pinned to.one of: `2026-10-01` · pattern `^\d{4}-\d{2}-\d{2}$`

Response `200`

A page of custom fields.

Response fields
Field	Type	What it is
datarequired	array of object
idrequired	string
keyrequired	string	Use this key in attributes: { "<key>": value }.
labelrequired	string or null
typerequired	string or null
optionsrequired	array of object or null	Allowed values for select / multiselect / radio fields.
labelrequired	string
valuerequired	string
read_onlyrequired	boolean
visibilityrequired	string or null	visible_to_all or manager_only.
in_userequired	boolean or null
created_atrequired	string or null
totalrequired	integer or null	-9007199254740991–9007199254740991
next_cursorrequired	string or null	Pass as "cursor" to get the next page; null when there are no more results.

Errors

Errors are application/problem+json. Branch on code.

Status	Code	When
400	invalid_input	A field is missing or has the wrong format. `errors[]` points at each field.
401	unauthenticated	The Authorization header is missing, the key is unknown, expired or revoked.
403	entitlement_required	The workspace's plan does not include API access (`api_access`).
403	insufficient_scope	The key does not have the permission this operation needs.
429	rate_limited	The key or workspace went over its rate limit. Wait for `Retry-After` seconds.
503	upstream_unavailable	A service behind the API is briefly unavailable. Safe to retry with backoff.

Examples

All custom fields

Response 200

{
  "data": [
    {
      "id": "31",
      "key": "order_count",
      "label": "Orders",
      "type": "number",
      "options": null,
      "read_only": false,
      "visibility": "visible_to_all",
      "in_use": true,
      "created_at": "2026-09-01T08:00:00Z"
    },
    {
      "id": "32",
      "key": "loyalty_tier",
      "label": "Loyalty tier",
      "type": "select",
      "options": [
        {
          "label": "Gold",
          "value": "gold"
        },
        {
          "label": "Silver",
          "value": "silver"
        }
      ],
      "read_only": false,
      "visibility": "visible_to_all",
      "in_use": false,
      "created_at": "2026-09-02T08:00:00Z"
    }
  ],
  "next_cursor": null,
  "total": 2
}

Operation path

The same operation is also at POST /v1/ops/crm_list_custom_fields, with every field in the JSON body.