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

# Customers

> Register, find, update and erase the people you support.

## Create or get a customer

[`POST /customers`](/api-reference/customers/create-or-get-a-customer) is *create or get*. Call it whenever you are about to start a conversation for a user, without checking first whether they exist.

* A new customer returns **`201`** with `created: true`.
* A customer you already sent returns **`200`** with `created: false`, unchanged.

The same `externalId`, **or** the same `email`, is the same customer.

```bash
curl https://api.usecerium.com/v1/customers \
  -H "Authorization: Bearer $CERIUM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "externalId": "user_8271",
    "name": "Ada Obi",
    "email": "ada@example.com",
    "phone": "+2348012345678"
  }'
```

**externalId** `string`

Your own id for the customer. 1 to 128 letters, numbers or `. _ : @ + -`.

**name** `string` *required*

Up to 255 characters.

**email** `string` *required*

A valid email. It is stored in lower case.

**phone** `string`

International format, for example `+2348012345678`.

**device** `object`

A push-notification device: `{ "token": "...", "platform": "ios" | "android" | "web" }`.

> [!WARNING]
>
> If the `externalId` belongs to one customer and the `email` to another, the call fails with `409` and `participant_conflict`. Fix the data on your side rather than retrying.

## Find a customer

Look up by your own id or by email:

```bash
curl "https://api.usecerium.com/v1/customers?externalId=user_8271" \
  -H "Authorization: Bearer $CERIUM_API_KEY"
```

The result is a list, so an unknown customer returns an empty `data` array and not `404`. To fetch by Cerium id use [`GET /customers/{customerId}`](/api-reference/customers/get-a-customer).

## Update a customer

[`PATCH /customers/{customerId}`](/api-reference/customers/update-a-customer) changes only what you send. Send at least one field.

| Field | Behaviour |
| - | - |
| `name`, `email`, `phone` | Replaced. |
| `tags` | The **whole set**. Tags you leave out are removed. Send `[]` to clear. Up to 20 tags of up to 30 characters. |
| `attributes` | Only the attributes you send change. A blank value or `null` removes one. |

```bash
curl -X PATCH https://api.usecerium.com/v1/customers/prt_8271 \
  -H "Authorization: Bearer $CERIUM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "tags": ["vip"], "attributes": { "plan": "Business", "country": null } }'
```

> [!NOTE]
>
> Attributes are defined by name in your Cerium dashboard. Sending an attribute that does not exist is refused with `unknown_attribute`. A request is checked in full before anything changes, so a refused request changes nothing.

## Erase a customer

See [Data privacy](/guides/data-privacy.md).
