Contacts API

Manage your WhatsApp Business contacts programmatically. Create new contacts, search your customer database, update profiles, and organize with tags and labels.

List contacts

Retrieve a paginated, searchable list of contacts for your organization.

GET /api/whatsapp/contacts

Query parameters:

Parameter	Type	Default	Description
`page`	number	`1`	Page number for pagination
`limit`	number	`20`	Results per page (max: 100)
`search`	string	—	Search by name, phone number, or email
`sortBy`	string	`created_at`	Sort field: `created_at`, `name`, `last_message_at`
`sortOrder`	string	`desc`	Sort direction: `asc` or `desc`

Response:

{
  "success": true,
  "data": {
    "contacts": [
      {
        "id": "contact_f1e2d3c4-5678-90ab-cdef-abcdefabcdef",
        "name": "Ahmed Hassan",
        "phone": "+971501234567",
        "email": "ahmed@example.com",
        "countryCode": "AE",
        "tags": ["vip", "returning-customer"],
        "labels": ["premium"],
        "source": "organic",
        "optedIn": true,
        "isBlocked": false,
        "lastMessageAt": "2026-05-16T14:22:00.000Z",
        "conversationCount": 5,
        "createdAt": "2026-03-10T08:00:00.000Z",
        "updatedAt": "2026-05-16T14:22:00.000Z"
      },
      {
        "id": "contact_e2d3c4b5-6789-01ab-cdef-bcdefabcdefg",
        "name": "Sarah Johnson",
        "phone": "+14155557890",
        "email": null,
        "countryCode": "US",
        "tags": ["new-lead"],
        "labels": [],
        "source": "campaign",
        "optedIn": true,
        "isBlocked": false,
        "lastMessageAt": "2026-05-16T13:45:00.000Z",
        "conversationCount": 1,
        "createdAt": "2026-05-16T13:30:00.000Z",
        "updatedAt": "2026-05-16T13:45:00.000Z"
      }
    ],
    "total": 1842,
    "page": 1,
    "limit": 20,
    "hasNext": true
  }
}

Get contact

Retrieve a single contact by ID (UUID or vendor contact ID).

GET /api/whatsapp/contacts/:contactId

Response:

{
  "success": true,
  "data": {
    "id": "contact_f1e2d3c4-5678-90ab-cdef-abcdefabcdef",
    "vendorContactId": "6478a1b2c3d4e5f6a7b8c9d0",
    "name": "Ahmed Hassan",
    "phone": "+971501234567",
    "email": "ahmed@example.com",
    "countryCode": "AE",
    "tags": ["vip", "returning-customer"],
    "labels": ["premium"],
    "params": {
      "shopify_customer_id": "cust_789012",
      "loyalty_tier": "gold"
    },
    "source": "organic",
    "optedIn": true,
    "isBlocked": false,
    "lastMessageAt": "2026-05-16T14:22:00.000Z",
    "conversationCount": 5,
    "createdAt": "2026-03-10T08:00:00.000Z",
    "updatedAt": "2026-05-16T14:22:00.000Z"
  }
}

Error (404):

{
  "success": false,
  "error": "Contact not found"
}

Create contact

Add a new contact to your WhatsApp Business account and CRM.

POST /api/whatsapp/contacts

Request body:

{
  "userNumber": "+971501234567",
  "userName": "Ahmed Hassan",
  "email": "ahmed@example.com",
  "countryCode": "AE",
  "tags": ["lead", "website"],
  "params": {
    "source_page": "/pricing",
    "utm_campaign": "spring_2026"
  }
}

Field	Type	Required	Description
`userNumber`	string	Yes	Phone number in E.164 format (e.g., `+971501234567`)
`userName`	string	No	Contact display name
`email`	string	No	Contact email address
`countryCode`	string	No	ISO 3166-1 alpha-2 code (e.g., `AE`, `US`)
`tags`	string[]	No	Array of tags for categorization
`params`	object	No	Custom key-value parameters

Response (201 Created):

