Customer Lists

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.

Endpoint	Request
List customer lists	`GET /api/v2/customer-lists`
Get a customer list	`GET /api/v2/customer-lists/{id}`
Create a customer list	`POST /api/v2/customer-lists`

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. 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.
Contacts: each contact stores its value for a variant under the variant’s id. See 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.
`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:

{
  "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:

{
  "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.

Getting Started

API Overview

Agents & Campaigns

Speech

Authentication

Variants

Customer list fields

Variant object

Errors

​Authentication

​Variants

​Customer list fields

​Variant object

​Errors

Authentication

Variants

Customer list fields

Variant object

Errors