Customers

A customer is one of your customers, a tenant of your product. Dispatch groups endpoints by customer, so you can send an event to one customer, or to everyone who subscribes.

Identify customers with your own ID

Every customer has an external_id, your ID for them. Wherever Dispatch accepts a customer, you can pass your own ID or the cst_… ID Ensue assigns, so your application never needs to store a mapping.

Field	Notes
external_id	Your ID. Letters, numbers and _ . : @ -, up to 100 characters. Unique in the workspace.
name	Optional display name, up to 120 characters.
metadata	Optional key-value data of your own.

Create or update

PUT /v1/dispatch/customers/:external_id creates the customer, or updates it if it exists, so it is safe to call from your signup flow and your profile-update flow alike. Fields you leave out keep their value. It answers 201 for a new customer and 200 for an existing one.

curl -X PUT https://api.getensue.com/v1/dispatch/customers/acme \
  -H "authorization: Bearer ens_<key>" -H "content-type: application/json" \
  -d '{ "name": "Acme Inc", "metadata": { "plan": "business" } }'

POST /v1/dispatch/customers creates strictly and answers 409 customer_exists if the ID is taken. PATCH changes a name or metadata.

Delete a customer

DELETE /v1/dispatch/customers/:ref removes the customer and its endpoints. Messages you already sent stay in your history.

Customers and sends

When you send an event with customer: "acme", only that customer’s matching endpoints receive it. Leave customer out to send to every customer’s matching endpoints. See Send events.

A send that names a customer that doesn’t exist is refused, so a typo in an ID never silently sends nothing, or creates a customer you did not mean to.