API reference

Contacts

Sync your customers into MYWA. Upserts are keyed on the phone number, so it is safe to call repeatedly from any system.

Upsert a contact

POST/contacts

Requires contacts:write. Returns 201 when a contact is created and 200 when an existing one is updated.

Body parameters

Field	Type	Description
`phone`req	`string`	E.164 phone number — the upsert key.
`name`	`string`	Contact display name.
`email`	`string`	Contact email.
`attributes`	`object`	Key→value pairs (string, number, or boolean). Merged, not replaced.

curl -X POST "$MYWA_API/contacts" \
  -H "Authorization: Bearer $MYWA_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "+15551234567",
    "name": "Jane Doe",
    "email": "jane@example.com",
    "attributes": { "plan": "pro", "orders": 12, "vip": true }
  }'

json

{
  "id": "cts_3c4d…",
  "phone": "+15551234567",
  "name": "Jane Doe",
  "email": "jane@example.com",
  "attributes": { "plan": "pro", "orders": 12, "vip": true },
  "optedOut": false,
  "createdAt": "2026-07-01T10:00:00.000Z"
}

Attributes are merged

Sending { "orders": 13 } updates only that key and leaves the rest intact — partial syncs from different systems never clobber each other. Values must be scalars (string, number, or boolean).

List & look up contacts

GET/contacts

Requires contacts:read. Look up one contact by phone, or page through all of them.

bash

# Exact lookup by phone (URL-encode the +)
curl "$MYWA_API/contacts?phone=%2B15551234567" -H "Authorization: Bearer $MYWA_KEY"

# Page through everything
curl "$MYWA_API/contacts?limit=100" -H "Authorization: Bearer $MYWA_KEY"

json

{
  "contacts": [ { "id": "cts_…", "phone": "+15551234567", "name": "Jane Doe", "…": "…" } ],
  "nextCursor": "cts_3c4d…"
}

Pass cursor=<nextCursor> to fetch the next page. nextCursor is null on the last page.

Get one contact

GET/contacts/:id

bash

curl "$MYWA_API/contacts/cts_3c4d…" -H "Authorization: Bearer $MYWA_KEY"