> ## Documentation Index
> Fetch the complete documentation index at: https://docs.olimi.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Customer Lists

> List, read and create the customer lists that campaigns call.

A customer list is a group of contacts that a campaign calls, such as a list uploaded from a spreadsheet. These endpoints let you read and create customer lists from your own systems. To manage the people in a list, use [Contacts](https://docs.olimi.ai/api-reference/endpoint/contacts/contacts.md).

| Endpoint | Request |
| - | - |
| [List customer lists](https://docs.olimi.ai/api-reference/endpoint/customer-list/list-customer-lists.md) | `GET /api/v2/customer-lists` |
| [Get a customer list](https://docs.olimi.ai/api-reference/endpoint/customer-list/get-customer-list.md) | `GET /api/v2/customer-lists/{id}` |
| [Create a customer list](https://docs.olimi.ai/api-reference/endpoint/customer-list/create-customer-list.md) | `POST /api/v2/customer-lists` |

> [!NOTE]
>
> Renaming and deleting customer lists isn't available through the API. Do it in the Dashboard.

## Authentication

Send your API key in the `X-API-KEY` header on every request, to the base URL `https://api-eg.olimi.ai`. See [API Authentication](https://docs.olimi.ai/api-auth.md).

You only ever see the customer lists that belong to the company your API key is issued to.

## Variants

A customer list can have extra columns beyond name and phone number, such as an order number, that the agent can mention during a call. These are called **variants**. Each one has:

* **`slug`**: the name the agent's script uses. A script that says `{{order_number}}` needs a variant with the slug `order_number`.
* **`name`**: the column's display name, for example `Order number`.

Two things depend on slugs matching:

* **Campaigns:** a campaign is refused with `missing_variants_…` if its agent's script uses a variable that one of its customer lists has no variant for. See [Campaigns](https://docs.olimi.ai/api-reference/endpoint/campaigns/campaigns.md#errors).
* **Contacts:** each contact stores its value for a variant under the variant's `id`. See [Custom fields](https://docs.olimi.ai/api-reference/endpoint/contacts/contacts.md#custom-fields).

Choose slugs carefully when you create a list. They can't be changed through the API afterwards.

## Customer list fields

| Field | Type | Meaning |
| - | - | - |
| `id` | UUID | The customer list's ID. |
| `organizationId` | UUID | Your company's ID. |
| `name` | string | The list's name. |
| `allowDuplication` | boolean \| null | Whether the list accepts a phone number more than once. `null` means no. |
| `totalContacts` | integer | Contacts in the list. |
| `answeredCount` | integer | List only. Contacts in the list who answered at least one campaign call. |
| `variants` | object\[] | Get and create only. The list's custom columns. See [Variant object](#variant-object). |
| `createdAt` | string | When the list was created (ISO 8601, UTC). |
| `updatedAt` | string | When the list was last changed (ISO 8601, UTC). |

### Variant object

| Field | Type | Meaning |
| - | - | - |
| `id` | UUID | The variant's ID. Send it as `variantId` when adding or editing contacts. |
| `slug` | string | The name the agent's script uses. |
| `name` | string | The column's display name. |
| `createdAt` | string | When the variant was created (ISO 8601, UTC). |
| `updatedAt` | string | When the variant was last changed (ISO 8601, UTC). |

## Errors

Always branch on `statusCode` first. Most errors also carry a machine-readable `errorCode`:

```json theme={null}
{
  "statusCode": 404,
  "errorCode": "customer_not_found",
  "message": "Customer not found"
}
```

| Status | `errorCode` | When |
| - | - | - |
| `400` | none | The `id` in the URL isn't a valid UUID. |
| `401` | `unauthenticated` | The `X-API-KEY` header is missing or the key isn't valid. |
| `404` | `customer_not_found` | Get only. No customer list with that `id` belongs to your company, or it was deleted. |
| `400` | `failed_update_data` | List only. `page` or `limit` is zero or negative. |
| `422` | none | Create only. The request body didn't pass validation. |

Validation errors (`422`) have a different body. `message` is a list of what went wrong, and there's no `errorCode`:

```json theme={null}
{
  "statusCode": 422,
  "message": ["name must be shorter than or equal to 100 characters"],
  "error": "Unprocessable Entity"
}
```

The `message` text is for humans and may change, so don't match on it.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.