# Cliento API reference: Customers

Base URL: `https://api.cliento.com`

The Customers APIs let an integration keep a location's customer register in step with another
system: find customers, and create, change and delete them.

A customer is one of three types, each with its own API:

- **Persons.** A person is an individual: the one who books, and the one the location sends
  reminders to.
- **Companies.** A company owns a vehicle or pays the invoice.
- **Vehicles.** A vehicle is what a garage or a car wash works on.

The Customers API searches all three types at once. Use it when you have a phone number or a
reference and do not know which type it belongs to.

Each customer belongs to one location. The links between them, such as a vehicle's owner, are not
available through the API yet.

What staff record about a person over time, such as a recipe, belongs to that person.

## Persons

The Persons API lets an integration list a location's persons, find one, and create, change and
delete them.

A person is an individual customer: someone who books an appointment, or the contact person for a
company or a vehicle. The location communicates with persons, so the phone number, the email
address and the consents for SMS and email reminders are on the person.

A person belongs to one location and has an id of the form `per_...`. Reading needs the scope
`customers:read`, and writing needs `customers:write`.

### Finding a person

Filter the list. Each filter matches the whole value, and several together match persons that have
all of them:

- `?email=`, an email address. Letter case is ignored.
- `?phoneNumber=`, in E.164 format with the plus sign percent-encoded (`%2B46701234567`). A number
  that staff typed in another format is not found.
- `?identityNumber=`, a personnummer or other identity number as it is stored.
- `?externalReference=`, the id you gave the person when you created it.

Only `externalReference` is unique: no two persons, companies or vehicles at a location share one,
though the reference of a deleted one can be used again. Two persons can share an email address or
a phone number, and sometimes an identity number, so the other filters can return several persons
and you choose between them.

When you do not know whether you are looking for a person, a company or a vehicle, search
Customers instead.

### Identity numbers

A person can have one identity number issued by an authority. It is sent and returned as
`identityNumber`, with a `type` and a `number`. An `identityNumber` that is not `null` needs
both. `null` in an update removes it. The number is kept as you send it. Only surrounding spaces
and any HTML markup are removed, before it is checked and stored. A personnummer and a
samordningsnummer are digits only, with no hyphen or space.

| `type` | What it is | Accepted `number` | Example |
|---|---|---|---|
| `se_personnummer` | Swedish personal identity number | Twelve digits, `YYYYMMDDNNNC`: the full year, the day between 01 and 31, and a valid check digit | `198604122385` |
| `se_samordningsnummer` | Swedish coordination number | Twelve digits like a personnummer, with 60 added to the day (61 to 91), and a valid check digit | `198604722382` |
| `se_reservnummer` | Swedish reserve number, given in healthcare to someone without the two above | 3 to 32 characters: upper-case letters A to Z, digits and hyphens | `19860412AB27` |
| `foreign` | A personal identity number from another country | Any text of 1 to 255 characters | `120486-1234` |
| `other` | Anything else | Any text of 1 to 255 characters | `EMP-00417` |

The check digit is the last digit and follows the Luhn algorithm over the last ten digits, that
is, without the century. A number that does not fit its type is refused with `validation_failed`
and `identityNumber.number` among the `fieldErrors`. More types may be added, so accept a `type`
you do not know in a response.

An identity number is not always unique. A create or an update is normally refused with
`duplicate` when another person at the location already has the number with the same `type`.
Staff can still register one number on several persons in Cliento, on purpose. A list filtered on
that number then returns each of them. Do not rely on a `type` and `number` identifying exactly
one person.

### List persons

`GET /v1/locations/{locationId}/persons`

Scope: `customers:read`

Stability: preview

The location's persons, oldest first, one page at a time. To find one, use the filters instead of reading the whole list; "Finding a person" under Persons says how each one matches.

**Parameters**

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `locationId` | path | string | Yes |  |
| `email` | query | string | No | Only persons with exactly this email address, whatever its letter case. Example: `anna.lindqvist@example.com`. |
| `phoneNumber` | query | string | No | Only persons with exactly this mobile number, in E.164 format. Percent-encode the plus sign as `%2B`. Example: `+46701234567`. |
| `identityNumber` | query | string | No | Only persons with exactly this identity number, as it is stored: a Swedish personnummer is twelve digits. Example: `198604122385`. |
| `externalReference` | query | string | No | Only the person you created with this `externalReference`. Example: `crm-88121`. |
| `limit` | query | integer (int32) | No | Page size, 1 to 200. Default 50. |
| `after` | query | string | No | The `nextCursor` of the previous page. |

**Responses**

| Status | Description | Body |
| --- | --- | --- |
| 200 | OK | PersonList |
| default | Any failure. See the Errors section. | Error |

### Create a person

`POST /v1/locations/{locationId}/persons`

Scope: `customers:write`

Stability: preview

Creates a person at the location. Send an `externalReference`, your own id for the person, to make the call safe to repeat. When a person at the location already has that reference, that person is returned unchanged with `200` and nothing is created. A person with an identity number that another person at the location already has, with the same `type`, is normally refused with `duplicate`.

**Parameters**

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `locationId` | path | string | Yes |  |
| `Idempotency-Key` | header | string | No | A value you make up for this one request, such as a UUID. Send the same value when you retry and the first answer is returned; see Retrying safely. Example: `8e03978e-40d5-43e8-bc93-6894a57f9324`. |

**Request body**: PersonCreate

**Responses**

| Status | Description | Body |
| --- | --- | --- |
| 200 | A person with this `externalReference` already existed. | Person |
| 201 | The person was created. | Person |
| default | Any failure. See the Errors section. | Error |

