Add, List, and Delete Contacts — Zexa Contacts API

The Contacts API lets you build and maintain your recipient database programmatically. Add contacts individually, organise them into contact lists for use with the Campaigns API, query and filter your contact database, and remove contacts when they are no longer needed. All phone numbers must be in E.164 format to ensure reliable delivery across all channels.

Add a Contact

POST https://api.zexa.ao/v1/contacts

Request Parameters

string

required

The contact’s full name (e.g. Maria Santos).

string

required

The contact’s phone number in E.164 format. Must include the + prefix followed by the country code and subscriber number (e.g. +244912345678 for an Angolan number).

string

The contact’s email address. Required if you plan to target this contact via the email channel.

array

An array of contact list IDs to assign this contact to upon creation (e.g. ["lst_abc123", "lst_def456"]). You can also add contacts to lists later via the dashboard.

Request Example

curl -X POST https://api.zexa.ao/v1/contacts \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Maria Santos",
    "phone": "+244912345678",
    "email": "maria@example.com",
    "lists": ["lst_abc123"]
  }'

import requests

response = requests.post(
    "https://api.zexa.ao/v1/contacts",
    headers={
        "Authorization": "Bearer YOUR_API_KEY",
        "Content-Type": "application/json",
    },
    json={
        "name": "Maria Santos",
        "phone": "+244912345678",
        "email": "maria@example.com",
        "lists": ["lst_abc123"],
    },
)

print(response.json())

Response Fields

string

The unique contact identifier, prefixed with cnt_ (e.g. cnt_def456).

string

The contact’s full name as provided in the request.

string

The contact’s phone number in E.164 format.

string

The contact’s email address, if provided.

array

An array of contact list IDs the contact belongs to.

string

ISO 8601 UTC timestamp of when the contact was created.

Example response (201 Created):

{
  "id": "cnt_def456",
  "name": "Maria Santos",
  "phone": "+244912345678",
  "email": "maria@example.com",
  "lists": ["lst_abc123"],
  "created_at": "2026-06-24T10:00:00Z"
}

Phone numbers must be in E.164 format. Use the + prefix followed by the country code and local number — for example, +244 for Angola, +351 for Portugal, and +1 for the United States. Submissions in local formats (e.g. 0912345678) will be rejected with a 422 error.

Error Scenarios

Status	Error	Description
`400`	`invalid_request`	Missing required fields or malformed JSON body
`401`	`unauthorized`	API key is missing or invalid
`409`	`conflict`	A contact with this phone number already exists on the account
`422`	`validation_error`	`phone` is not in E.164 format, or `email` is malformed

List Contacts

Retrieve a paginated list of contacts on your account. Optionally filter by contact list.

GET https://api.zexa.ao/v1/contacts

Query Parameters

string

Filter contacts by a specific contact list ID. Returns only contacts belonging to the specified list.

integer

Page number (default: 1).

integer

Results per page (default: 50, max: 100).

Request Example

curl "https://api.zexa.ao/v1/contacts?list_id=lst_abc123&page=1&per_page=25" \
  -H "Authorization: Bearer YOUR_API_KEY"

import requests

response = requests.get(
    "https://api.zexa.ao/v1/contacts",
    params={"list_id": "lst_abc123", "page": 1, "per_page": 25},
    headers={"Authorization": "Bearer YOUR_API_KEY"},
)

print(response.json())

Response Fields

array

An array of contact objects matching the query.

Show contact object fields

string

Unique contact identifier.

string

The contact’s full name.

string

The contact’s phone number in E.164 format.

string

The contact’s email address, if set.

string

ISO 8601 UTC timestamp of when the contact was created.

object

Pagination metadata.

Show meta fields

integer

Total number of contacts matching the query.

integer

Current page number.

integer

Number of results per page.

Example response:

{
  "data": [
    {
      "id": "cnt_def456",
      "name": "Maria Santos",
      "phone": "+244912345678",
      "email": "maria@example.com",
      "created_at": "2026-06-24T10:00:00Z"
    },
    {
      "id": "cnt_ghi789",
      "name": "João Ferreira",
      "phone": "+244923456789",
      "email": "joao@example.com",
      "created_at": "2026-06-23T14:30:00Z"
    }
  ],
  "meta": {
    "total": 128,
    "page": 1,
    "per_page": 25
  }
}

Delete a Contact

Permanently remove a contact from your account by their ID:

DELETE https://api.zexa.ao/v1/contacts/{id}

curl -X DELETE https://api.zexa.ao/v1/contacts/cnt_def456 \
  -H "Authorization: Bearer YOUR_API_KEY"

import requests

response = requests.delete(
    "https://api.zexa.ao/v1/contacts/cnt_def456",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
)

print(response.status_code)  # 204 on success

A successful deletion returns 204 No Content with an empty response body.

Error Scenarios

Status	Error	Description
`401`	`unauthorized`	API key is missing or invalid
`404`	`not_found`	No contact with the given ID exists on the account

Deleting a contact removes them from all contact lists they belong to and permanently excludes them from future campaigns. This action cannot be undone. If you simply want to stop targeting a contact in a specific campaign, remove them from the relevant contact list instead.

Overview

Endpoints

Add, List, and Delete Contacts — Zexa Contacts API

Add a Contact

Request Parameters

Request Example

Response Fields

Error Scenarios

List Contacts

Query Parameters

Request Example

Response Fields

Delete a Contact

Error Scenarios

​Add a Contact

​Request Parameters

​Request Example

​Response Fields

​Error Scenarios

​List Contacts

​Query Parameters

​Request Example

​Response Fields

​Delete a Contact

​Error Scenarios

Add a Contact

Request Parameters

Request Example

Response Fields

Error Scenarios

List Contacts

Query Parameters

Request Example

Response Fields

Delete a Contact

Error Scenarios