Skip to content

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.

OperationEndpointScope
Create or find a customerPOST /api/v1/customerscustomers:write
List customersGET /api/v1/customerscustomers:read
Get one customerGET /api/v1/customers/{id}customers:read
Update a customerPATCH /api/v1/customers/{id}customers:write
Get a customer's detailsGET /api/v1/customers/{id}/detailscustomers:read
Get a customer's conversationsGET /api/v1/customers/{id}/conversationsconversations:read
Link an identifier combinationPOST /api/v1/customer/linkcustomers:write
Read back your linksGET /api/v1/customer/linkcustomers:read
Remove your linksDELETE /api/v1/customer/linkcustomers:write
Link many at oncePOST /api/v1/customer/link/batchcustomers: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
    }
  }
}
FieldMeaning
stats.channels / channel_mixEvery 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_atTheir most recent activity
insights.resolution.resolution_ratePercentage 0–100, the same definition /analytics/summary uses for your whole workspace — just scoped to this one person
insights.resolution.endedClosed 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.

ParameterMeaning
statusOptional exact match: active, ended, resolved, escalated or abandoned
limit1–200, default 50
cursorThe 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"
}
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 ​

HTTPCodeWhere
400invalid_requestMissing identifiers on create/link, an empty update body, or more than 500 links in one batch
403insufficient_scopeA customers:*-only key calling GET /api/v1/customers/{id}/conversations, which needs conversations:read
404not_foundAn unknown customer id on get / update / details / conversations
409link_conflictThe identifiers are already linked to a different external_id
409identity_conflictCreate 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