### Get a person

`GET /v1/locations/{locationId}/persons/{personId}`

Scope: `customers:read`

Stability: preview

**Parameters**

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `locationId` | path | string | Yes |  |
| `personId` | path | string | Yes |  |

**Responses**

| Status | Description | Body |
| --- | --- | --- |
| 200 | OK | Person |
| default | Any failure. See the Errors section. | Error |

### Get a person by id

`GET /v1/persons/{personId}`

Scope: `customers:read`

Stability: preview

The same person as under its location, found from its id. For a caller that holds an id and not the location it belongs to. The answer carries `locationId`.

**Parameters**

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `personId` | path | string | Yes |  |

**Responses**

| Status | Description | Body |
| --- | --- | --- |
| 200 | OK | Person |
| default | Any failure. See the Errors section. | Error |

### Update a person

`PATCH /v1/locations/{locationId}/persons/{personId}`

Scope: `customers:write`

Stability: preview

Changes only the fields in the request. Either all of them are changed or none. See `PersonUpdate` for how to clear a field.

**Parameters**

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `locationId` | path | string | Yes |  |
| `personId` | path | string | Yes |  |
| `Idempotency-Key` | header | string | No | A value you make up for this one request, such as a UUID. Send the same value when you retry and the first answer is returned; see Retrying safely. Example: `8e03978e-40d5-43e8-bc93-6894a57f9324`. |

**Request body**: PersonUpdate

**Responses**

| Status | Description | Body |
| --- | --- | --- |
| 200 | OK | Person |
| default | Any failure. See the Errors section. | Error |

### Delete a person

`DELETE /v1/locations/{locationId}/persons/{personId}`

Scope: `customers:write`

Stability: preview

A person with upcoming bookings cannot be deleted. Those bookings are cancelled or deleted in Cliento first.

**Parameters**

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `locationId` | path | string | Yes |  |
| `personId` | path | string | Yes |  |
| `Idempotency-Key` | header | string | No | A value you make up for this one request, such as a UUID. Send the same value when you retry and the first answer is returned; see Retrying safely. Example: `8e03978e-40d5-43e8-bc93-6894a57f9324`. |

**Responses**

| Status | Description | Body |
| --- | --- | --- |
| 204 | No Content |  |
| default | Any failure. See the Errors section. | Error |

## Recipes

**Industry: hair and beauty.** The Recipes API is for hair salons. It lets an integration save the colour that was mixed for a
customer, so that staff can read it in Cliento at the next visit. It is meant for a system that
mixes or measures colour itself, such as a scale or a dispenser.

A recipe belongs to a person and describes one visit. It has one or more bowls. Each bowl lists
its components and the amount of each.

Recipes are read and added under `/v1/locations/{locationId}/persons/{personId}/recipes`. A
recipe has an id of the form `rcp_...`. Reading needs the scope `customers:read`, and adding
needs `customers:write`.

- The list is newest first, so its first recipe is what the person got the last time.
- A recipe also shows in the person's log, the notes staff keep on a person in Cliento, written
  out as text. Staff can change or remove it there.
- A recipe is not changed through the API. When the mix is adjusted, add a new one.
- A recipe moves no stock. A component can name the product it was taken from (`productId`), but
  the withdrawal is recorded through the Stock movements API. To tie the two together, put the
  `externalReference` of that stock withdrawal in the recipe's `stockReference`.
- Amounts are decimal strings, such as `"22.5"`, in the unit you send with them.
- `properties` are your own names and values, for what has no field, such as a processing time.
  They can be set on the recipe, a bowl or a component. Staff see them in Cliento, written out
  with the recipe in the person's log.
- `appData` is a JSON object for your own system's use: it is stored and returned as it is, and
  never shown in Cliento.
- A location that keeps medical records, such as a clinic, takes no new recipes: adding one there
  is refused with `not_allowed`.

### List a person's recipes

`GET /v1/locations/{locationId}/persons/{personId}/recipes`

Scope: `customers:read`

Stability: preview

The person's recipes, newest first, one page at a time. The first one is what was mixed the last time.

**Parameters**

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `locationId` | path | string | Yes |  |
| `personId` | path | string | Yes |  |
| `limit` | query | integer (int32) | No | Page size, 1 to 200. Default 50. |
| `after` | query | string | No | The `nextCursor` of the previous page. |

**Responses**

| Status | Description | Body |
| --- | --- | --- |
| 200 | OK | RecipeList |
| default | Any failure. See the Errors section. | Error |

### Add a recipe to a person

`POST /v1/locations/{locationId}/persons/{personId}/recipes`

Scope: `customers:write`

Stability: preview

Adds a recipe to the person. It also shows in the person's log in Cliento, where staff read it. A recipe is not changed afterwards through the API: when the mix is adjusted, add a new recipe. Send an `Idempotency-Key` so that a repeat of the call does not add the recipe twice. Not available at a location that keeps medical records.

**Parameters**

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `locationId` | path | string | Yes |  |
| `personId` | path | string | Yes |  |
| `Idempotency-Key` | header | string | No | A value you make up for this one request, such as a UUID. Send the same value when you retry and the first answer is returned; see Retrying safely. Example: `8e03978e-40d5-43e8-bc93-6894a57f9324`. |

**Request body**: RecipeCreate

**Responses**

| Status | Description | Body |
| --- | --- | --- |
| 201 | Created | Recipe |
| default | Any failure. See the Errors section. | Error |

