Lists API
A list is a named group of contacts you can send a campaign to. Create lists, add and remove contacts, and see who is in each one.
/lists/List contact lists
List the project's contact lists.
Query Parameters
pageintegerPage number to return. Defaults to 1.
page_sizeintegerNumber of lists per page. Defaults to 30, maximum 1000.
{
"count": 1,
"next": null,
"previous": null,
"results": [
{
"id": "a7bd4b07-7e58-4785-933c-424d728a2790",
"name": "VIP Customers",
"description": "High-value customers",
"contact_count": 2,
"created_at": "2026-04-03T13:55:44.050666Z"
}
]
}/lists/Create a list
Create a contact list.
Body Parameters
namestringrequiredName of the list. Maximum 100 characters.
descriptionstringOptional description of the list. Maximum 500 characters.
{
"name": "VIP Customers",
"description": "High-value customers"
}{
"id": "a7bd4b07-7e58-4785-933c-424d728a2790",
"name": "VIP Customers",
"description": "High-value customers",
"contact_count": 0,
"created_at": "2026-04-03T13:55:44.050666Z"
}/lists/{list_id}/Get a list
Get one contact list by ID, with how many contacts it has right now.
Path Parameters
list_idstringrequiredThe UUID of the list.
{
"id": "a7bd4b07-7e58-4785-933c-424d728a2790",
"name": "VIP Customers",
"description": "High-value customers",
"contact_count": 2,
"created_at": "2026-04-03T13:55:44.050666Z"
}/lists/{list_id}/Update a list
Change a list's name or description. Anything you leave out stays as it is.
Path Parameters
list_idstringrequiredThe UUID of the list.
Body Parameters
namestringName of the list. Maximum 100 characters.
descriptionstringDescription of the list. Maximum 500 characters.
{
"description": "Updated description"
}{
"id": "a7bd4b07-7e58-4785-933c-424d728a2790",
"name": "VIP Customers",
"description": "Updated description",
"contact_count": 2,
"created_at": "2026-04-03T13:55:44.050666Z"
}/lists/{list_id}/Delete a list
Soft-delete a contact list. Returns 204 No Content, or 409 Conflict if a campaign still uses the list.
Path Parameters
list_idstringrequiredThe UUID of the list.
No response body.
/lists/{list_id}/contacts/List contacts in a list
List the contacts in a list.
Path Parameters
list_idstringrequiredThe UUID of the list.
Query Parameters
pageintegerPage number to return. Defaults to 1.
page_sizeintegerNumber of contacts per page. Defaults to 30, maximum 1000.
{
"count": 2,
"next": null,
"previous": null,
"results": [
{
"id": "1597951f-e00f-42c3-9924-26a0044ba820",
"phone": "+233241234567",
"first_name": "Alice",
"last_name": "Mensah",
"email": "",
"attributes": {},
"opted_in": true,
"opt_in_source": "API",
"opted_out_at": null,
"created_at": "2026-04-03T13:56:18.900086Z"
}
]
}/lists/{list_id}/contacts/Add contacts to a list
Add existing contacts to a list. The response counts how many were added, how many were already in it, and how many weren't found.
Path Parameters
list_idstringrequiredThe UUID of the list.
Body Parameters
contact_idsstring[]requiredArray of contact IDs to add to the list. Maximum 500.
{
"contact_ids": ["25659b22-d307-4912-907e-63ed0b353f39"]
}{
"added": 1,
"already_in_list": 0,
"not_found": 0
}/lists/{list_id}/contacts/{contact_id}/Remove a contact
Take one contact out of a list. Returns 204 No Content.
Path Parameters
list_idstringrequiredThe UUID of the list.
contact_idstringrequiredThe UUID of the contact to remove.
No response body.