Customers
The businesses you run calls for. {id} is always either the Kleos id or your own external_ref.
List your customers
GET/v1/customers
Returns the customers created with a key in the SAME mode. A test key never sees live customers and a live key never sees test ones.
Permission: customers:read
Parameters
| Name | In | Type | |
|---|---|---|---|
limit | query | integer | How many to return. Defaults to 100, capped at 200. |
Response
{
"object": "list",
"data": [
{
"object": "customer",
"id": "0f2a6c4e-96a2-4f2e-8f2b-6c1a0e73d8b1",
"external_ref": "crm-8842",
"name": "Vandeputte Plumbing",
"brand_name": "Vandeputte",
"website_url": "https://vandeputte.be",
"country": "BE",
"timezone": "Europe/Brussels",
"status": "prospect",
"mode": "test",
"created_at": "2026-08-04T09:12:44.000Z"
}
],
"has_more": false
}Create a customer
POST/v1/customers
Creates the account one of your customers will be run under. Creating it provisions nothing: no number is bought, no agent is published, nothing dials. Send `Idempotency-Key` and a retry after a timeout is safe.
Permission: customers:write
Parameters
| Name | In | Type | |
|---|---|---|---|
Idempotency-Key | header | string | Your own unique string. Replaying it returns the first response for 24 hours. |
Body
| Field | Type | |
|---|---|---|
name * | string | The customer's legal or trading name. |
external_ref | string | Your own id for them. Unique per account, and usable in place of the Kleos id in every other call. |
brand_name | string | What the agent should call the business on a call, if it differs from `name`. |
website_url | string | Used for research before calls. |
country | string | ISO-3166 alpha-2. Decides the calling rules and the language the agent is certified in. |
timezone | string | IANA name, e.g. Europe/Brussels. Decides when calling is allowed. |
Response
{
"object": "customer",
"id": "0f2a6c4e-96a2-4f2e-8f2b-6c1a0e73d8b1",
"external_ref": "crm-8842",
"name": "Vandeputte Plumbing",
"brand_name": "Vandeputte",
"website_url": "https://vandeputte.be",
"country": "BE",
"timezone": "Europe/Brussels",
"status": "prospect",
"mode": "test",
"created_at": "2026-08-04T09:12:44.000Z"
}Refusals
| Status | Code | When |
|---|---|---|
| 400 | name_required | `name` was missing or blank. |
| 403 | customer_limit_reached | Your account has a customer ceiling and it is full. |
| 409 | idempotency_key_reused | The same `Idempotency-Key` arrived with a different body. |
Retrieve one customer
GET/v1/customers/{id}
`{id}` is either the Kleos id or your own `external_ref` — whichever you have to hand.
Permission: customers:read
Parameters
| Name | In | Type | |
|---|---|---|---|
id * | path | string | Kleos id or your `external_ref`. |
Response
{
"object": "customer",
"id": "0f2a6c4e-96a2-4f2e-8f2b-6c1a0e73d8b1",
"external_ref": "crm-8842",
"name": "Vandeputte Plumbing",
"brand_name": "Vandeputte",
"website_url": "https://vandeputte.be",
"country": "BE",
"timezone": "Europe/Brussels",
"status": "prospect",
"mode": "test",
"created_at": "2026-08-04T09:12:44.000Z"
}Refusals
| Status | Code | When |
|---|---|---|
| 404 | customer_not_found | No customer with that id in this mode. |
Can this customer take a live call yet?
GET/v1/customers/{id}/readiness
The honest answer, with machine-readable blockers. If `ready_for_live_calls` is false, the blocker list is exactly what the call path would refuse on — this endpoint never claims ready when a call would be turned away.
Permission: customers:read
Parameters
| Name | In | Type | |
|---|---|---|---|
id * | path | string | Kleos id or your `external_ref`. |
Response
{
"object": "readiness",
"customer_id": "0f2a6c4e-96a2-4f2e-8f2b-6c1a0e73d8b1",
"external_ref": "crm-8842",
"country": "BE",
"calling_language": "nl-BE",
"ready_for_live_calls": false,
"blockers": [
{
"code": "emporos_not_live",
"message": "This account is not approved for live calls yet."
},
{
"code": "no_number_in_country",
"message": "No Kleos number is available for this customer's country yet."
}
],
"checks": {
"account_live": false,
"business_verified": true,
"agreement_signed": true,
"balance_loaded": false,
"speech_certified_for_language": true,
"number_in_country": false,
"script_certified": false
}
}Refusals
| Status | Code | When |
|---|---|---|
| 404 | customer_not_found | No customer with that id in this mode. |