# Customers

Represent each of your customers with your own ID, so you never store Ensue's.

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.

```bash
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](/dispatch/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.

> [!NOTE]
> A customer can have up to **20 endpoints**.