Update customer
/v1/customers/{id}org.permission.customer.updateorg.user.customer.writeThe API key or user must hold at least one of them. Legacy roles still work; prefer the others for new keys.
Updates a customer based on the unique customer ID.
Note
This endpoint is subject to Object Rate Limiting, which limits how many updates single user can make to a single customer. To learn more, see Rate limiting.
Company
If you omit the company, the customer will no longer be linked to the company.
Custom Attributes
Custom attributes are optional and allow you to specify custom key-value pairs.
Kustomer uses a naming convention for custom attributes to specify the field data type with a name suffix:
Naming Suffix
Numnumber or nullAtdate-time or nullStrstring or null, length: [ 0 .. 1024 ] charactersTxtstring or null, length: [ 0 .. 1024 ] charactersBoolboolean or nullUrlstring or null, format: uri
Customers
A customer is one person your team supports. Every conversation, message, note and custom object about that person hangs off their customer record, and agents see it all on a single timeline.
Kustomer is organized around the customer rather than the ticket. When someone emails, chats or calls for the first time, Kustomer creates a customer for them and matches later contact on the same email address, phone number or social handle back to that record. In the agent desktop the customer is the profile and the timeline of everything that has happened with them: conversations, orders and other custom objects, and tracked events. You can also create customers yourself, usually to sync people from your own database or CRM before they ever contact support.
Identifiers and matching
A customer carries several kinds of contact identifiers, each a list of objects with a type and an optional verified flag: emails, phones, whatsapps, socials and externalIds. Values in these lists must be unique across your org, because Kustomer uses them to route new inbound messages to the right person; a write that would give a second customer the same email, phone or external ID is rejected. When people genuinely share a contact point, such as a family email address, use sharedEmails, sharedPhones, sharedSocials or sharedExternalIds, which have no uniqueness rule.
externalId is a shortcut for your own ID for the person. Set it on create and you can look the customer up later by it, which makes syncs idempotent. You can also look customers up by email or phone.
What the record holds
Besides name, contact identifiers, locations, locale, timeZone and tags, a customer has a company (the company they belong to) and custom attributes under custom. Kustomer maintains several read-only summaries for you: conversationCounts (open, snoozed, done and all), lastConversation, lastMessageIn, lastActivityAt and preview, a snippet of the latest message.
Merging duplicates
Duplicates happen, for example when the same person writes from a work and a personal email. A merge combines a source customer into a target. Conversations, messages, notes and custom objects move to the target; contact identifiers, tags and custom attributes are combined (the target wins when both have the same custom attribute); and the source is deleted. A merge reports status as pending, running, success or error. Merging a customer into itself, or starting a merge while another one for the same pair is in progress, fails with 409 Conflict. There is no unmerge endpoint.
Which endpoint to use
| To | Call |
|---|---|
| Create, read, update or delete one customer | POST /v1/customers, GET, PUT, PATCH or DELETE /v1/customers/{id} |
| Find a customer by your own ID | GET /v1/customers/externalId={externalId} |
| Find a customer by contact details | GET /v1/customers/email={email} or GET /v1/customers/phone={phone} |
| Page through customers by created or updated date | GET /v1/customers |
| Import, update or delete up to 100 customers per request | POST, PUT or DELETE /v1/customers/bulk |
| Merge a duplicate into another customer | POST /v1/customers/merges |
| Check a merge, or list a customer's merges | GET /v1/customers/merges/{id} or GET /v1/customers/{id}/merges |
PUT merges the attributes you send into the record unless you add replace=true, but leaving out company unlinks the customer from their company, so always resend it. PATCH also accepts a JSON Patch body (Content-Type: application/json-patch+json), which is handy for appending one email or phone without resending the list; pass rev to make the write depend on the revision you last read. Customer updates are subject to object limits. GET /v1/customers only filters on createdAt and updatedAt; use search for anything richer. It pages with page and pageSize (default 100, up to 1,000; a larger value is treated as 1,000) and reads only the first 10,000 matches for a given filter — the same window as search. The last reachable page is min(999, floor(10,000 / pageSize)) using that capped size, so a request with pageSize=1001 is evaluated as pageSize=1000 and can reach page 10; a higher page returns 400. On that last reachable page, links.next is null and links.last points there even when meta.totalPages is higher. When pageSize does not divide 10,000, or the 999-page cap binds first, matches inside the window can be left unread (for example pageSize=333 stops at page 30 / 9,990 matches, and pageSize=5 stops at page 999 / 4,995) — compare meta.totalPages with the pages you read. If pages remain unread and the query matches 10,000 or fewer, restart from page=1 with a pageSize that divides 10,000 (such as 100, 250 or 500). If the query matches more than 10,000, restarting only re-reads the same window — split into smaller windows instead. Do not continue at the next page number after changing pageSize — page offsets depend on pageSize, so that can duplicate or skip matches. Omit sort for newest lastActivityAt first, or pass createdAt, -createdAt, updatedAt or -updatedAt. For larger exports, narrow with date filters or split into time windows; if more than 10,000 customers share one updatedAt, use search and split further with another filter such as a creation-date range. See pagination and search recipes. Bulk requests run asynchronously, as described in Bulk operations.
Path parameters
Customer ID.
"5f8efdd5d3de932f344ca367"Query parameters
If true, replace the full resource instead of applying merge semantics.
trueRequest body
application/jsonrequired"m""f"Responses
OK