# Lists

Source: https://kirora.io/docs/api/reference/lists

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

- [List lists](https://kirora.io/docs/api/reference/listLists): `GET /v1/lists`
- [Create a list](https://kirora.io/docs/api/reference/createList): `POST /v1/lists`
- [Retrieve a list](https://kirora.io/docs/api/reference/getList): `GET /v1/lists/{id}`
- [Update a list](https://kirora.io/docs/api/reference/updateList): `PATCH /v1/lists/{id}`
- [Delete a list](https://kirora.io/docs/api/reference/deleteList): `DELETE /v1/lists/{id}`
- [Add contacts to a list](https://kirora.io/docs/api/reference/addListContacts): `POST /v1/lists/{id}/contacts`
- [Delete contacts from a list](https://kirora.io/docs/api/reference/deleteListContacts): `POST /v1/lists/{id}/contacts/delete`
- [Retrieve a list's usage](https://kirora.io/docs/api/reference/getListUsage): `GET /v1/lists/{id}/usage`

## The List object

```json
{
  "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"
}
```

- `id` (string, required, uuid)
- `name` (string, required)
- `description` (string | null, required)
- `createdAt` (string, required, date-time)
- `updatedAt` (string, required, date-time)