### Get a recipe

`GET /v1/locations/{locationId}/persons/{personId}/recipes/{recipeId}`

Scope: `customers:read`

Stability: preview

**Parameters**

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `locationId` | path | string | Yes |  |
| `personId` | path | string | Yes |  |
| `recipeId` | path | string | Yes |  |

**Responses**

| Status | Description | Body |
| --- | --- | --- |
| 200 | OK | Recipe |
| default | Any failure. See the Errors section. | Error |

## Companies

The Companies API lets an integration list a location's companies, find one, and create, change
and delete them.

A company is a business customer: the owner of a vehicle, or the one that pays the invoice for a
job. The location does not communicate with a company about a booking. It communicates with a
person, such as the company's contact person.

A company belongs to one location and has an id of the form `com_...`. Reading needs the scope
`customers:read`, and writing needs `customers:write`.

- **`organisationNumber`** is the Swedish organisation number: ten digits with a valid check
  digit, with no hyphen. A number that does not fit is refused with `validation_failed`.
- **`department`** names one part of a company, such as `Used cars`, for a location that registers
  each part as a company of its own.
- **To find a company**, filter the list on `organisationNumber` or on the `externalReference` you
  gave it.
- **An organisation number is not always unique.** A create or an update is normally refused with
  `duplicate` when another company at the location already has the number, whatever its
  `department`. Staff can still register one number on several companies in Cliento, on purpose.
  That is how the parts of one company come to be several companies. Do not rely on a number
  identifying exactly one company.

### List companies

`GET /v1/locations/{locationId}/companies`

Scope: `customers:read`

Stability: preview

The location's companies, oldest first, one page at a time. To find one, filter on its organisation number or your own reference.

**Parameters**

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `locationId` | path | string | Yes |  |
| `organisationNumber` | query | string | No | Only companies with exactly this organisation number, ten digits. Example: `5560360793`. |
| `externalReference` | query | string | No | Only the company you created with this `externalReference`. Example: `crm-88121`. |
| `limit` | query | integer (int32) | No | Page size, 1 to 200. Default 50. |
| `after` | query | string | No | The `nextCursor` of the previous page. |

**Responses**

| Status | Description | Body |
| --- | --- | --- |
| 200 | OK | CompanyList |
| default | Any failure. See the Errors section. | Error |

### Create a company

`POST /v1/locations/{locationId}/companies`

Scope: `customers:write`

Stability: preview

Creates a company at the location. Send an `externalReference`, your own id for the company, to make the call safe to repeat. When a company at the location already has that reference, that company is returned unchanged with `200` and nothing is created. A company with an organisation number that another company at the location already has is normally refused with `duplicate`.

**Parameters**

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `locationId` | path | string | Yes |  |
| `Idempotency-Key` | header | string | No | A value you make up for this one request, such as a UUID. Send the same value when you retry and the first answer is returned; see Retrying safely. Example: `8e03978e-40d5-43e8-bc93-6894a57f9324`. |

**Request body**: CompanyCreate

**Responses**

| Status | Description | Body |
| --- | --- | --- |
| 200 | A company with this `externalReference` already existed. | Company |
| 201 | The company was created. | Company |
| default | Any failure. See the Errors section. | Error |

### Get a company

`GET /v1/locations/{locationId}/companies/{companyId}`

Scope: `customers:read`

Stability: preview

**Parameters**

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `locationId` | path | string | Yes |  |
| `companyId` | path | string | Yes |  |

**Responses**

| Status | Description | Body |
| --- | --- | --- |
| 200 | OK | Company |
| default | Any failure. See the Errors section. | Error |

### Get a company by id

`GET /v1/companies/{companyId}`

Scope: `customers:read`

Stability: preview

The same company as under its location, found from its id. For a caller that holds an id and not the location it belongs to. The answer carries `locationId`.

**Parameters**

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `companyId` | path | string | Yes |  |

**Responses**

| Status | Description | Body |
| --- | --- | --- |
| 200 | OK | Company |
| default | Any failure. See the Errors section. | Error |

### Update a company

`PATCH /v1/locations/{locationId}/companies/{companyId}`

Scope: `customers:write`

Stability: preview

Changes only the fields in the request. Either all of them are changed or none. See `CompanyUpdate` for how to clear a field.

**Parameters**

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `locationId` | path | string | Yes |  |
| `companyId` | path | string | Yes |  |
| `Idempotency-Key` | header | string | No | A value you make up for this one request, such as a UUID. Send the same value when you retry and the first answer is returned; see Retrying safely. Example: `8e03978e-40d5-43e8-bc93-6894a57f9324`. |

**Request body**: CompanyUpdate

**Responses**

| Status | Description | Body |
| --- | --- | --- |
| 200 | OK | Company |
| default | Any failure. See the Errors section. | Error |

### Delete a company

`DELETE /v1/locations/{locationId}/companies/{companyId}`

Scope: `customers:write`

Stability: preview

A company with upcoming bookings cannot be deleted. Those bookings are cancelled or deleted in Cliento first.

**Parameters**

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `locationId` | path | string | Yes |  |
| `companyId` | path | string | Yes |  |
| `Idempotency-Key` | header | string | No | A value you make up for this one request, such as a UUID. Send the same value when you retry and the first answer is returned; see Retrying safely. Example: `8e03978e-40d5-43e8-bc93-6894a57f9324`. |

**Responses**

| Status | Description | Body |
| --- | --- | --- |
| 204 | No Content |  |
| default | Any failure. See the Errors section. | Error |

## Vehicles

