Get one customer with history and health
Full detail for a single customer. Everything the customer detail page needs in one round trip:
/v1/customers/{customer_id}Viewer- Operation id
- get_customer
- Access
- Any workspace role can call this.
/v1/customers/{customer_id}Full detail for a single customer. Everything the customer detail page needs in one round trip:
- core profile and metadata
- the 10 most recent tickets
- the 10 most recent conversations, with channel, outcome and sentiment
- lifetime totals (tickets, conversations, turns, cost)
- sentiment and intent distributions
- first seen and last seen timestamps
recent_tickets and recent_conversations are capped at 10 each and are
not pageable. For the full ticket history, call GET /v1/tickets with
customer_id set.
health is a derived score from 0 to 100 with a label of champion,
healthy, monitor or at_risk. It is a plain formula, not a model, and
factors lists every contribution that moved the score, so a number can
always be explained. Treat the exact figure as advisory.
ticket_count repeats stats.tickets_total for older callers.
A customer in another workspace answers 404, the same as one that does not exist.
Tenancy: the request is scoped to one workspace, and the credential presented is what selects it. A caller with no membership in that workspace is refused with 404, which is indistinguishable from a workspace that does not exist.
Authorisation: any workspace role, including viewer. Reads are open to every member.
Access: Authorization: Bearer carrying either a realm access token or an API key. A key must hold the customers:read scope, and the workspace role of the person who owns it must meet the floor above.
A realm-issued access token, presented as Authorization: Bearer <token>. It acts as the person who signed in, and every operation resolves their workspace role live from the membership record.
In: header
Path Parameters
uuidResponse Body
application/json
application/json
application/json
curl -X GET "https://example.com/v1/customers/497f6eca-6276-4993-bfeb-53cbbbba6f08"{ "id": "9f1d6c4e-6b6e-4b31-9a5b-2f1c9a4d5e60", "display_name": "Sam Okafor", "email": "sam.okafor@northwind.example", "company": "Northwind Ltd", "country": "GB", "metadata": { "plan": "enterprise" }, "created_at": "2026-02-03T09:41:00+00:00", "updated_at": "2026-08-14T10:20:00+00:00", "first_seen": "2026-02-03T09:41:00+00:00", "last_seen": "2026-08-14T10:20:00+00:00", "stats": { "tickets_total": 9, "tickets_open": 1, "conversations": 4, "total_turns": 37, "total_cost_usd": 0.42, "resolved": 3, "handed_off": 1, "with_human_reply": 2 }, "sentiment_distribution": { "positive": 2, "neutral": 1, "negative": 1 }, "top_intents": [ { "intent": "billing_question", "count": 3 }, { "intent": "refund_request", "count": 1 } ], "health": { "score": 80, "label": "healthy", "factors": [ { "key": "recency", "label": "Active in last 14 days", "delta": 15 }, { "key": "handoffs", "label": "1 AI handoff", "delta": -5 } ] }, "recent_tickets": [ { "id": "5e8b0c31-7a4d-4f92-b6c8-1d3e2a5f7b90", "subject": "Card declined at checkout", "status": "open", "priority": "high", "created_at": "2026-08-14T10:20:00+00:00" } ], "recent_conversations": [ { "id": "e3f4a5b6-c7d8-4e9f-a0b1-c2d3e4f5a6b7", "channel": "web_widget", "host_app": "northwind-store", "outcome": "handed_off", "started_at": "2026-08-14T10:12:00+00:00", "total_turns": 9, "user_sentiment": "negative", "judged_sentiment": "negative", "had_human_reply": true, "agent_id": "5b2c1a90-1f2e-4a77-9c31-9e0b1d2c3f44" } ], "ticket_count": 9}