Skip to main content
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

​
name
string
required
The contact’s full name (e.g. Maria Santos).
​
phone
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).
​
email
string
The contact’s email address. Required if you plan to target this contact via the email channel.
​
lists
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"]
  }'

​
Response Fields

​
id
string
The unique contact identifier, prefixed with cnt_ (e.g. cnt_def456).
​
name
string
The contact’s full name as provided in the request.
​
phone
string
The contact’s phone number in E.164 format.
​
email
string
The contact’s email address, if provided.
​
lists
array
An array of contact list IDs the contact belongs to.
​
created_at
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

StatusErrorDescription
400invalid_requestMissing required fields or malformed JSON body
401unauthorizedAPI key is missing or invalid
409conflictA contact with this phone number already exists on the account
422validation_errorphone 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

​
list_id
string
Filter contacts by a specific contact list ID. Returns only contacts belonging to the specified list.
​
page
integer
Page number (default: 1).
​
per_page
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"

​
Response Fields

​
data
array
An array of contact objects matching the query.
​
meta
object
Pagination metadata.
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"
A successful deletion returns 204 No Content with an empty response body.

​
Error Scenarios

StatusErrorDescription
401unauthorizedAPI key is missing or invalid
404not_foundNo 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.