**Industry: automotive.** The Vehicles API is for garages, car washes and other automotive businesses. It lets an
integration list a location's vehicles, find one, and create, change and delete them.

A vehicle is what the job is done on: the car, not its owner. The owner is a person or a company.
The location communicates with the vehicle's contact person, who is a person.

A vehicle belongs to one location and has an id of the form `veh_...`. Reading needs the scope
`customers:read`, and writing needs `customers:write`.

- **`registrationNumber`** identifies the vehicle. A vehicle needs a registration number or a
  `description`; it can have both.
- **`make`, `model`, `modelYear` and `colour`** are filled in from the Swedish vehicle register
  when staff look the registration number up in Cliento. They are not set through the API and are
  left out for a vehicle that has not been looked up.
- **To find a vehicle**, filter the list on `registrationNumber` or on the `externalReference` you
  gave it.
- **A registration number is not always unique.** A create or an update is normally refused with
  `duplicate` when another vehicle at the location already has the number. Staff can still
  register one number on several vehicles in Cliento, on purpose. Do not rely on a number
  identifying exactly one vehicle.

### List vehicles

`GET /v1/locations/{locationId}/vehicles`

Scope: `customers:read`

Stability: preview

The location's vehicles, oldest first, one page at a time. To find one, filter on its registration number or your own reference.

**Parameters**

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `locationId` | path | string | Yes |  |
| `registrationNumber` | query | string | No | Only vehicles with exactly this registration number. Example: `ABC123`. |
| `externalReference` | query | string | No | Only the vehicle you created with this `externalReference`. Example: `crm-88121`. |
| `limit` | query | integer (int32) | No | Page size, 1 to 200. Default 50. |
| `after` | query | string | No | The `nextCursor` of the previous page. |

**Responses**

| Status | Description | Body |
| --- | --- | --- |
| 200 | OK | VehicleList |
| default | Any failure. See the Errors section. | Error |

### Create a vehicle

`POST /v1/locations/{locationId}/vehicles`

Scope: `customers:write`

Stability: preview

Creates a vehicle at the location. Send an `externalReference`, your own id for the vehicle, to make the call safe to repeat. When a vehicle at the location already has that reference, that vehicle is returned unchanged with `200` and nothing is created. A vehicle with a registration number that another vehicle at the location already has is normally refused with `duplicate`.

**Parameters**

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `locationId` | path | string | Yes |  |
| `Idempotency-Key` | header | string | No | A value you make up for this one request, such as a UUID. Send the same value when you retry and the first answer is returned; see Retrying safely. Example: `8e03978e-40d5-43e8-bc93-6894a57f9324`. |

**Request body**: VehicleCreate

**Responses**

| Status | Description | Body |
| --- | --- | --- |
| 200 | A vehicle with this `externalReference` already existed. | Vehicle |
| 201 | The vehicle was created. | Vehicle |
| default | Any failure. See the Errors section. | Error |

### Get a vehicle

`GET /v1/locations/{locationId}/vehicles/{vehicleId}`

Scope: `customers:read`

Stability: preview

**Parameters**

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `locationId` | path | string | Yes |  |
| `vehicleId` | path | string | Yes |  |

**Responses**

| Status | Description | Body |
| --- | --- | --- |
| 200 | OK | Vehicle |
| default | Any failure. See the Errors section. | Error |

### Get a vehicle by id

`GET /v1/vehicles/{vehicleId}`

Scope: `customers:read`

Stability: preview

The same vehicle as under its location, found from its id. For a caller that holds an id and not the location it belongs to. The answer carries `locationId`.

**Parameters**

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `vehicleId` | path | string | Yes |  |

**Responses**

| Status | Description | Body |
| --- | --- | --- |
| 200 | OK | Vehicle |
| default | Any failure. See the Errors section. | Error |

### Update a vehicle

`PATCH /v1/locations/{locationId}/vehicles/{vehicleId}`

Scope: `customers:write`

Stability: preview

Changes only the fields in the request. Either all of them are changed or none. See `VehicleUpdate` for how to clear a field.

**Parameters**

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `locationId` | path | string | Yes |  |
| `vehicleId` | path | string | Yes |  |
| `Idempotency-Key` | header | string | No | A value you make up for this one request, such as a UUID. Send the same value when you retry and the first answer is returned; see Retrying safely. Example: `8e03978e-40d5-43e8-bc93-6894a57f9324`. |

**Request body**: VehicleUpdate

**Responses**

| Status | Description | Body |
| --- | --- | --- |
| 200 | OK | Vehicle |
| default | Any failure. See the Errors section. | Error |

### Delete a vehicle

`DELETE /v1/locations/{locationId}/vehicles/{vehicleId}`

Scope: `customers:write`

Stability: preview

A vehicle with upcoming bookings cannot be deleted. Those bookings are cancelled or deleted in Cliento first.

**Parameters**

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `locationId` | path | string | Yes |  |
| `vehicleId` | path | string | Yes |  |
| `Idempotency-Key` | header | string | No | A value you make up for this one request, such as a UUID. Send the same value when you retry and the first answer is returned; see Retrying safely. Example: `8e03978e-40d5-43e8-bc93-6894a57f9324`. |

**Responses**

| Status | Description | Body |
| --- | --- | --- |
| 204 | No Content |  |
| default | Any failure. See the Errors section. | Error |

## Customers

The Customers API searches persons, companies and vehicles at once. Use it when you do not know
which type of customer you are looking for. You can search by email address, by phone number, by
your own reference, or by an identifying number such as a personnummer or a vehicle registration
number.

