Update customer attributes

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

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. Bulk requests run asynchronously, as described in Bulk operations.