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.

GET/lists/

List contact lists

List the project's contact lists.

Query Parameters

pageinteger

Page number to return. Defaults to 1.

page_sizeinteger

Number of lists per page. Defaults to 30, maximum 1000.

200 OKResponse
{
  "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"
    }
  ]
}
POST/lists/

Create a list

Create a contact list.

Body Parameters

namestringrequired

Name of the list. Maximum 100 characters.

descriptionstring

Optional description of the list. Maximum 500 characters.

Request Body
{
  "name": "VIP Customers",
  "description": "High-value customers"
}
201 CreatedCreated
{
  "id": "a7bd4b07-7e58-4785-933c-424d728a2790",
  "name": "VIP Customers",
  "description": "High-value customers",
  "contact_count": 0,
  "created_at": "2026-04-03T13:55:44.050666Z"
}
GET/lists/{list_id}/

Get a list

Get one contact list by ID, with how many contacts it has right now.

Path Parameters

list_idstringrequired

The UUID of the list.

200 OKResponse
{
  "id": "a7bd4b07-7e58-4785-933c-424d728a2790",
  "name": "VIP Customers",
  "description": "High-value customers",
  "contact_count": 2,
  "created_at": "2026-04-03T13:55:44.050666Z"
}
PATCH/lists/{list_id}/

Update a list

Change a list's name or description. Anything you leave out stays as it is.

Path Parameters

list_idstringrequired

The UUID of the list.

Body Parameters

namestring

Name of the list. Maximum 100 characters.

descriptionstring

Description of the list. Maximum 500 characters.

Request Body
{
  "description": "Updated description"
}
200 OKResponse
{
  "id": "a7bd4b07-7e58-4785-933c-424d728a2790",
  "name": "VIP Customers",
  "description": "Updated description",
  "contact_count": 2,
  "created_at": "2026-04-03T13:55:44.050666Z"
}
DELETE/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_idstringrequired

The UUID of the list.

204 No ContentNo content

No response body.

GET/lists/{list_id}/contacts/

List contacts in a list

List the contacts in a list.

Path Parameters

list_idstringrequired

The UUID of the list.

Query Parameters

pageinteger

Page number to return. Defaults to 1.

page_sizeinteger

Number of contacts per page. Defaults to 30, maximum 1000.

200 OKResponse
{
  "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"
    }
  ]
}
POST/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_idstringrequired

The UUID of the list.

Body Parameters

contact_idsstring[]required

Array of contact IDs to add to the list. Maximum 500.

Request Body
{
  "contact_ids": ["25659b22-d307-4912-907e-63ed0b353f39"]
}
200 OKResponse
{
  "added": 1,
  "already_in_list": 0,
  "not_found": 0
}
DELETE/lists/{list_id}/contacts/{contact_id}/

Remove a contact

Take one contact out of a list. Returns 204 No Content.

Path Parameters

list_idstringrequired

The UUID of the list.

contact_idstringrequired

The UUID of the contact to remove.

204 No ContentNo content

No response body.