Customers

View as Markdown

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. 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

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

JavaScript

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

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"]

{
  "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=....