A search returns a page of matching customers. Each match is a short entry that says which type
it is. That type's API has the full record.

The Customers API is read-only. Each type is created, changed and deleted through its own API.

- **Each entry is short**: its id, its `type`, its `locationId`, its name (for a vehicle, its
  `description`) and the number that identifies it. The id's prefix (`per_`, `com_`, `veh_`) and
  `type` say where to read the rest: Persons, Companies or Vehicles.
- **Filters** match the whole value, and several together match what has all of them: `?email=`,
  `?phoneNumber=` (in E.164 format with the plus sign percent-encoded), `?number=` (an identity
  number, an organisation number or a registration number) and `?externalReference=`. Add
  `?type=` to keep one type, and repeat it for several.
- An `externalReference` is unique among everything at a location, whatever its type.

### List customers of every type

`GET /v1/locations/{locationId}/customers`

Scope: `customers:read`

Stability: preview

The location's persons, companies and vehicles in one list of short entries, oldest first. Use it to find something when you do not know its type, for example from a phone number; then read it in full from Persons, Companies or Vehicles, as the id's prefix and `type` say.

**Parameters**

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `locationId` | path | string | Yes |  |
| `type` | query | array of string | No | Only these kinds: `person`, `company` or `vehicle`. Repeat the parameter for several. Example: `person`. |
| `email` | query | string | No | Only those with exactly this email address. Letter case is ignored. Example: `anna.lindqvist@example.com`. |
| `phoneNumber` | query | string | No | Only those with exactly this mobile number, in E.164 format. Percent-encode the plus sign as `%2B`. Example: `+46701234567`. |
| `number` | query | string | No | Only those with exactly this number: an identity number, an organisation number or a registration number. Example: `ABC123`. |
| `externalReference` | query | string | No | Only the one you created with this `externalReference`. Example: `crm-88121`. |
| `limit` | query | integer (int32) | No | Page size, 1 to 200. Default 50. |
| `after` | query | string | No | The `nextCursor` of the previous page. |

**Responses**

| Status | Description | Body |
| --- | --- | --- |
| 200 | OK | CustomerList |
| default | Any failure. See the Errors section. | Error |

### List customers across locations

`GET /v1/customers`

Scope: `customers:read`

Stability: preview

Lists the persons, companies and vehicles of every location this API key can be used on, as short entries, one page at a time. The call works only when sharing customers between locations is turned on for the organisation in Cliento. Otherwise it is refused with `not_allowed`, and you list customers per location instead. Each entry has the `locationId` it is registered at. Read the full record, change it or delete it under that location, in Persons, Companies or Vehicles. The filters work as on a location's list.

**Parameters**

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `email` | query | string | No | Only those with exactly this email address. Letter case is ignored. Example: `anna.lindqvist@example.com`. |
| `phoneNumber` | query | string | No | Only those with exactly this mobile number, in E.164 format. Percent-encode the plus sign as `%2B`. Example: `+46701234567`. |
| `externalReference` | query | string | No | Only those you created with this `externalReference`. A reference is unique within a location, not across them, so the list can return one match per location. Example: `crm-88121`. |
| `number` | query | string | No | Only those with exactly this number: an identity number, an organisation number or a registration number. Example: `ABC123`. |
| `type` | query | array of string | No | Only these kinds: `person`, `company` or `vehicle`. Repeat the parameter for several. Example: `person`. |
| `limit` | query | integer (int32) | No | Page size, 1 to 200. Default 50. |
| `after` | query | string | No | The `nextCursor` of the previous page. |

**Responses**

| Status | Description | Body |
| --- | --- | --- |
| 200 | OK | CustomerList |
| default | Any failure. See the Errors section. | Error |

### Get a customer of any type

`GET /v1/locations/{locationId}/customers/{customerId}`

Scope: `customers:read`

Stability: preview

The short entry for a person, a company or a vehicle, by its id.

**Parameters**

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `locationId` | path | string | Yes |  |
| `customerId` | path | string | Yes |  |

**Responses**

| Status | Description | Body |
| --- | --- | --- |
| 200 | OK | Customer |
| default | Any failure. See the Errors section. | Error |

### Get a customer of any type by id

`GET /v1/customers/{customerId}`

Scope: `customers:read`

Stability: preview

The short entry for a person, a company or a vehicle, found from its id. For a caller that holds an id and not the location it belongs to. The answer carries `locationId`.

**Parameters**

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `customerId` | path | string | Yes |  |

**Responses**

| Status | Description | Body |
| --- | --- | --- |
| 200 | OK | Customer |
| default | Any failure. See the Errors section. | Error |

## Customer log

**Coming soon.** Read and add the notes and files staff keep on a person, a company or a vehicle.

## Schemas

### Address

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `city` | string or null | No | Example: `Stockholm`. |
| `country` | string or null | No | Free text; an ISO 3166-1 alpha-2 code is recommended. Example: `SE`. |
| `line1` | string or null | No | Example: `Storgatan 12`. |
| `line2` | string or null | No | Example: `Lgh 1102`. |
| `line3` | string or null | No |  |
| `postCode` | string or null | No | Example: `111 51`. |

### Communication

What the person has agreed to receive. In an update, a field you leave out keeps its value. For a new person `smsReminders`, `emailReminders` and `reviewReminders` start as true and `marketing` as false: send `marketing` as true only when the person has agreed to marketing.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `emailReminders` | boolean | No | Booking reminders by email. |
| `marketing` | boolean | No | Marketing messages. |
| `reviewReminders` | boolean | No | Requests to review a visit. |
| `smsReminders` | boolean | No | Booking reminders by SMS. |

