Contacts API

Create, read, update and delete the people you message, or bulk upsert them in a single request. Contacts can be grouped into lists for targeted campaigns.

GET/contacts/

List contacts

Retrieve a paginated list of contacts in the project. Supports search and filtering by opt-in status.

Query Parameters

searchstring

Search by phone or name.

opted_inboolean

Filter by opt-in status (true or false).

limitinteger

Maximum number of contacts to return. Defaults to 20.

offsetinteger

Number of contacts to skip. Defaults to 0.

200 OKResponse

{
          "count": 1,
          "next": null,
          "previous": null,
          "results": [
            {
              "id": "25659b22-d307-4912-907e-63ed0b353f39",
              "phone": "+233201234567",
              "first_name": "Alice",
              "last_name": "Mensah",
              "attributes": {},
              "opted_in": true,
              "opt_in_source": "MANUAL",
              "opted_out_at": null,
              "created_at": "2026-04-01T19:05:07.109303Z"
            }
          ]
        }

POST/contacts/

Create a contact

Create a new contact. A phone number is required. Optionally add the contact to lists at creation time with list_ids.

Body Parameters

phonestringrequired

Phone number in E.164 format (e.g. +233241234567). Maximum 30 characters.

first_namestring

Contact's first name. Maximum 100 characters.

last_namestring

Contact's last name. Maximum 100 characters.

attributesobject

Custom key-value attributes for the contact.

opted_inboolean

Whether the contact has opted in to receive messages.

opt_in_sourcestring

How the contact opted in. One of API, CSV, or MANUAL.

list_idsstring[]

Array of list IDs to add the contact to. Maximum 10.

Request Body

{
          "phone": "+233241234567",
          "first_name": "Alice",
          "last_name": "Mensah",
          "attributes": {},
          "opted_in": true,
          "opt_in_source": "API",
          "list_ids": ["a7bd4b07-7e58-4785-933c-424d728a2790"]
        }

201 CreatedCreated

{
          "id": "1597951f-e00f-42c3-9924-26a0044ba820",
          "phone": "+233241234567",
          "first_name": "Alice",
          "last_name": "Mensah",
          "attributes": {},
          "opted_in": true,
          "opt_in_source": "API",
          "opted_out_at": null,
          "created_at": "2026-04-03T13:56:18.900086Z"
        }

GET/contacts/{contact_id}/

Get a contact

Retrieve a single contact by ID. The response includes the lists the contact belongs to.

Path Parameters

contact_idstringrequired

The UUID of the contact.

200 OKResponse

{
          "id": "25659b22-d307-4912-907e-63ed0b353f39",
          "phone": "+233201234567",
          "first_name": "Alice",
          "last_name": "Mensah",
          "attributes": {},
          "opted_in": true,
          "opt_in_source": "MANUAL",
          "opted_out_at": null,
          "created_at": "2026-04-01T19:05:07.109303Z",
          "lists": [
            {
              "id": "a7bd4b07-7e58-4785-933c-424d728a2790",
              "name": "VIP Customers",
              "created_at": "2026-04-03T13:55:44.050666Z"
            }
          ]
        }

PATCH/contacts/{contact_id}/

Update a contact

Partially update a contact. All fields are optional — only the fields you include are changed. Updatable fields: first_name, last_name, attributes, opted_in.

Path Parameters

contact_idstringrequired

The UUID of the contact.

Body Parameters

first_namestring

Contact's first name. Maximum 100 characters.

last_namestring

Contact's last name. Maximum 100 characters.

attributesobject

Custom key-value attributes for the contact.

opted_inboolean

Whether the contact has opted in to receive messages.

Request Body

{
          "last_name": "Owusu",
          "opted_in": true
        }

200 OKResponse

{
          "id": "25659b22-d307-4912-907e-63ed0b353f39",
          "phone": "+233201234567",
          "first_name": "Alice",
          "last_name": "Owusu",
          "attributes": {},
          "opted_in": true,
          "opt_in_source": "MANUAL",
          "opted_out_at": null,
          "created_at": "2026-04-01T19:05:07.109303Z"
        }

DELETE/contacts/{contact_id}/

Delete a contact

Soft-delete a contact. Returns 204 No Content on success.

Path Parameters

contact_idstringrequired

The UUID of the contact.

204 No ContentNo content

Empty body — no content is returned.

POST/contacts/bulk/

Bulk upsert

Create or update contacts in bulk. Existing contacts are matched by phone. Maximum 500 contacts per request.

Body Parameters

contactsobject[]required

Array of contact objects, each using the same fields as Create a contact. Maximum 500 items.

Request Body

{
          "contacts": [
            {
              "phone": "+233241000002",
              "first_name": "Bob"
            }
          ]
        }

200 OKResponse

{
          "imported": 1,
          "skipped": 0,
          "failed": 0,
          "errors": []
        }