Contacts

Contacts are your customers - the people you call, message, and sell to. Use this API to sync customers from your own systems and keep them up to date.

All endpoints share the prefix /v1/contacts and authenticate with an API key.

Endpoint	Scope
`GET /v1/contacts`	`contacts:read`
`GET /v1/contacts/:id`	`contacts:read`
`POST /v1/contacts`	`contacts:write`
`PATCH /v1/contacts/:id`	`contacts:write`

List contacts


GET /v1/contacts

Query parameters

Parameter	Type	Description
`search`	string	Match against name, phone, or email
`page`	number	Page number (default `1`)
`limit`	number	Items per page (default `20`)


{
  "message": "Contacts retrieved",
  "data": [
    {
      "id": "ct1a2b3c-...",
      "name": "Ada Lovelace",
      "phoneNumber": "+2348012345678",
      "email": "ada@example.com",
      "isVip": false,
      "isBlacklisted": false,
      "joinedAt": "2026-01-01T00:00:00.000Z"
    }
  ],
  "meta": { "total": 1, "page": 1, "perPage": 20, "totalPages": 1, "hasMore": false }
}

Get a contact


GET /v1/contacts/:id

Returns a single contact. Responds 404 not_found if the ID doesn’t belong to your business.

Create a contact


POST /v1/contacts

Body

Field	Type	Required	Description
`name`	string	Yes	Display name (1–100 characters)
`phone_number`	string	No	Phone in E.164
`email`	string	No	Email address
`whatsapp_number`	string	No	WhatsApp number in E.164
`is_vip`	boolean	No	Flag as a VIP customer
`is_blacklisted`	boolean	No	Block this customer


{
  "name": "Ada Lovelace",
  "phone_number": "+2348012345678",
  "email": "ada@example.com",
  "is_vip": true
}

Response 201 Created - the created contact.

Pass an Idempotency-Key header (or idempotency_key field) so retries don’t create duplicate contacts.

Update a contact


PATCH /v1/contacts/:id

Send only the fields you want to change. Accepts the same fields as create (all optional): name, phone_number, email, whatsapp_number, is_vip, is_blacklisted.


{ "is_vip": false, "email": "ada.lovelace@example.com" }

Response 200 OK - the updated contact.