### Company

Represents a business a location serves. Belongs to one location.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `address` | Address | No |  |
| `createdAt` | string (date-time) | No |  |
| `department` | string | No | A part of the company, when the location serves several of them. Example: `Used cars`. |
| `email` | string | No | Example: `info@example.com`. |
| `externalReference` | string | No | Your own id for it, as sent when it was created. Example: `crm-88121`. |
| `id` | string | Yes | Example: `com_6Tn3wRd8Kq1Vb5Xs9LmPyA`. |
| `locationId` | string | Yes | Example: `loc_4fK9xQ2mLr8TzB1vNc7HdW`. |
| `name` | string | No | Example: `Bilfirman AB`. |
| `notes` | string | No | Staff-facing notes, at most 1000 characters. |
| `organisationNumber` | string | No | The Swedish organisation number: ten digits with a valid check digit, with no hyphen. Example: `5560360793`. |
| `otherPhoneNumber` | string | No | Example: `+4686543210`. |
| `phoneNumber` | string | No | Phone number, in E.164 format when it was set through this API. Example: `+46701234567`. |
| `updatedAt` | string (date-time) | No |  |

### CompanyCreate

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `address` | Address | No |  |
| `department` | string | No | A part of the company, when the location serves several of them. Example: `Used cars`. |
| `email` | string | No | Example: `info@example.com`. |
| `externalReference` | string | No | Your own id for it, at most 100 characters, such as its id in your system. It makes the create safe to repeat and lets you find it again. Compared exactly, letter case included. Example: `crm-88121`. |
| `name` | string | Yes | Example: `Bilfirman AB`. |
| `notes` | string | No | Staff-facing notes, at most 1000 characters. |
| `organisationNumber` | string | No | The Swedish organisation number: ten digits with a valid check digit, with no hyphen. Example: `5560360793`. |
| `otherPhoneNumber` | string | No | Example: `+4686543210`. |
| `phoneNumber` | string | No | Phone number in E.164 format: a plus sign, the country code and the number, at most 15 digits. Example: `+46701234567`. |

### CompanyList

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `data` | array of Company | Yes |  |
| `nextCursor` | string | No | Pass as `after` to fetch the next page. Absent on the last page. Example: `com_6Tn3wRd8Kq1Vb5Xs9LmPyA`. |

### CompanyUpdate

A JSON merge patch: send only what changes. A field you leave out keeps its value; a field set to `null` is cleared, except `name`, which cannot be cleared. `address` merges field by field.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `address` | Address or null | No |  |
| `department` | string or null | No | A part of the company, when the location serves several of them. Example: `Used cars`. |
| `email` | string or null | No | Example: `info@example.com`. |
| `name` | string | No | Example: `Bilfirman AB`. |
| `notes` | string or null | No | Staff-facing notes, at most 1000 characters. |
| `organisationNumber` | string or null | No | The Swedish organisation number: ten digits with a valid check digit, with no hyphen. Example: `5560360793`. |
| `otherPhoneNumber` | string or null | No | Example: `+4686543210`. |
| `phoneNumber` | string or null | No | Phone number in E.164 format: a plus sign, the country code and the number, at most 15 digits. Example: `+46701234567`. |

### Customer

The short entry for a person, a company or a vehicle. The id's prefix says which type, and that type's API has the rest.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | Yes | Example: `per_2QCtWVSaVO7yCRYBj1zsbA`. |
| `locationId` | string | Yes | Example: `loc_4fK9xQ2mLr8TzB1vNc7HdW`. |
| `name` | string | No | Example: `Anna Lindqvist`. |
| `number` | string | No | The number that identifies it, when it has one: a person's identity number, a company's organisation number or a vehicle's registration number. Example: `198604122385`. |
| `type` | string | Yes | `person`, `company` or `vehicle`. It also says where to read the rest: Persons, Companies or Vehicles. More values may be added. Example: `person`. |

### CustomerList

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `data` | array of Customer | Yes |  |
| `nextCursor` | string | No | Pass as `after` to fetch the next page. Absent on the last page. Example: `per_2QCtWVSaVO7yCRYBj1zsbA`. |

### CustomerOwner

Whose customer a person is within its location: the location's own, or that of one of the location's resources. A salon that rents out chairs uses it: a person served by a hairdresser who rents a chair is that resource's customer, and a person served by an employee is the location's. Many locations never record it, so `unassigned` is common and says nothing either way.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `resourceId` | string | No | The resource (see Resources) whose customer the person is. Present when `type` is `resource`. Example: `res_2QCtWVSaVO7yCRYBj1zsbA`. |
| `type` | string | Yes | `location`: the location's own customer. `resource`: the customer of one resource, named by `resourceId`. `unassigned`: not recorded. More values may be added. Values today: `location`, `resource`, `unassigned`. |

### Error

The body of every non-2xx response.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `code` | string | Yes | Stable, machine-readable error code. Values today: `invalid_request`, `validation_failed`, `entity_not_found`, `duplicate`, `merchant_required`, `code_already_used`, `gift_card_already_used`, `pin_not_recognised`, `insufficient_stock`, `not_allowed`, `request_in_progress`, `idempotency_key_reused`, `unauthenticated`, `forbidden`, `account_blocked`, `rate_limited`, `route_not_found`, `method_not_allowed`, `internal_error`. |
| `details` | object of any value | No | Extra detail. For `validation_failed`, `fieldErrors` maps each rejected field to the reason. |
| `message` | string | Yes | Human-readable explanation. Not stable; do not parse it. |

