POST/v1/contactsstable

Create or update a contact

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: Update the contact again, or delete it if it was just created.

Creates a contact, or updates the one that already has this phone number — so calling it twice is safe. Groups and tags you pass are added; existing ones are kept.

This is the call to use when syncing from a shop or CRM.

Try it

Edit as JSON

phonerequiredstring

International format with country code, e.g. `+15555550123`. Local numbers starting with 0 are refused.

nameoptionalstring

Full name.

emailoptionalstring

Email address (stored in the `email` custom field).

attributesoptionalobject (JSON)

Custom field values by key. `null` or `""` clears a value. Unknown keys are refused with the list of valid ones.

group_idsoptionallist

Group ids.

tagsoptionallist

Tag names or ids. Names that do not exist yet are created.

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/contacts?dry_run=true' \
  -H "Authorization: Bearer $API_KEY" \
  -H 'Content-Type: application/json' \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "phone": "+15555550123",
  "name": "Jane Doe",
  "email": "jane@example.com",
  "tags": [
    "shopify",
    "vip"
  ],
  "attributes": {
    "order_count": 4
  }
}'

The code reads your key from $API_KEY.

Body

Body fields
Field	Type	What it is
phonerequired	string	International format with country code, e.g. `+15555550123`. Local numbers starting with 0 are refused.3–32 characters
name	string	Full name.1–255 characters
email	string	Email address (stored in the `email` custom field).0–255 characters
attributes	object	Custom field values by key. `null` or `""` clears a value. Unknown keys are refused with the list of valid ones.
group_ids	array of string \| integer	Group ids.0–50 items
tags	array of string \| integer	Tag names or ids. Names that do not exist yet are created.0–20 itemsSigned in? Pick one from your data with “My data”.

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 `200`

The contact, and whether it was created or updated.

Response fields
Field	Type	What it is
idrequired	string
actionrequired	string	one of: `created`, `updated`, `unchanged`
contactrequired	object
idrequired	string
namerequired	string or null
phonerequired	string or null	As the platform shows it to this staff member: E.164 digits, or masked (e.g. "*******12345") when the workspace hides numbers from agents. Never unmasked here.
phone_maskedrequired	boolean
whatsapp_user_idrequired	string or null
dndrequired	boolean	Do-not-disturb: the contact receives no broadcasts/marketing.
starredrequired	boolean or null	null only when it could not be read this time (`unavailable` includes profile_extras).
created_atrequired	string or null
updated_atrequired	string or null
email	string or null
web_visitor_id	string or null
tags	array of object
idrequired	string
namerequired	string or null
groups	array of object
idrequired	string
namerequired	string or null
attributes	array of object	Every custom field value this staff member may see (manager-only fields are hidden from agents; deleted fields never appear), at most 100. Text values longer than 2000 characters are clipped.
keyrequired	string	The custom field key (as in `GET /v1/custom-fields`).
labelrequired	string or null	The field label shown in the panel.
typerequired	string or null	text, textarea, number, int, float, decimal, email, phone, url, select, radio, multiselect, checkbox, boolean, date or datetime.
valuerequired	any	The value as the panel shows it: text; checkbox/boolean "Yes"/"No"; date "YYYY-MM-DD"; datetime "YYYY-MM-DD HH:MM:SS" (UTC); multiselect "a, b"; int/float numbers; decimal a string with 8 decimals.
displayrequired	string or null	value as text.
typed_valuerequired	string \| number \| boolean \| array of string or null	value typed by the field type: number/int/float/decimal → number; checkbox/boolean → true/false; date → "YYYY-MM-DD"; datetime → ISO-8601 UTC; multiselect → array of the chosen values; select/radio/text/… → string. null when empty or unreadable.
conversations	array of object	Newest first (at most 10), a timeline summary; read messages with the inbox tools.
idrequired	string
channel_idrequired	string or null
staterequired	string or null
assignedrequired	boolean
assigned_staff_idrequired	string or null
created_atrequired	string or null
last_activity_atrequired	string or null
last_activity_at	string or null	Latest conversation activity (from the conversation list).
unavailable	array of string	Present only when part of the contact could not be read this time (retry later for it): profile_extras = starred, createdAt, updatedAt and webVisitorId are null because they are unknown, not empty; conversations = the timeline (and lastActivityAt) is empty because it could not be read, not because there are none.
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. Too many other contacts' numbers contain this one to find the existing contact exactly (`reason: lookup_incomplete`): nothing is created, so no duplicate; update the contact by id instead.
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	Your plan contact limit is reached (`reason: plan_contact_limit`).
403	insufficient_scope	The key does not have the permission this operation needs.
409	conflict	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.
502	upstream_error	The contact service answered unexpectedly. Retry with the same Idempotency-Key.
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 new customer from your shop

Request body

{
  "phone": "+15555550123",
  "name": "Jane Doe",
  "email": "jane@example.com",
  "tags": [
    "shopify",
    "vip"
  ],
  "attributes": {
    "order_count": 4
  }
}

Response 200

{
  "id": "48213",
  "action": "created",
  "contact": {
    "id": "48213",
    "name": "Jane Doe",
    "phone": "+15555550123",
    "phone_masked": false,
    "email": "jane@example.com",
    "dnd": false,
    "starred": false,
    "tags": [
      {
        "id": "17",
        "name": "vip"
      }
    ],
    "groups": [
      {
        "id": "5",
        "name": "Newsletter"
      }
    ],
    "created_at": "2026-09-20T08:14:03Z",
    "updated_at": "2026-09-23T16:40:11Z",
    "whatsapp_user_id": null
  }
}

Webhook events

These events can fire after this call. Subscribe an endpoint to hear about them.

Operation path

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