Customers
Every person who has talked to your agents — by phone, WhatsApp, SMS, email or web chat — is one customer record, the same one the Studio Customers page shows. This API lets your own systems create and look up those records, read a customer's history and health metrics, and tell Perfox in advance who someone is before they've ever made contact.
| Operation | Endpoint | Scope |
|---|---|---|
| Create or find a customer | POST /api/v1/customers | customers:write |
| List customers | GET /api/v1/customers | customers:read |
| Get one customer | GET /api/v1/customers/{id} | customers:read |
| Update a customer | PATCH /api/v1/customers/{id} | customers:write |
| Get a customer's details | GET /api/v1/customers/{id}/details | customers:read |
| Get a customer's conversations | GET /api/v1/customers/{id}/conversations | conversations:read |
| Link an identifier combination | POST /api/v1/customer/link | customers:write |
| Read back your links | GET /api/v1/customer/link | customers:read |
| Remove your links | DELETE /api/v1/customer/link | customers:write |
| Link many at once | POST /api/v1/customer/link/batch | customers:write |
The link paths are singular: /customer/link
Every other operation on this page is under /customers. The four linking endpoints are /customer/link and /customer/link/batch — no s. It's easy to "fix" this by habit and get a 404.
Two scopes are in play here, deliberately: everything above needs customers:read or customers:write except a customer's conversations, which needs conversations:read — a key scoped only for customer records still gets 403 insufficient_scope on that one endpoint, because it returns conversation data.
Identity fields
Every write here works with the same fields: name, phone (any format — canonicalized to E.164 on our side), email, external_id (your own system's stable id for this person), attributes (free-form key–value context — plan tier, account id, anything your business tracks), tags, and preferred_language.
Creating and finding a customer
bash
curl -X POST "https://<your-workspace>-api.perfox.ai/api/v1/customers" \
-H "Authorization: Bearer sk_…" \
-H "Content-Type: application/json" \
-d '{
"external_id": "acme-8841",
"name": "Priya Sharma",
"phone": "+919876543210",
"email": "priya@example.com",
"attributes": { "plan_tier": "premium" }
}'At least one of phone, email or external_id is required — without a strong identifier the record would have nowhere to resolve to, and the request is refused with 400 invalid_request.
This is create-or-find, not create-always: the identifiers you send are resolved the same way an inbound message is, so a phone number already talking to your agents on WhatsApp resolves to that same customer here instead of creating a duplicate. A brand-new match returns 201; a match against an existing customer returns 200. On an existing match, only name, preferred_language, tags and attributes from the body are applied — the phone, email and external_id you send are used to find the customer, never to overwrite the identifiers they already have.
Perfox never guesses between two customers
If the identifiers you send match more than one existing customer — the phone is on one record and the email on another — nothing is written and the call answers 409 identity_conflict with reason: "multiple_customers" and the two oldest matching customer_ids. Customers are never merged automatically: send one identifier, or the external_id, to address a single customer.
With an external_id in the body the call never conflicts. A customer already carrying that id wins; otherwise the id is stamped onto a phone/email match only when exactly one customer qualifies — with two, it gets a new record of its own (201).
json
{
"id": "01a0…",
"name": "Priya Sharma",
"phone": "+919876543210",
"email": "priya@example.com",
"external_id": "acme-8841",
"attributes": { "plan_tier": "premium" },
"created_at": "2026-09-25T10:12:00.000Z",
"updated_at": "2026-09-25T10:12:00.000Z"
}Listing and getting customers
GET /api/v1/customers returns { "data": [...], "has_more": false } — your 200 most recently updated customers, newest first. It takes no filter or paging parameters; has_more is true when older customers exist beyond those 200. Visitors who chatted without ever giving a name, phone, email or external id (the shared "Anonymous" bucket) are left out.
GET /api/v1/customers/{id} returns one customer, or 404 not_found.
Updating a customer
bash
curl -X PATCH "https://<your-workspace>-api.perfox.ai/api/v1/customers/01a0…" \
-H "Authorization: Bearer sk_…" \
-H "Content-Type: application/json" \
-d '{ "preferred_language": "hi", "tags": ["vip"] }'At least one field is required, or 400 invalid_request; an unknown id is 404 not_found.
PATCH does not overwrite everything you send
preferred_language always takes your new value. tags is additive — yours are merged in and de-duplicated, never removed. attributes is a merge: the keys you send are set, the keys you don't send are left alone. But name, phone, email and external_id are fill-in-if-missing — each one is written only when the customer doesn't already have a value for it. name specifically only changes while the customer still carries the placeholder name nobody has ever supplied one for.
So PATCHing a new phone number onto a customer who already has one succeeds (200) and applies everything else in the request, but the phone number itself stays what it was. This mirrors how every channel resolves identity — the first value observed wins, so a later message correcting a typo can't silently overwrite a name your team already confirmed. There's no field-reset on this endpoint; if you need to genuinely replace an identifier, that's a decision your own workflow should make deliberately, not a side effect of a routine sync.
A phone or email this customer doesn't have yet, but another customer already holds, is refused with 409 identity_conflict (reason: "held_by_another_customer", fields naming which) and nothing in the call is written — customers are never merged automatically. This applies under the default Business external ID only identity setting (Admin → Settings → Business); with Let Perfox unify by these fields, customers may share identifiers by design.
A customer's details — quick stats and insights
bash
curl "https://<your-workspace>-api.perfox.ai/api/v1/customers/01a0…/details" \
-H "Authorization: Bearer sk_…"Everything here is computed over all of this customer's conversations — never a page or a sample — the same numbers the Studio inspector's Profile and Insights tabs show.
json
{
"customer": { "id": "01a0…", "name": "Priya Sharma", "...": "..." },
"stats": {
"conversation_count": 14,
"channels": ["whatsapp", "email", "phone"],
"first_active_at": "2026-03-02T09:11:00.000Z",
"last_active_at": "2026-09-25T10:12:00.000Z"
},
"insights": {
"channel_mix": [
{ "channel": "whatsapp", "count": 9 },
{ "channel": "email", "count": 4 },
{ "channel": "phone", "count": 1 }
],
"resolution": {
"resolved": 10, "escalated": 1, "abandoned": 2, "active": 0, "ended": 1,
"total": 14, "resolution_rate": 71.43
}
}
}| Field | Meaning |
|---|---|
stats.channels / channel_mix | Every channel this customer has used, busiest first. A conversation that moved channel counts once per channel it touched |
stats.first_active_at | "Customer since" — their first conversation |
stats.last_active_at | Their most recent activity |
insights.resolution.resolution_rate | Percentage 0–100, the same definition /analytics/summary uses for your whole workspace — just scoped to this one person |
insights.resolution.ended | Closed by the system without a resolved verdict (idle timeout, a call that just ended) — distinct from abandoned |
An unknown id is 404 not_found. The conversations themselves aren't included here — see the next section.
A customer's conversations
bash
curl "https://<your-workspace>-api.perfox.ai/api/v1/customers/01a0…/conversations?status=resolved&limit=50" \
-H "Authorization: Bearer sk_…"Needs conversations:read. Returns every conversation this customer has had, newest-created first.
| Parameter | Meaning |
|---|---|
status | Optional exact match: active, ended, resolved, escalated or abandoned |
limit | 1–200, default 50 |
cursor | The previous page's next_cursor |
json
{
"conversations": [
{ "id": "01a0…", "customer_id": "01a0…", "status": "resolved", "channels": ["whatsapp"], "...": "..." }
],
"next_cursor": "2026-09-01T08:00:00.000Z"
}The cursor is a position, not an offset: a conversation created while you're mid-page is never skipped or shown twice, which an offset-based page can't promise once new conversations are landing concurrently. next_cursor is present only when another page remains — pass it straight back as cursor. Read one conversation's full transcript with GET /api/v1/conversations/{id}/events. An unknown customer id is 404 not_found.
Linking your own identifiers to a customer
Sometimes you know who someone is before they've ever contacted your workspace — a CRM import, a customer list from another system. POST /api/v1/customer/link tells Perfox in advance: "this email and phone belong to my id acme-8841", so the moment that person makes first contact on any channel, their conversation lands on a customer record carrying your external_id from the start.
bash
curl -X POST "https://<your-workspace>-api.perfox.ai/api/v1/customer/link" \
-H "Authorization: Bearer sk_…" \
-H "Content-Type: application/json" \
-d '{
"external_id": "acme-8841",
"identifiers": { "email": "priya@example.com", "mobile": "+919876543210" }
}'At least one of email or mobile is required — a name alone can't be looked up.
Identifiers combine with AND, not OR
{ "email": "family@example.com", "name": "Priya" } links only the person who is BOTH that email AND that name — it never matches "Raj", who happens to share the household email. Leave name out and the combination is broader: any customer with that email matches.
Applied now, or at first contact
If an existing customer already matches every identifier you sent, your external_id is stamped onto them immediately — the response includes applied_customer_id. If nobody matches yet, the mapping is stored and applies automatically the first time that person makes contact, on whichever channel they use.
Customers are never merged automatically. If your identifiers match more than one existing customer, or match a customer who already carries a different external_id, the call is refused with 409 identity_conflict and nothing is written — merging is a decision for a human, not a side effect of an API call. The error carries the reason (multiple_customers or customer_already_linked), up to 20 customer_ids, customer_count — how many customers matched in total — and, for an already-linked customer, its current_external_id. Linking a combination that an existing link (to a different external_id) would also match is refused with 409 link_conflict, naming that current_external_id; remove the old link first with DELETE /customer/link if you meant to replace it. Sending the identical link again is a no-op — it just confirms what's already there.
json
{
"external_id": "acme-8841",
"email": "priya@example.com",
"mobile": "+919876543210",
"applied_customer_id": "01a0…",
"created_at": "2026-09-25T10:12:00.000Z",
"updated_at": "2026-09-25T10:12:00.000Z"
}Reading back and removing your links
bash
curl "https://<your-workspace>-api.perfox.ai/api/v1/customer/link?external_id=acme-8841" \
-H "Authorization: Bearer sk_…"Returns { "links": [...] } — every identifier combination currently linked to that external_id, and which customer (if any) it was applied to. An external_id nobody has linked yet returns an empty list, not an error — there's nothing to distinguish it from "not yet used".
bash
curl -X DELETE "https://<your-workspace>-api.perfox.ai/api/v1/customer/link?external_id=acme-8841" \
-H "Authorization: Bearer sk_…"Removes every link row for that external_id and undoes only what a link call itself applied: the external_id is cleared from a customer only if they still carry the exact id that call stamped onto them. A customer who ended up with that id some other way — they gave it to your agent directly, or your own lookup tool set it during a conversation — keeps it. This is a link cleanup, not a data-subject erasure; raise that through Compliance & DPDP instead. Response: { "deleted": 1, "detached_customer_ids": ["01a0…"] }.
Linking many at once
bash
curl -X POST "https://<your-workspace>-api.perfox.ai/api/v1/customer/link/batch" \
-H "Authorization: Bearer sk_…" \
-H "Content-Type: application/json" \
-d '{
"links": [
{ "external_id": "acme-8841", "identifiers": { "email": "priya@example.com" } },
{ "external_id": "acme-9012", "identifiers": { "mobile": "+919876500002" } }
]
}'Up to 500 links per call, each applied and reported on its own — one row's conflict never blocks the rest of the import:
json
{
"results": [
{ "index": 0, "external_id": "acme-8841", "status": "linked", "applied_customer_id": "01a0…" },
{ "index": 1, "external_id": "acme-9012", "status": "link_conflict", "current_external_id": "acme-0007" }
]
}status is linked, link_conflict or identity_conflict — the same conflict rules as the single-item endpoint, decided independently per row. A conflicting row also carries current_external_id, or customer_ids and customer_count, as applicable. The batch call answers 200; the single-item link answers 201.
Errors
| HTTP | Code | Where |
|---|---|---|
| 400 | invalid_request | Missing identifiers on create/link, an empty update body, or more than 500 links in one batch |
| 403 | insufficient_scope | A customers:*-only key calling GET /api/v1/customers/{id}/conversations, which needs conversations:read |
| 404 | not_found | An unknown customer id on get / update / details / conversations |
| 409 | link_conflict | The identifiers are already linked to a different external_id |
| 409 | identity_conflict | Create or link: the identifiers match more than one customer. Link: the customer is already linked to a different external_id. Update: the phone or email belongs to another customer |
You can now …
- Create or find a customer from your own systems, without duplicating someone your agents already know
- List and look up customer records, and update their identity fields without accidentally clobbering what a conversation already confirmed
- Pull one customer's quick stats, channel mix and resolution rate — the same numbers as the Studio inspector, computed over their whole history
- Page through everything one customer has ever talked about, safely, while new conversations are still coming in
- Tell Perfox who someone is before they've ever said a word to you, so their first contact resolves straight onto the right record