### IdentityNumber

A number issued by an authority that identifies a person, such as a personnummer. The accepted format of each type is listed under Persons.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `number` | string | Yes | In the format of its type: twelve digits for a Swedish personnummer. Example: `198604122385`. |
| `type` | string | Yes | The kind of number, in lower case, such as `se_personnummer` or `foreign`. More values may be added. Example: `se_personnummer`. |

### Person

Represents an individual a location serves. Belongs to one location.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `address` | Address | No |  |
| `communication` | Communication | Yes |  |
| `createdAt` | string (date-time) | No |  |
| `dateOfBirth` | string | No | ISO 8601 date. Example: `1986-04-12`. |
| `email` | string | No | Example: `anna.lindqvist@example.com`. |
| `externalReference` | string | No | Your own id for it, as sent when it was created. Example: `crm-88121`. |
| `gender` | string | No | One lower-case word such as `female`. More values may be added. Example: `female`. |
| `id` | string | Yes | Example: `per_2QCtWVSaVO7yCRYBj1zsbA`. |
| `identityNumber` | IdentityNumber | No |  |
| `locationId` | string | Yes | Example: `loc_4fK9xQ2mLr8TzB1vNc7HdW`. |
| `name` | string | No | Example: `Anna Lindqvist`. |
| `notes` | string | No | Staff-facing notes, at most 1000 characters. |
| `onlineBookingBlocked` | boolean | Yes | True when the person may not book online. |
| `otherPhoneNumber` | string | No | Example: `+4686543210`. |
| `owner` | CustomerOwner | Yes | Whose customer the person is within the location. See CustomerOwner. |
| `phoneNumber` | string | No | Mobile number, in E.164 format when it was set through this API. Example: `+46701234567`. |
| `updatedAt` | string (date-time) | No |  |

### PersonCreate

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `address` | Address | No |  |
| `communication` | Communication | No |  |
| `dateOfBirth` | string | No | ISO 8601 date. Example: `1986-04-12`. |
| `email` | string | No | Example: `anna.lindqvist@example.com`. |
| `externalReference` | string | No | Your own id for it, at most 100 characters, such as its id in your system. It makes the create safe to repeat and lets you find it again. Compared exactly, letter case included. Example: `crm-88121`. |
| `gender` | string | No | Values today: `male`, `female`, `other`. |
| `identityNumber` | IdentityNumber | No |  |
| `name` | string | Yes | Example: `Anna Lindqvist`. |
| `notes` | string | No | Staff-facing notes, at most 1000 characters. |
| `onlineBookingBlocked` | boolean | No | Set to true to stop the person booking online. |
| `otherPhoneNumber` | string | No | Example: `+4686543210`. |
| `phoneNumber` | string | No | Mobile number in E.164 format: a plus sign, the country code and the number, at most 15 digits. Example: `+46701234567`. |

### PersonList

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `data` | array of Person | Yes |  |
| `nextCursor` | string | No | Pass as `after` to fetch the next page. Absent on the last page. Example: `per_2QCtWVSaVO7yCRYBj1zsbA`. |

### PersonUpdate

A JSON merge patch: send only what changes. A field you leave out keeps its value; a text field, `identityNumber` or `address` set to `null` is cleared, except `name`, which cannot be cleared. `address` merges field by field; `identityNumber` is replaced as a whole. The booleans (`communication.*`, `onlineBookingBlocked`) are true or false and cannot be null.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `address` | Address or null | No |  |
| `communication` | Communication | No |  |
| `dateOfBirth` | string or null | No | ISO 8601 date. Example: `1986-04-12`. |
| `email` | string or null | No | Example: `anna.lindqvist@example.com`. |
| `gender` | string or null | No | Values today: `male`, `female`, `other`, `null`. |
| `identityNumber` | IdentityNumber or null | No |  |
| `name` | string | No | Example: `Anna Lindqvist`. |
| `notes` | string or null | No | Staff-facing notes, at most 1000 characters. |
| `onlineBookingBlocked` | boolean | No | Set to true to stop the person booking online. |
| `otherPhoneNumber` | string or null | No | Example: `+4686543210`. |
| `phoneNumber` | string or null | No | Mobile number in E.164 format: a plus sign, the country code and the number, at most 15 digits. Example: `+46701234567`. |

### Recipe

A record of what was mixed for a person at one visit. Belongs to that person.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `appData` | object of any value | No | The JSON object of your own that is stored with the recipe, returned as it is. Example: `{"formulaId":"F-2291"}`. |
| `bowls` | array of RecipeBowl | Yes | The bowls mixed, in order. |
| `createdAt` | string (date-time) | Yes | Example: `2026-10-11T09:24:31Z`. |
| `id` | string | Yes | Example: `rcp_4Kd8sWn2Qy6Hb9Tf3LmVxA`. |
| `note` | string | No | Example: `Slightly warmer than last time.`. |
| `personId` | string | Yes | Example: `per_6Jm2tRx8Lc4Nq7Bv5ZgWkD`. |
| `properties` | object of string | No | Example: `{"processingTime":"35 min"}`. |
| `stockReference` | string | No | Example: `treatment-2026-10-11-0042`. |
| `title` | string | No | Example: `Colour, roots and lengths`. |
| `updatedAt` | string (date-time) | No | When staff last changed the recipe in Cliento. Left out when they never have. Example: `2026-10-12T14:02:10Z`. |

### RecipeBowl

