Customers
A customer is one of your customers: a business you are running calls for. Under the hood it is a full Kleos account, which is why it can do everything a Kleos account can do.
Use your own ids
Set external_ref when you create a customer and you never have to store a Kleos id. Every endpoint that accepts {id} accepts either.
GET /v1/customers/crm-8842
GET /v1/customers/0f2a6c4e-96a2-4f2e-8f2b-6c1a0e73d8b1 # same customerReferences are unique per account and per mode, and creating the same reference twice returns the existing customer with 200 rather than making a second one. That makes a retried signup safe even if you forgot the idempotency header.
What creating one does — and does not
It creates a record. It does not buy a number, publish an agent, send an email or place a call. Those are separate calls with their own permissions, so a bug in your signup flow cannot spend your balance.
The fields that actually matter
| Field | Why it matters |
|---|---|
country | Decides the calling rules, the agent's language, and which number Kleos needs. |
timezone | Decides when calling is permitted. An IANA name, e.g. Europe/Brussels. |
brand_name | What the agent calls the business out loud, when that differs from the legal name. |
website_url | Read during research, so the agent knows what the business actually sells. |
Country and timezone are the two worth getting right at signup. Both are hard to correct later without confusing a campaign that has already started.
Status
The status field reflects where the customer is in their life on the platform — prospect before anything runs, then pilot, active, paused or churned. It is not a readiness signal. For “can this customer take a call right now”, ask readiness.