GET/v1/contactsstable

List contacts

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.

Finds contacts in your workspace, newest first. Filter by text, tags, groups, starred or do-not-disturb. For custom fields, dates, assigned staff, broadcasts and saved filters use Search contacts (POST /contacts/search).

Use detail=full to include email, tags and groups on every row.

Try it

Query (9)

queryoptionalstring

Name or phone contains this text.

group_idsoptionallist

Contacts in ANY of these groups.

tag_idsoptionallist

Contacts with ANY of these tags (repeat the parameter).

starredoptionalboolean

`true` = starred contacts only.

dndoptionalboolean

`true` = do-not-disturb on; `false` = can receive broadcasts.

not_in_any_groupoptionalboolean

`true` = contacts in no group.

detailoptionalstring

`summary` (default) or `full` (adds email, tags and groups).

limitoptionalinteger

How many items per page (1–100).

cursoroptionalstring

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

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

curl -X GET 'https://mcp.wa-api.cloud/v1/contacts?tag_ids=17&detail=full&limit=2' \
  -H "Authorization: Bearer $API_KEY"

The code reads your key from $API_KEY.

Parameters

Parameters
Field	Type	What it is
query	string · query	Name or phone contains this text.1–100 characters
group_ids	array of string \| integer · query	Contacts in ANY of these groups.0–50 items
tag_ids	array of string \| integer · query	Contacts with ANY of these tags (repeat the parameter).0–50 itemsSigned in? Pick one from your data with “My data”.
starred	boolean · query	`true` = starred contacts only.
dnd	boolean · query	`true` = do-not-disturb on; `false` = can receive broadcasts.
not_in_any_group	boolean · query	`true` = contacts in no group.
detail	string · query	`summary` (default) or `full` (adds email, tags and groups).one of: `summary`, `full` · default `"summary"`
limit	integer · query	How many items per page (1–100).1–100 · default `25`
cursor	string · query	The `next_cursor` from the previous page. Cursors expire after 24 hours.1–2048 characters

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 contacts.

Response fields
Field	Type	What it is
datarequired	array of 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.
totalrequired	integer or null	Contacts matching the filters (all pages); with filter / savedFilterId / sort only on the first page.-9007199254740991–9007199254740991
approximate	boolean or null	true when total is an estimate (advanced path).
resolved_dates	array of object	Relative or local dates in filter and the absolute instants they were run with.
pathrequired	string
inputrequired	string
valuerequired	string
warnings	array of object	Filter conditions that may not mean what they look like: {path, message}.
path	string
messagerequired	string
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

VIP contacts with full detail

Response 200

{
  "data": [
    {
      "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
    }
  ],
  "next_cursor": "eyJ2IjoxLCJwIjoyfQ.c2ln",
  "total": 1
}

Operation path

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