One bowl: what was mixed together, usually colour and a developer.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `components` | array of RecipeComponent | Yes | What went into the bowl, 1 to 20. |
| `properties` | object of string | No | Your own names and values for this bowl, with the same limits as a component's `properties`. Example: `{"processingTime":"35 min"}`. |
| `ratio` | string | No | Parts of colour to parts of developer. Example: `1:2`. |
| `title` | string | No | What the bowl is for. At most 200 characters. Example: `Roots`. |

### RecipeComponent

One thing that went into a bowl.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `amount` | string | Yes | How much, in `unit`, as a decimal string greater than 0 with at most three decimals. Example: `30`. |
| `name` | string | Yes | What it is, as the hairdresser reads it. At most 200 characters. Example: `Koleston Perfect 7/0`. |
| `productId` | string | No | The product the component was taken from, when it is one of the location's. Example: `prd_5Tg8mPq1Xc7Jd2Ls9WbNrK`. |
| `properties` | object of string | No | Your own names and values for this component, at most 30. A name is at most 100 characters and a value at most 500. Example: `{"brand":"Wella"}`. |
| `role` | string | No | What the component is in the mix, as one lower-case word such as `colour` or `developer`. The list is open, so accept a value you do not know. Example: `colour`. |
| `shade` | string | No | The shade code of a colour. At most 50 characters. Example: `7/0`. |
| `strengthPercent` | string | No | The strength of a developer in per cent, as a decimal string greater than 0 and at most 100, with at most two decimals. Example: `6`. |
| `unit` | string | Yes | The unit of `amount`, as the hairdresser reads it. At most 20 characters. Example: `g`. |

### RecipeCreate

What was mixed for a person at one visit.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `appData` | object of any value | No | A JSON object of your own, for what the recipe has no field for. It is stored and returned as it is, and never shown in Cliento. At most 16 kB. A number keeps the precision of a double; send a longer one as a string. Example: `{"formulaId":"F-2291"}`. |
| `bowls` | array of RecipeBowl | Yes | The bowls mixed, 1 to 20, in order. |
| `note` | string | No | Free text. At most 4000 characters. Example: `Slightly warmer than last time.`. |
| `properties` | object of string | No | Your own names and values for the whole recipe, with the same limits as a component's `properties`. Example: `{"processingTime":"35 min"}`. |
| `staffId` | string | No | The staff member who made the recipe, shown as its author in the person's log. Without it the author is the API key. Example: `stf_7Hn3kQw9Zr4Tb6Vy1MxPdE`. |
| `stockReference` | string | No | The `externalReference` of the stock document that took the recipe's products out of stock, when you recorded one. At most 100 characters. Example: `treatment-2026-10-11-0042`. |
| `title` | string | No | What the recipe is for. At most 200 characters. Example: `Colour, roots and lengths`. |

### RecipeList

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `data` | array of Recipe | Yes |  |
| `nextCursor` | string | No | Pass as `after` to fetch the next page. Absent on the last page. Example: `rcp_4Kd8sWn2Qy6Hb9Tf3LmVxA`. |

### Vehicle

Represents a vehicle a location works on. Belongs to one location.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `colour` | string | No | From the vehicle register. Example: `Red`. |
| `createdAt` | string (date-time) | No |  |
| `description` | string | No | What the vehicle is called in Cliento. A lookup in the vehicle register fills it in with the make, model, colour and year; staff can change it. Example: `The red van`. |
| `externalReference` | string | No | Your own id for it, as sent when it was created. Example: `crm-88121`. |
| `id` | string | Yes | Example: `veh_3Ks7pQx2Wn9Tb4Vd6HyRcE`. |
| `locationId` | string | Yes | Example: `loc_4fK9xQ2mLr8TzB1vNc7HdW`. |
| `make` | string | No | From the Swedish vehicle register, when staff have looked the vehicle up in Cliento. Not set through the API. Example: `Volvo`. |
| `model` | string | No | From the vehicle register. Example: `V60`. |
| `modelYear` | integer (int32) | No | From the vehicle register. Example: `2021`. |
| `notes` | string | No | Staff-facing notes, at most 1000 characters. |
| `registrationNumber` | string | No | The registration number, one to seven characters. Example: `ABC123`. |
| `updatedAt` | string (date-time) | No |  |

### VehicleCreate

A vehicle needs a `registrationNumber` or a `description`.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `description` | string | No | What the vehicle is called in Cliento, such as `The red van`. Example: `The red van`. |
| `externalReference` | string | No | Your own id for it, at most 100 characters, such as its id in your system. It makes the create safe to repeat and lets you find it again. Compared exactly, letter case included. Example: `crm-88121`. |
| `notes` | string | No | Staff-facing notes, at most 1000 characters. |
| `registrationNumber` | string | No | The registration number, one to seven characters. Example: `ABC123`. |

### VehicleList

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `data` | array of Vehicle | Yes |  |
| `nextCursor` | string | No | Pass as `after` to fetch the next page. Absent on the last page. Example: `veh_3Ks7pQx2Wn9Tb4Vd6HyRcE`. |

### VehicleUpdate

A JSON merge patch: send only what changes. A field you leave out keeps its value; a field set to `null` is cleared, but a vehicle must keep a `registrationNumber` or a `description`.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `description` | string or null | No | What the vehicle is called in Cliento, such as `The red van`. Example: `The red van`. |
| `notes` | string or null | No | Staff-facing notes, at most 1000 characters. |
| `registrationNumber` | string or null | No | The registration number, one to seven characters. Example: `ABC123`. |