v1

latestOpenAPI 3.1.02026-07-22115189303.8 KB

Contacts

List contacts

Retrieve a paginated list of WhatsApp contacts for your project.

get/whatsapp/contacts

Query parameters

customer_idstring

Filter by associated customer ID

customer_external_idstring

Filter by customer external ID

has_customerboolean

Filter by customer association (true/false)

profile_name_containsstring

Filter by profile name (case-insensitive substring match)

wa_id_containsstring

Filter by WhatsApp ID (substring match)

business_scoped_user_idstring

Filter by exact WhatsApp business-scoped user ID

created_afterstring date-time

Filter contacts created after this ISO 8601 timestamp

created_beforestring date-time

Filter contacts created before this ISO 8601 timestamp

pageinteger

Page number for legacy offset pagination. Deprecated — use cursor pagination (limit, after, before) instead. Maximum page: 50. Maximum window (page × per_page): 5,000. Requests exceeding these limits return a 400 error.

per_pageinteger

Items per page for legacy offset pagination.

limitinteger

Maximum number of results per cursor-paginated page (default 20, max 100).

beforestring

Cursor for the previous page (Base64 encoded).

afterstring

Cursor for the next page (Base64 encoded).

Response

Successfully retrieved contacts

Example response

{
  "data": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "wa_id": "15551234567",
      "business_scoped_user_id": "US.13491208655302741918",
      "parent_business_scoped_user_id": "US.ENT.506847293015824",
      "username": "@testusername",
      "profile_name": "John Doe",
      "display_name": "John (VIP)"
    }
  ]
}