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) and parse it. The API returns the parsed rows so you can map columns to contact fields before committing the import.

After reviewing the mapping, confirm the import with POST /contacts/mapped/file.

VCard upload

POST /contacts/upload/vcard

Upload a .vcf file. VCard contacts are parsed automatically with standard field mapping. Confirm with POST /contacts/mapped/vcard.

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.