Lists API
Group contacts into lists to organize segments and target messaging campaigns. Create lists, add and remove contacts, and read a list's membership.
/lists/List contact lists
Retrieve a paginated list of contact lists in the project.
Query Parameters
limitintegerMaximum number of lists to return. Defaults to 20.
offsetintegerNumber of lists to skip. Defaults to 0.
{
"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 new 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
Retrieve a single contact list by ID, including its current contact count.
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
Partially update a contact list. All fields are optional — only the fields you include are changed.
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 on success, or 409 Conflict if the list still has associated campaigns.
Path Parameters
list_idstringrequiredThe UUID of the list.
Empty body — no content is returned.
/lists/{list_id}/contacts/List contacts in a list
Retrieve a paginated list of the contacts that belong to a specific list.
Path Parameters
list_idstringrequiredThe UUID of the list.
Query Parameters
limitintegerMaximum number of contacts to return. Defaults to 20.
offsetintegerNumber of contacts to skip. Defaults to 0.
{
"count": 2,
"next": null,
"previous": null,
"results": [
{
"id": "1597951f-e00f-42c3-9924-26a0044ba820",
"phone": "+233241234567",
"first_name": "Alice",
"last_name": "Mensah",
"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 one or more existing contacts to a list. The response reports how many were added, were already members, or could not be 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
Remove a single contact from a list. Returns 204 No Content on success.
Path Parameters
list_idstringrequiredThe UUID of the list.
contact_idstringrequiredThe UUID of the contact to remove.
Empty body — no content is returned.