{
  "success": true,
  "data": {
    "id": "contact_new12345-6789-01ab-cdef-abcdefabcdef",
    "vendorContactId": "6478a1b2c3d4e5f6a7b8c9d1",
    "name": "Ahmed Hassan",
    "phone": "+971501234567",
    "email": "ahmed@example.com",
    "countryCode": "AE",
    "tags": ["lead", "website"],
    "params": {
      "source_page": "/pricing",
      "utm_campaign": "spring_2026"
    },
    "source": "api",
    "optedIn": false,
    "isBlocked": false,
    "createdAt": "2026-05-16T15:00:00.000Z",
    "updatedAt": "2026-05-16T15:00:00.000Z"
  }
}

Error — missing phone (400):

{
  "success": false,
  "error": "Phone number (userNumber) is required"
}

Error — duplicate (409):

{
  "success": false,
  "error": "Contact with this phone number already exists"
}

Update contact

Update one or more fields on an existing contact.

PATCH /api/whatsapp/contacts/:contactId

Request body: (include only fields you want to update)

{
  "name": "Ahmed Hassan Al-Maktoum",
  "email": "ahmed.new@example.com",
  "tags": ["vip", "returning-customer", "high-value"],
  "params": {
    "shopify_customer_id": "cust_789012",
    "loyalty_tier": "platinum"
  },
  "opted_in": true
}

Allowed fields:

Field	Type	Description
`name`	string	Contact display name
`email`	string	Contact email
`country_code`	string	ISO country code
`tags`	string[]	Replaces all existing tags
`params`	object	Replaces all custom params
`is_blocked`	boolean	Block/unblock contact
`source`	string	Contact source
`opted_in`	boolean	WhatsApp opt-in status

Response:

{
  "success": true,
  "data": {
    "id": "contact_f1e2d3c4-5678-90ab-cdef-abcdefabcdef",
    "name": "Ahmed Hassan Al-Maktoum",
    "phone": "+971501234567",
    "email": "ahmed.new@example.com",
    "country_code": "AE",
    "tags": ["vip", "returning-customer", "high-value"],
    "params": {
      "shopify_customer_id": "cust_789012",
      "loyalty_tier": "platinum"
    },
    "is_blocked": false,
    "opted_in": true,
    "updated_at": "2026-05-16T15:10:00.000Z"
  }
}

Error — no valid fields (400):

{
  "success": false,
  "error": "No valid fields to update"
}

Bulk import contacts

Import multiple contacts at once from a CSV upload or JSON array.

POST /api/whatsapp/contacts/bulk

Request body:

{
  "contacts": [
    {
      "userNumber": "+971501111111",
      "userName": "Contact One",
      "tags": ["imported"]
    },
    {
      "userNumber": "+971502222222",
      "userName": "Contact Two",
      "tags": ["imported"]
    },
    {
      "userNumber": "+971503333333",
      "userName": "Contact Three",
      "email": "three@example.com"
    }
  ]
}

Response:

{
  "success": true,
  "data": {
    "imported": 3,
    "skipped": 0,
    "errors": [],
    "contacts": [
      { "id": "contact_new1...", "phone": "+971501111111", "status": "created" },
      { "id": "contact_new2...", "phone": "+971502222222", "status": "created" },
      { "id": "contact_new3...", "phone": "+971503333333", "status": "created" }
    ]
  }
}

Response with partial failures:

{
  "success": true,
  "data": {
    "imported": 2,
    "skipped": 1,
    "errors": [
      {
        "index": 1,
        "phone": "+971502222222",
        "error": "Contact already exists"
      }
    ],
    "contacts": [
      { "id": "contact_new1...", "phone": "+971501111111", "status": "created" },
      { "id": "contact_new3...", "phone": "+971503333333", "status": "created" }
    ]
  }
}

Error responses

Status Code	Error	Description
400	`"Phone number (userNumber) is required"`	Missing required phone field
400	`"No valid fields to update"`	PATCH with no recognized fields
401	`"Unauthorized"`	Missing or invalid auth headers
404	`"Contact not found"`	ID does not exist in your organization
409	`"Contact already exists"`	Duplicate phone number
429	`"Rate limit exceeded"`	Too many requests
500	`"Internal server error"`	Unexpected failure

List contacts​

Get contact​

Create contact​

Update contact​

Bulk import contacts​

Error responses​

List contacts

Get contact

Create contact

Update contact

Bulk import contacts

Error responses