API reference
Core resources
Customers, companies, conversations, messages, notes, drafts, KObjects, Klasses, search, bulk operations and more.
Server https://api.kustomerapp.com/v1 · 171 operations
This category describes endpoints related to your Kustomer CRM data. This includes standard objects (like Companies, Customers, Conversations, Message and Custom Objects), custom attributes, tracking events, and more.
For more information on the object model, see Data Model Overview in the Kustomer Help Center.
NOTE
If your Kustomer organization is using sensitive attributes, values for sensitive attributes may be masked in API responses for standard objects if the API token making the request does not have Read Sensitive permissions for the sensitive attributes. For more information on sensitive attributes and masking, see Data Masking in the Kustomer Help Center.
Audit Logs
The audit log is a read-only history of what happened in your Kustomer org, such as who changed a conversation, who signed in, and what a routing or business rule did. Each entry records the event, the object it touched, who or what did it, and the fields that changed.
Attachments
An attachment is a file, such as an image, PDF or recording, attached to a message, note, draft, forward or custom object comment. Kustomer stores a record describing the file, and you upload or download the bytes through short-lived signed URLs.
Brands
A brand represents one of the companies, products or storefronts you support from a single Kustomer org. Brands let each one have its own name and icon, chat widget settings, knowledge base and email addresses.
/v1/brandspostCreate brand/v1/brandsgetGet default brand/v1/brands/defaultgetList brand address mappings/v1/brandAddressespostCreate brand address mapping/v1/brandAddressespatchUpdate brand address mapping/v1/brandAddresses/{id}DELDelete brand address mapping by id/v1/brandAddresses/{id}DELDelete all mappings for an address/v1/brandAddresses/address/{address}DELDelete all mappings for a brand/v1/brandAddresses/brand/{brandId}getGet brand by ID/v1/brands/{id}patchUpdate brand/v1/brands/{id}Business Schedules
A business schedule defines your support team's working hours for each day of the week in one time zone, plus holidays when you're closed. Kustomer uses it to measure time in business hours, for SLAs, reporting, chat availability and workflow conditions.
Bulk Operations
A bulk operation is the background job Kustomer creates when you create, update or delete many records in one bulk request. You poll it to see when the job finishes, then read its batches to find out which records succeeded and which failed.
Companies
A company is an organization that your customers belong to, such as a business account. It holds the organization's contact details, tags and custom attributes, can own custom objects, and can sit in a parent-child hierarchy with other companies.
Companies (Bulk)
A company is an organization that your customers belong to, such as a business account. It holds the organization's contact details, tags and custom attributes, can own custom objects, and can sit in a parent-child hierarchy with other companies.
Companies (Hierarchy)
A company is an organization that your customers belong to, such as a business account. It holds the organization's contact details, tags and custom attributes, can own custom objects, and can sit in a parent-child hierarchy with other companies.
Conversations
A conversation is one support thread with one customer, such as an email exchange, a chat session or a phone call. It holds the work state agents manage, including status, assignment, priority and tags, and contains the thread's messages and notes.
/v1/conversationspostCreate conversation/v1/conversationsgetGet conversation by ID/v1/conversations/{id}putUpdate conversation/v1/conversations/{id}patchUpdate conversation attributes/v1/conversations/{id}DELDelete conversation/v1/conversations/{id}getGet conversation by external ID/v1/conversations/externalId={externalId}getGet conversation attachments/v1/conversations/{id}/attachmentsgetGet conversation events/v1/conversations/{id}/eventsConversations (Bulk)
A conversation is one support thread with one customer, such as an email exchange, a chat session or a phone call. It holds the work state agents manage, including status, assignment, priority and tags, and contains the thread's messages and notes.
Conversations (Messages)
A message is one communication between your team and a customer, such as an email, a chat line, a text, a call or a social post, recorded inside a conversation. Creating one through the API records it on the timeline; it does not deliver anything.
Conversations (Forwards)
A forward sends a copy of an entire conversation by email to someone outside it, such as a vendor, a warehouse or another department. It starts as a draft and is sent when you give it a send time.
Conversations (Time)
Conversation time records how long agents actively spent working on a conversation in Kustomer. Each record is one handle session, and the records together are the source for handle time reporting.
Conversations (Notes)
A note is an internal comment that your team leaves on a conversation. Customers never see notes; agents use them to hand off context, record what they checked, and @mention teammates.
Notes (Conversations)
A note is an internal comment that your team leaves on a conversation. Customers never see notes; agents use them to hand off context, record what they checked, and @mention teammates.
Customers (Bulk)
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.
Customers (Conversations)
A conversation is one support thread with one customer, such as an email exchange, a chat session or a phone call. It holds the work state agents manage, including status, assignment, priority and tags, and contains the thread's messages and notes.
Customers (Drafts)
A draft is an outbound message that hasn't been sent yet. Unlike creating a message, sending a draft makes Kustomer deliver it to the customer through a connected channel such as email, SMS, chat or WhatsApp.
Customers (Events)
Tracking events record what a person does in your website or app, such as viewing a page or starting a checkout, grouped into sessions on the customer's event history. Identity calls tie an anonymous visitor to a Kustomer customer.
Customers (KObjects)
A KObject is one record of a custom type that you define, such as a single order, booking or device. It belongs to a customer or company, shows up on their timeline, and can be searched and used in workflows like built-in data.
Customers (Merges)
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.
Customers (Messages)
A message is one communication between your team and a customer, such as an email, a chat line, a text, a call or a social post, recorded inside a conversation. Creating one through the API records it on the timeline; it does not deliver anything.
Customers (Notes)
A note is an internal comment that your team leaves on a conversation. Customers never see notes; agents use them to hand off context, record what they checked, and @mention teammates.
Customers (Unmasking Windows)
An unmasking window temporarily reveals a customer's sensitive data. While it is open, attributes marked sensitive on the customer and on their conversations, messages and custom objects are returned unmasked instead of hidden.
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.
/v1/customerspostCreate customer/v1/customersgetGet customer by ID/v1/customers/{id}putUpdate customer/v1/customers/{id}patchUpdate customer attributes/v1/customers/{id}DELDelete customer/v1/customers/{id}getGet customer by email/v1/customers/email={email}getGet customer by external ID/v1/customers/externalId={externalId}getGet customer by phone number/v1/customers/phone={phone}Custom Attributes
Custom attributes are your own fields on Kustomer objects, such as a loyalty tier on a customer or an order number on a conversation. Their metadata tells Kustomer each field's label, type, allowed values and sensitivity.
Drafts (Attachments)
An attachment is a file, such as an image, PDF or recording, attached to a message, note, draft, forward or custom object comment. Kustomer stores a record describing the file, and you upload or download the bytes through short-lived signed URLs.
Drafts
A draft is an outbound message that hasn't been sent yet. Unlike creating a message, sending a draft makes Kustomer deliver it to the customer through a connected channel such as email, SMS, chat or WhatsApp.
Forwards (Attachments)
An attachment is a file, such as an image, PDF or recording, attached to a message, note, draft, forward or custom object comment. Kustomer stores a record describing the file, and you upload or download the bytes through short-lived signed URLs.
KObjects (Custom Objects) (Bulk)
A KObject is one record of a custom type that you define, such as a single order, booking or device. It belongs to a customer or company, shows up on their timeline, and can be searched and used in workflows like built-in data.
KObjects (Custom Objects)
A KObject is one record of a custom type that you define, such as a single order, booking or device. It belongs to a customer or company, shows up on their timeline, and can be searched and used in workflows like built-in data.
/v1/klasses/{name}postCreate KObject/v1/klasses/{name}getGet KObject (custom object) by ID/v1/klasses/{name}/{id}putUpdate KObject (custom object) by ID/v1/klasses/{name}/{id}DELDelete KObject (custom object) by ID/v1/klasses/{name}/{id}getGet KObject by external ID/v1/klasses/{name}/externalId={externalId}Klasses
A Klass is a custom object type that you define, such as "Order" or "Subscription", with its own name, icon, color and attributes. Each record of that type is a KObject.
Media
Media are files your org stores in Kustomer for content rather than for a conversation, such as images embedded in knowledge base articles. You create a media record, upload the file to the temporary URL it returns, then reference the media ID where the file is used.
Messages (Bulk)
A message is one communication between your team and a customer, such as an email, a chat line, a text, a call or a social post, recorded inside a conversation. Creating one through the API records it on the timeline; it does not deliver anything.
Messages
A message is one communication between your team and a customer, such as an email, a chat line, a text, a call or a social post, recorded inside a conversation. Creating one through the API records it on the timeline; it does not deliver anything.
/v1/messages/{id}/redactionsgetGet messages/v1/messagespostCreate message/v1/messagesgetGet message by ID/v1/messages/{id}putUpdate message by ID/v1/messages/{id}patchUpdate message attributes by ID/v1/messages/{id}getGet a Message by External ID/v1/messages/externalId={externalId}Notes (Bulk)
A note is an internal comment that your team leaves on a conversation. Customers never see notes; agents use them to hand off context, record what they checked, and @mention teammates.
Notes
A note is an internal comment that your team leaves on a conversation. Customers never see notes; agents use them to hand off context, record what they checked, and @mention teammates.
Comments (Attachments)
An attachment is a file, such as an image, PDF or recording, attached to a message, note, draft, forward or custom object comment. Kustomer stores a record describing the file, and you upload or download the bytes through short-lived signed URLs.
Tracking Events
Tracking events record what a person does in your website or app, such as viewing a page or starting a checkout, grouped into sessions on the customer's event history. Identity calls tie an anonymous visitor to a Kustomer customer.
Search
Search finds customers, conversations, messages, companies, notes, custom objects and other records that match a set of criteria, the same way saved searches do in the agent desktop.
Satisfaction
Satisfaction surveys (CSAT) ask customers to rate their experience after a conversation. A survey defines the question, rating scale, channel and audience; each time one is sent, Kustomer creates a satisfaction response that tracks delivery and stores the customer's rating and comments.
SLAs
An SLA (service level agreement) is a response-time policy, such as "reply to urgent emails within one hour". Kustomer matches each conversation to one SLA and tracks deadlines for it, so agents can see what's about to breach and managers can report on what did.
Sub-Statuses
A sub-status adds detail inside one of the three main statuses, open, snoozed or done, such as "Waiting on warehouse" under snoozed or "Resolved by refund" under done. Admins define them, and agents pick one when they change a conversation's or custom object's status.
Snoozes
Snooze options are the preset choices, such as "2 Hours" or "Tomorrow", that agents pick from when they snooze a conversation or custom object. Each option says how to work out the wake-up time; snoozing hides the item until then and reopens it when the time comes.
Spam
Spam senders are your org's allow and block lists for inbound email. Each entry is one email address marked whitelist (never treated as spam) or blacklist (always treated as spam), and it overrides Kustomer's automatic spam detection for that sender.
Comments
A comment is a short internal note that agents leave on a custom object record, such as a task. Customers never see comments; they are for discussion among your team, with optional mentions and attachments.
/v1/kobjects/{id}/commentspostCreate comment on KObject/v1/kobjects/{id}/commentsgetGet comment by ID/v1/comments/{id}putUpdate comment by ID/v1/comments/{id}DELDelete comment by ID/v1/comments/{id}