A list is a fixed set of contacts you add and remove yourself; its membership changes only when you change it. Use a list for an audience you manage, a segment for one described by rules, and a tag to label campaigns and templates, not people. Adding contacts to a list can enroll them in a journey triggered by joining it. A contact's lists: GET /v1/contacts/{id}/lists.
Endpoints
| Endpoint | Request |
|---|---|
| List lists | GET /v1/lists |
| Create a list | POST /v1/lists |
| Retrieve a list | GET /v1/lists/{id} |
| Update a list | PATCH /v1/lists/{id} |
| Delete a list | DELETE /v1/lists/{id} |
| Add contacts to a list | POST /v1/lists/{id}/contacts |
| Delete contacts from a list | POST /v1/lists/{id}/contacts/delete |
| Retrieve a list's usage | GET /v1/lists/{id}/usage |
The List object
{
"id": "0192f3a2-1b3c-7e5d-8a21-4f6a7b8c9d0e",
"name": "Newsletter",
"description": "Everyone who wants the monthly newsletter",
"createdAt": "2026-09-01T10:00:00.000Z",
"updatedAt": "2026-10-01T09:30:00.000Z"
}idstringrequireduuid
namestringrequireddescriptionstring | nullrequiredcreatedAtstringrequireddate-time
updatedAtstringrequireddate-time