Create or get a customer

POST /customers 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.
string
Your own id for the customer. 1 to 128 letters, numbers or . _ : @ + -.
string
required
Up to 255 characters.
string
required
A valid email. It is stored in lower case.
string
International format, for example +2348012345678.
object
A push-notification device: { "token": "...", "platform": "ios" | "android" | "web" }.
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:
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}.

Update a customer

PATCH /customers/{customerId} changes only what you send. Send at least one field.
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.