List contacts

Exact match on the contact's primary phone number, in E.164.

Free-text match over the contact's name (displayName and the WhatsApp profile name), phone numbers and email addresses. Case- and accent-insensitive. A phone number matches on a trailing fragment too, so 5551234 finds +14155551234.

Contacts created automatically from an inbound message have no displayName — they are matched by their identifier until you set one with PATCH /v1/contacts/{contactId}.

Results come back in relevance order rather than newest-first. cursor is opaque in both modes; pass back exactly what the previous response returned, and start a new pagination run when the search term changes.

Exact WhatsApp business-scoped user ID (e.g. CO.13491208655302741918). Returns the contact that holds it, or an empty list. Combines with phoneNumber and tag as a filter, and cannot be combined with search (400). A value that is not shaped like a BSUID returns 400.

Tag name. Repeatable: ?tag=vip&tag=chile returns contacts carrying every tag given, not any of them — the same rule the dashboard filter applies.

Tags are matched by name, case-insensitively. An unknown tag returns 400 rather than being ignored, because a typo that silently matched every contact would be a worse answer than an error.

Opaque cursor from a previous response's nextCursor. Do not construct it.