POST/v1/custom-fieldsbeta

Create a custom field

Needs: Create and edit contacts, tags, contact groups and custom fields (crm:write)
Plan: Any plan with API access
Limits: 60 a minute per key
Dry run: Yes — every check runs with ?dry_run=true, nothing changes
Undo: Delete it with Delete a custom field.

Creates a custom field for contacts.

key: lower-case snake_case starting with a letter (a–z, 0–9, _, up to 64), unique in your workspace. Reserved names such as name or phone_number are refused.
type: select, radio and multiselect need options (unique values); every other type takes none.
A workspace has at most 100 custom fields.

A key that already exists is refused with 409 (reason: duplicate), so a retry never makes a twin.

Try it

Edit as JSON

keyrequiredstring

Unique key, e.g. `loyalty_tier`. Used in `attributes` and message variables.

labelrequiredstring

The label your team sees.

typerequiredstring

Field type.

optionsoptionallist (JSON)

Choices for `select`, `radio` and `multiselect`: strings (label = value) or `{label, value}`.

placeholderoptionalstring

Hint shown in the empty input.

read_onlyoptionalboolean

`true` = your team cannot edit the value in the app; the API still can.

visibilityoptionalstring

`manager_only` hides the field from agents.

Idempotency-Keyoptional — made for you if empty

Protects against doing it twice if you retry: a retry with the same key gets the first answer back instead of running again.

Test mode (dry run): nothing will change

Run liveTurns test mode off for this page only. It switches back when you leave the page.

curl -X POST 'https://mcp.wa-api.cloud/v1/custom-fields?dry_run=true' \
  -H "Authorization: Bearer $API_KEY" \
  -H 'Content-Type: application/json' \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "key": "loyalty_tier",
  "label": "Loyalty tier",
  "type": "select",
  "options": [
    "gold",
    "silver",
    "bronze"
  ]
}'

The code reads your key from $API_KEY.

Body

Body fields
Field	Type	What it is
keyrequired	string	Unique key, e.g. `loyalty_tier`. Used in `attributes` and message variables.1–64 characters
labelrequired	string	The label your team sees.1–255 characters
typerequired	string	Field type.one of: `text`, `textarea`, `select`, `multiselect`, `checkbox`, `radio`, `date`, `datetime`, `number`, `email`, `url`, `phone`, `int`, `float`, `boolean`, `decimal`
options	array of string \| object	Choices for `select`, `radio` and `multiselect`: strings (label = value) or `{label, value}`.0–100 items
placeholder	string	Hint shown in the empty input.0–255 characters
read_only	boolean	`true` = your team cannot edit the value in the app; the API still can.default `false`
visibility	string	`manager_only` hides the field from agents.one of: `visible_to_all`, `manager_only` · default `"visible_to_all"`

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}$`
Idempotency-Key	header	Any unique string (8–128 characters). A retry with the same key returns the first answer instead of running twice. Kept 24 hours.pattern `^[A-Za-z0-9._:-]+$` · 8–128 characters

Response `201`

The new custom field.

Response fields
Field	Type	What it is
fieldrequired	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
dry_run	boolean	`true` when this was a dry run: every check ran and nothing changed.

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	forbidden	The workspace already has 100 custom fields (`reason: custom_field_limit`).
403	insufficient_scope	The key does not have the permission this operation needs.
409	conflict	A custom field with this key already exists (`reason: duplicate`). Also returned while a request with the same Idempotency-Key is still running.
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.
504	timeout	The change did not finish in time. Retry with the same Idempotency-Key: it never runs twice.

Examples

A loyalty tier with three choices

Request body

{
  "key": "loyalty_tier",
  "label": "Loyalty tier",
  "type": "select",
  "options": [
    "gold",
    "silver",
    "bronze"
  ]
}

Response 201

{
  "field": {
    "id": "32",
    "key": "loyalty_tier",
    "label": "Loyalty tier",
    "type": "select",
    "options": [
      {
        "label": "gold",
        "value": "gold"
      },
      {
        "label": "silver",
        "value": "silver"
      },
      {
        "label": "bronze",
        "value": "bronze"
      }
    ],
    "read_only": false,
    "visibility": "visible_to_all",
    "in_use": false,
    "created_at": "2026-09-02T08:00:00Z"
  }
}

Operation path

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