# Customers

A customer is a person who holds tickets, identified by your own `externalId`.
You create customers from an email and name only. See the
[Customers](#customers) concept page for the full mental model.

A serialized customer object:

```json
{
  "id": "cus_ext_42",
  "email": "fan@example.com",
  "name": "Jordan Fan",
  "status": "active",
  "created_at": "2026-06-05T11:00:00.000Z"
}
```

`status` is `active` once the customer is fully provisioned, otherwise `pending`.

---

## POST /v1/customers

Create (or idempotently return) a customer. The `id` you supply as `externalId`
is your own stable identifier — reuse it everywhere you reference this customer
(issuing, transferring tickets).

**Scope:** `customers:write`

### Request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `externalId` | string | Yes | Your stable identifier for the customer. Becomes the customer `id`. |
| `email` | string | Yes | Customer email; tickets are delivered here. |
| `name` | string | No | Customer display name. |

Accepts an `Idempotency-Key` header.

### Example request

```bash
curl https://api.ticketconnect.example/v1/customers \
  -H "Authorization: Bearer sk_test_your_key_here" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: cus-001" \
  -d '{
    "externalId": "cus_ext_42",
    "email": "fan@example.com",
    "name": "Jordan Fan"
  }'
```

### Example response

```json
{
  "id": "cus_ext_42",
  "email": "fan@example.com",
  "name": "Jordan Fan",
  "status": "active",
  "created_at": "2026-06-05T11:00:00.000Z"
}
```

---

## GET /v1/customers/{id}

Retrieve a customer by the `externalId` you assigned.

**Scope:** `customers:write`

### Path params

| Param | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | Yes | The customer's `externalId`. |

### Example request

```bash
curl https://api.ticketconnect.example/v1/customers/cus_ext_42 \
  -H "Authorization: Bearer sk_test_your_key_here"
```

### Example response

```json
{
  "id": "cus_ext_42",
  "email": "fan@example.com",
  "name": "Jordan Fan",
  "status": "active",
  "created_at": "2026-06-05T11:00:00.000Z"
}
```