Contacts and Contact Lists

Contacts are your address book. Contact lists group contacts into named segments that you can target with campaigns.

Managing contacts

Create a contact

POST /contacts

Provide the contact's name, phone number, email, and any custom fields.

Search and filter

GET /contacts

Filter contacts by name, phone number, email, gender, validity, or communication channel support. Results are paginated.

Update and delete

• PUT /contacts/{id} -- Update a contact's details.
• DELETE /contacts -- Delete one or more contacts by ID.

Bulk import

The API supports two import formats:

CSV / Excel upload

POST /contacts/upload

Upload a file (CSV, Excel) as multipart form data, with file and fileName; add removeHead=true when the first row holds the column headers. The import happens in the same call: columns are mapped to contact fields automatically, new contacts are created and existing ones, matched by phone number, are updated.

VCard upload

POST /contacts/upload/vcard

Upload a .vcf file, again with file and fileName. Entries are read from the standard vCard fields and imported in the same call, with the same create-or-update behaviour.

In both cases, to put the imported contacts in a list, add them afterwards with POST /contacts/list/contacts.

Contact lists

Create a list

POST /contacts/list

Give your list a name and optionally a description.

Add contacts to a list

POST /contacts/list/contacts

Associate one or more contacts with one or more lists in a single request.

Remove contacts from a list

DELETE /contacts/list/contacts

Remove specific contacts from specific lists without deleting the contacts themselves.

Browse list members

GET /contacts/list/{listId}/contacts

Paginated list of all contacts belonging to a specific list.

Using lists in campaigns

When you create a campaign, you specify a contact list as the target audience. The campaign will send the message to every contact in that list.

This is why organizing your contacts into well-defined lists is important: it lets you target the right audience for each campaign.

Exporting contacts

For large data sets, use the async export workflow:

POST /exports/contacts

See the Exports guide for the full export workflow.

Quick reference

Action	Endpoint
List contacts	GET /contacts
Create contact	POST /contacts
Get contact	GET /contacts/{id}
Update contact	PUT /contacts/{id}
Delete contacts	DELETE /contacts
List contact lists	GET /contacts/list
Create list	POST /contacts/list
Add to list	POST /contacts/list/contacts
Remove from list	DELETE /contacts/list/contacts
Upload CSV	POST /contacts/upload
Upload VCard	POST /contacts/upload/vcard

See the Contact API Reference and Contact List API Reference for full details.