# Customers

> Look up the customers who write to you.

A customer is a person who writes to you. Customers appear when someone writes through the widget, and gain a name and email when you [identify signed-in customers](https://tirver.com/help/identify-signed-in-customers.md). The API can list and read customers. It cannot create or change them.

## The customer object

| Field | Type | Meaning |
|---|---|---|
| `id` | string | The customer id. This is the `customer_id` on conversations. |
| `name` | string or null | Display name. |
| `email` | string or null | Email address. |
| `external_id` | string or null | The user id your product passed when identifying them. |
| `attributes` | object | Custom attributes. |
| `last_seen_at` | string or null | When they were last seen. |
| `created_at` | string | When they first appeared. |

## List customers

`GET /api/v1/customers`

Needs the `customers:read` scope. Newest first.

| Parameter | Type | What it does |
|---|---|---|
| `q` | string | Customers whose name or email contains this text. |
| `email` | string | Only the customer with this email address. Exact, not case sensitive. |
| `external_id` | string | Only the customer with this user id from your product. |
| `limit` | integer | Page size, 1 to 100. Defaults to 25. |
| `cursor` | string | The `next_cursor` from the previous page. |

**curl**

```bash
curl "https://app.tirver.com/api/v1/customers?email=ada@example.com" \
  -H "Authorization: Bearer $TIRVER_API_KEY"
```

**JavaScript**

```js
const res = await fetch('https://app.tirver.com/api/v1/customers?email=ada@example.com', {
  headers: { Authorization: `Bearer ${process.env.TIRVER_API_KEY}` },
});
const { data } = await res.json();
```

**Python**

```python
res = requests.get(
    "https://app.tirver.com/api/v1/customers",
    params={"email": "ada@example.com"},
    headers={"Authorization": f"Bearer {os.environ['TIRVER_API_KEY']}"},
    timeout=10,
)
customers = res.json()["data"]
```

```json
{
  "data": [
    {
      "id": "3b7a91e4",
      "external_id": "42",
      "email": "ada@example.com",
      "name": "Ada Lovelace",
      "attributes": {},
      "last_seen_at": "2026-11-14T09:01:00.000Z",
      "created_at": "2026-10-02T08:30:00.000Z"
    }
  ],
  "next_cursor": null,
  "has_more": false
}
```

## Get a customer

`GET /api/v1/customers/{id}`

Needs `customers:read`. Returns one customer with the same fields plus `conversation_count`, the number of conversations they have had. To list those conversations, call [`GET /api/v1/conversations?customer_id=...`](https://tirver.com/help/api/conversations.md).

Source: https://tirver.com/help/api/customers