How do AI agents use Kustomer through Open Connector?

Your user connects Kustomer once with one of its cataloged authentication methods. Open Connector stores the credential in an encrypted vault and exposes Kustomer tools to your agent over MCP or a typed API, with credentials injected server-side on each call.

Is this a Kustomer MCP server?

Yes. Open Connector can serve Kustomer as a named MCP server with a scoped allowlist and a per-user connection URL, so any MCP client can call Kustomer actions with credentials injected server-side.

Where do Kustomer credentials live?

In your own infrastructure. Open Connector keeps credentials in its own vault and injects them at call time, so they never leave your environment.

Kustomer integration

Kustomer integration for AI agents.

Kustomer integration for AI agents with secure authentication and server-side credential injection. Open Connector runs the OAuth, seals the token in an encrypted vault, and serves Kustomer tools to your agent over MCP or a typed API — credentials injected server-side, every call audited, nothing leaving your infrastructure. Open source (AGPL-3.0) and self-hostable.

View source on GitHub All integrations →

What your agents can do

Real Kustomer actions, managed and audited.

Your user connects Kustomer once; your agent can then use Kustomer to manage CRM customers, conversations, companies, messages, and related support data — scoped to the OAuth permissions you grant and the tool allowlist you configure. Every action is least-privilege and written to a tamper-evident audit trail.

1
Your user grants Kustomer access once (OAuth) — the token lands in the vault.
2
Your agent calls a tool over MCP or the typed API; Open Connector injects the credential server-side.
3
Every routed call appends a hash-chained audit record — nothing leaves your infra.

Tools & triggers

Supported Kustomer tools.

148 tools are generated from the published Kustomer catalog. Descriptions are plain text; each action remains subject to its configured authentication and tool allowlist.

Showing 148 tools. All published catalog entries are included in this page's server-rendered HTML.

Append tags to conversation: Adds tags to a conversation by the tag name and/or the unique ID of the conversation. Creates a new tag if a tag does not exist yet in your Kustomer organization. To learn more, see [Conversation tags](https://help.kustomer.com/conversations-tags-H1c4iVrIb) in the Kustomer Help Center. Any one of the following roles is required for this endpoint: |Legacy Role|Equivalent Permission Set Role| |-----|--------| |org.user.conversation.write|org.permission.conversation.update| ### Note > This endpoint is subject to Object Rate Limiting, which limits how many updates a single User can make to a single Conversation. See [Rate limiting](https://developer.kustomer.com/kustomer-api-docs/reference/rate-limiting) for more information.; Conversations (Tags)
Bulk batch update companies: Batch updates multiple companies. Any one of the following roles is required for this endpoint: |Legacy Role|Equivalent Permission Set Role| |-----|--------| |org.user.company.write|org.permission.company.update| ### Custom Attributes [Custom attributes](https://help.kustomer.com/define-attributes-Skr924HI) 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 * `Num` *number* or *null* * `At` *date-time* or *null* * `Str` *string* or *null*, length: [ 0 .. 1024 ] characters * `Txt` *string* or *null*, length: [ 0 .. 1024 ] characters * `Bool` *boolean* or *null* * `Url` *string* or *null*, format: *uri*; Companies (Bulk)
Bulk batch update conversations: Updates a bulk batch of conversations. Use the `ids` query param to update multiple conversations in bulk with the same data. Any one of the following roles is required for this endpoint: |Legacy Role|Equivalent Permission Set Role| |-----|--------| |org.user.conversation.write|org.permission.conversation.update|; Conversations (Bulk)
Bulk batch update customers: Updates a bulk batch of customers. Use the `ids` query param to update multiple customers in bulk with the same data. Any one of the following roles is required for this endpoint: |Legacy Role|Equivalent Permission Set Role| |-----|--------| |org.user.customer.write|org.permission.customer.update|; Customers (Bulk)
Bulk batch update KObjects (custom objects): Updates a bulk batch of multiple KObjects (custom objects). Use the `ids` query param to update multiple KObjects in bulk with the same data. Any one of the following roles is required for this endpoint: |Legacy Role|Equivalent Permission Set Role| |-----|--------| |org.user.kobject.write|org.permission.kobject.update| ||org.permission.kobject.kobject_*.update|; KObjects (Custom Objects) (Bulk)
Bulk batch update messages: Updates a bulk batch of messages. Use the `ids` query param to update multiple messages in bulk with the same data. Any one of the following roles is required for this endpoint: |Legacy Role|Equivalent Permission Set Role| |-----|--------| |org.user.message.write|org.permission.message.update|; Messages (Bulk)
Bulk batch update notes: Updates a bulk batch of notes. Use the `ids` query param to update multiple notes in bulk with the same data. Any one of the following roles is required for this endpoint: |Legacy Role|Equivalent Permission Set Role| |-----|--------| |org.user.note.write|org.permission.note.update|; Notes (Bulk)
Bulk create companies: Creates companies in bulk. Any one of the following roles is required for this endpoint: |Legacy Role|Equivalent Permission Set Role| |-----|--------| |org.user.company.write|org.permission.company.create| ### Custom Attributes [Custom attributes](https://help.kustomer.com/define-attributes-Skr924HI) 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 * `Num` *number* or *null* * `At` *date-time* or *null* * `Str` *string* or *null*, length: [ 0 .. 1024 ] characters * `Txt` *string* or *null*, length: [ 0 .. 1024 ] characters * `Bool` *boolean* or *null* * `Url` *string* or *null*, format: *uri*; Companies (Bulk)
Bulk create conversations: Create conversations in bulk. Any one of the following roles is required for this endpoint: |Legacy Role|Equivalent Permission Set Role| |-----|--------| |org.user.conversation.write|org.permission.conversation.create|; Conversations (Bulk)
Bulk create customers: Creates customers in bulk. Any one of the following roles is required for this endpoint: |Legacy Role|Equivalent Permission Set Role| |-----|--------| |org.user.customer.write|org.permission.customer.create|; Customers (Bulk)
Bulk create KObjects (custom objects): Creates KObjects (custom objects) in bulk. Any one of the following roles is required for this endpoint: |Legacy Role|Equivalent Permission Set Role| |-----|--------| |org.user.kobject.write|org.permission.kobject.create| ||org.permission.kobject.kobject_*.create|; KObjects (Custom Objects) (Bulk)
Bulk create messages: Creates a bulk batch of messages. Any one of the following roles is required for this endpoint: |Legacy Role|Equivalent Permission Set Role| |-----|--------| |org.user.message.write|org.permission.message.create|; Messages (Bulk)
Bulk create notes: Creates a bulk batch of notes. Any one of the following roles is required for this endpoint: |Legacy Role|Equivalent Permission Set Role| |-----|--------| |org.user.note.write|org.permission.note.create|; Notes (Bulk)
Bulk delete conversations: Deletes multiple conversations in bulk. Use the `ids` query param to delete multiple conversations in bulk. Any one of the following roles is required for this endpoint: |Legacy Role|Equivalent Permission Set Role| |-----|--------| |org.user.conversation.write|org.permission.conversation.delete|; Conversations (Bulk)
Bulk delete customers: Deletes multiple customers in bulk. Any one of the following roles is required for this endpoint: |Legacy Role|Equivalent Permission Set Role| |-----|--------| |org.user.customer.delete|org.permission.customer.delete|; Customers (Bulk)
Bulk delete KObjects (custom objects): Deletes multiple KObjects in bulk. Any one of the following roles is required for this endpoint: |Legacy Role|Equivalent Permission Set Role| |-----|--------| |org.user.kobject.delete|org.permission.kobject.delete| ||org.permission.kobject.kobject_*.delete|; KObjects (Custom Objects) (Bulk)
Create attachment: Creates a new attachment document. Includes a temporary upload policy for uploading the file with a POST request. Any one of the following roles is required for this endpoint: |Legacy Role|Equivalent Permission Set Role| |-----|--------| |org.user.note.write|org.permission.note.create| |org.user.message.write|org.permission.message.create| ### Uploading attachments You can upload attachments by sending a multi-part POST request to the URL found in the response object's `meta.upload.url` property. The request must be accompanied by the key/value pairs found in `meta.upload.fields` as standard form keys. The file should be included as the last key under the name "file".; Attachments
Create customer KObject (custom Object): Creates a new [KObject (custom object)](https://help.kustomer.com/define-attributes-Skr924HI) and links the KObject to a customer based on the unique customer ID. Any one of the following roles is required for this endpoint: |Legacy Role|Equivalent Permission Set Role| |-----|--------| |org.user.kobject.write|org.permission.kobject.create| ||org.permission.kobject.kobject_*.create|; Customers (KObjects)KObjects (Custom Objects)
Create draft attachment: Creates an attachment on a draft. ## Pre-signed URL When you create an attachment, the response will include a **related** URL in the **links** section. You can use this URL to upload the contents of the attachment. This URL is a Pre-Signed URL from S3 and provides access to upload a file for a limited duration. ### Example command to upload an attachment to the related Pre-Signed URL ```bash $ curl --upload-file [full path to file] "[Pre-Signed URL]" ```; Drafts (Attachments)
Create forward attachment: Creates an attachment on a forward. ## Pre-signed URL When you create an attachment, the response will include a **related** URL in the **links** section. You ca use this URL to upload the contents of the attachment. This URL is a Pre-Signed URL from S3 and provides access to upload a file for a limited duration. ### Example command to upload an attachment to the related Pre-Signed URL ```bash $ curl --upload-file [full path to file] "[Pre-Signed URL]" ```; Forwards (Attachments)
Create KObject: Creates a new KObject (custom object). Any one of the following roles is required for this endpoint: |Legacy Role|Equivalent Permission Set Role| |-----|--------| |org.user.kobject.write|org.permission.kobject.create| ||org.permission.kobject.kobject_*.create| ### Custom Attributes [Custom attributes](https://help.kustomer.com/define-attributes-Skr924HI) 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 * `Num` *number* or *null* * `At` *date-time* or *null* * `Str` *string* or *null*, length: [ 0 .. 1024 ] characters * `Txt` *string* or *null*, length: [ 0 .. 1024 ] characters * `Bool` *boolean* or *null* * `Url` *string* or *null*, format: *uri* ### Rate Limit Custom objects are subject to a rate limit. A single client can create up to 120 custom objects per minute per customer. #### Notes * Custom objects with `importedAt` in the body will not be subject to the rate limit. * A `429 Too Many Requests` response will be returned if the rate limit has been reached for a customer.; KObjects (Custom Objects)
Create media: Creates a new media upload document. This includes a temporary upload policy to allow a file upload through a `POST` request. ## Media uploads Media uploads require a mutli-part `POST` request to the URL in the `meta.upload.url` property in the response object: * The request must include as standard form keys the key-value pairs located in the `meta.upload.fields` property. * The request must include the file as the last key under the name `file`. ## Blocked extensions The following file name extensions are blocked and **cannot** be used as attachments: - .bin - .bat - .chm - .com - .cpl - .crt - .exe - .hlp - .hta - .inf - .ins - .isp - .jse - .lnk - .mdb - .msc - .msi - .msp - .mst - .pcd - .pif - .ps1 - .reg - .scr - .sct - .shs - .vbe - .vba - .vbs - .wsf - .wsh - .wsl; Media
Create message: Adds an instance of a message to an existing conversation timeline with a customer. Interactions with a customer that occurred via email, SMS, web or mobile chat, Facebook direct messages or comments, Twitter direct messages or Tweets, voice, Instagram direct messages or WhatsApp messages can be added to the conversation timeline. Does not sent a message to a customer, only to be used to record the instance of a message. To send a message, first see the [Create a draft by customer endpoint](https://developer.kustomer.com/kustomer-api-docs/reference/createadraftbycustomer). ### Prerequisites An existing conversation must be created to add the message. See the [Create conversation](https://developer.kustomer.com/kustomer-api-docs/reference/createaconversation) or [Bulk create conversations](https://developer.kustomer.com/kustomer-api-docs/reference/bulkcreateconversationshttps://developer.kustomer.com/kustomer-api-docs/reference/bulkcreateconversations) or [Create conversation for customer](https://developer.kustomer.com/kustomer-api-docs/reference/createaconversationforacustomer) endpoints. Any one of the following roles is required for this endpoint: |Legacy Role|Equivalent Permission Set Role| |-----|--------| |org.user.message.write|org.permission.message.create| ### Rate limit Messages are subject to a rate limit. A single client can create up to 120 messages per minute per customer. Messages with `importedAt` in their body will not be subject to the rate limit. A `429 Too Many Requests` response will be returned if the rate limit has been reached for a customer.; Messages
Create note: Creates a note. Any one of the following roles is required for this endpoint: |Legacy Role|Equivalent Permission Set Role| |-----|--------| |org.user.note.write|org.permission.note.create| ### Rate limit Notes are subject to a rate limit. A single client can create up to 120 notes per minute per customer.; Notes
Create a business schedule: Creates a new business schedule. Any one of the following roles is required for this endpoint: |Legacy Role|Equivalent Permission Set Role| |-----|--------| |org.admin.schedule.write|org.permission.schedule.create|; Business Schedules
Create snooze: Creates a new snooze option. Any one of the following roles is required for this endpoint: |Legacy Role|Equivalent Permission Set Role| |-----|--------| |org.admin.content.snooze.write|org.permission.snooze.create| |org.admin.snooze.write||; Snoozes
Create sub-status: Creates a new sub-status. Any one of the following roles is required for this endpoint: |Legacy Role|Equivalent Permission Set Role| |-----|--------| |org.admin.sub_status.write|org.permission.sub_status.create| |org.admin.content.sub_status.write||; Sub-Statuses
Create unmasking window by customer ID: Creates or replaces an unmasking window based on the unique customer ID. Any one of the following roles is required for this endpoint: |Legacy Role|Equivalent Permission Set Role| |-----------------------|--------------------------------------| |org.user.customer.write|org.permission.unmasking_window.create| ### Note > If an unmasking window is created for a customer, any sensitive attributes for the customer and for the customer's conversations, messages, and custom objects will be returned unmasked during the unmasking window period.; Customers (Unmasking Windows)Unmasking Windows
Create company: Creates a new company. Any one of the following roles is required for this endpoint: |Legacy Role|Equivalent Permission Set Role| |-----|--------| |org.user.company.write|org.permission.company.create| ### Custom Attributes [Custom attributes](https://help.kustomer.com/define-attributes-Skr924HI) 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 * `Num` *number* or *null* * `At` *date-time* or *null* * `Str` *string* or *null*, length: [ 0 .. 1024 ] characters * `Txt` *string* or *null*, length: [ 0 .. 1024 ] characters * `Bool` *boolean* or *null* * `Url` *string* or *null*, format: *uri*; Companies
Create conversation: Creates a new conversation. Any one of the following roles is required for this endpoint: |Legacy Role|Equivalent Permission Set Role| |-----|--------| |org.user.conversation.write|org.permission.conversation.create| ### Custom Attributes [Custom attributes](https://help.kustomer.com/define-attributes-Skr924HI) 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 * `Num` *number* or *null* * `At` *date-time* or *null* * `Str` *string* or *null*, length: [ 0 .. 1024 ] characters * `Txt` *string* or *null*, length: [ 0 .. 1024 ] characters * `Bool` *boolean* or *null* * `Url` *string* or *null*, format: *uri* ### Rate Limit Conversations are subject to a rate limit. A single client can create up to 120 conversations per minute per customer. Conversations with `importedAt` in their body will not be subject to the rate limit. A `429 Too Many Requests` response will be returned if the rate limit has been reached for a customer.; Conversations
Create conversation for customer: Creates a new, empty conversation for a customer. Any one of the following roles is required for this endpoint: |Legacy Role|Equivalent Permission Set Role| |-----|--------| |org.user.conversation.write|org.permission.conversation.create| ### Custom Attributes [Custom attributes](https://help.kustomer.com/define-attributes-Skr924HI) 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 * `Num` *number* or *null* * `At` *date-time* or *null* * `Str` *string* or *null*, length: [ 0 .. 1024 ] characters * `Txt` *string* or *null*, length: [ 0 .. 1024 ] characters * `Bool` *boolean* or *null* * `Url` *string* or *null*, format: *uri*; Customers (Conversations)
Create customer: Creates a new customer record. Any one of the following roles is required for this endpoint: |Legacy Role|Equivalent Permission Set Role| |-----|--------| |org.user.customer.write|org.permission.customer.create| ### Custom Attributes [Custom attributes](https://help.kustomer.com/define-attributes-Skr924HI) 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 * `Num` *number* or *null* * `At` *date-time* or *null* * `Str` *string* or *null*, length: [ 0 .. 1024 ] characters * `Txt` *string* or *null*, length: [ 0 .. 1024 ] characters * `Bool` *boolean* or *null* * `Url` *string* or *null*, format: *uri*; Customers
Create customer merge: Creates a [customer merge](https://help.kustomer.com/merge-customers-SksSuFLaZ) based on a set of source customer and target customer IDs. Any one of the following roles is required for this endpoint: |Legacy Role|Equivalent Permission Set Role| |-----|--------| |org.user.customer.write|org.permission.customer_merge.create| |org.admin.customer.merge.write| ### Merge rules Customer merges follow these rules: **Merge the following fields**: - Emails - Phones - Socials - Locations - Watchers - Custom (target customer ID takes precedence with same attribute names) - Tags - KlassNames - conversationCounts (sums all values) **Choose based on most recent value**: - Preview - Based on `preview.previewAt` - LastMessageIn - Based on `lastMessageIn.sentAt` - lastConversation - Based on `lastMessageIn.sentAt` - recentLocation - Based on `recentLocation.updatedAt` - signedUpAt - modifiedAt / modifiedBy - lastSeenAt - lastActivityAt **Choose based on the oldest value**: - createdAt / createdBy **Give precedence to the target customer ID value**: - Company - name - externalId - username - avatarUrl - locale - timeZone - birthdayAt - gender; Customers (Merges)
Create draft for customer: Creates an outbound draft to a customer through a specific channel (email, SMS, Facebook DM, etc). ### Scheduling drafts To schedule a draft to be sent at a future time, you must include both: - A `sendAt` timestamp that is in the future - `"scheduled": true` in the request body If `scheduled` is omitted, the system will override your `sendAt` value and create the draft immediately. --- ### Note drafts You can also create [note](https://help.kustomer.com/using-notes-HJvDjNP58) drafts by specifying the channel as `note` in the request body `channel` field. You can have one note draft per conversation. --- ### Rate limit Customer drafts are subject to a rate limit. A single client can create up to **120 drafts per minute per customer**, including drafts scheduled for the future. A `429 Too Many Requests` response will be returned if the rate limit has been reached for a customer. WhatsApp outbound messages are limited to **400 messages per minute per user**. This limit applies to both machine and non-machine (human) users. --- ### WhatsApp media file support When creating a WhatsApp draft that includes media, only specific file types are supported. Unsupported media types (e.g. `.videomp4`) will be blocked before submission to prevent send failures. **Supported file types for WhatsApp messages are:** - AUDIO: `aac`, `mp4`, `amr`, `mpeg`, `mp3`, `ogg`, `m4a` - VIDEO: `mp4`, `3gp`, `3gpp` - DOCUMENT: `txt`, `pdf`, `doc`, `docx`, `xls`, `xlsx`, `ppt`, `pptx` - IMAGE: `jpeg`, `jpg`, `png` - STICKER: `webp`; Customers (Drafts)
Create forward by conversation: Creates a forward to send through email. Forwards will send all messages in a conversation. ### NOTE > To schedule the forward for delivery, create a forward with a `sendAt` property. Any one of the following roles is required for this endpoint: |Legacy Role|Equivalent Permission Set Role| |-----|--------| |org.user.conversation_forward.write|org.permission.conversation_forward.create|; Conversations (Forwards)
Create Klass: Creates a new [Klass](https://help.kustomer.com/define-attributes-Skr924HI#Attributes) model for your Kustomer organization. Any one of the following roles is required for this endpoint: |Legacy Role|Equivalent Permission Set Role| |-----|--------| |org.admin.klass.write|org.permission.klass.create|; Klasses
Create message by customer ID: Creates a new message based on the unique customer ID. Any one of the following roles is required for this endpoint: |Legacy Role|Equivalent Permission Set Role| |-----|--------| |org.user.message.write|org.permission.message.create| ### Note > If a conversation is specified, the message will be linked to the existing conversation. Otherwise, a new conversation will be created and associated with the message. ### Authorization The `org.admin` role is required for setting `createdAt`, `createdBy`, `modifiedAt`, and `modifiedBy`. Otherwise, these attributes are automatically set by the token. ### Rate Limit Messages are subject to a rate limit. A single client can create up to 120 messages per minute per customer. Messages with `importedAt` in their body will not be subject to the rate limit. A `429 Too Many Requests` response will be returned if the rate limit has been reached for a customer.; Customers (Messages)Messages
Create message from conversation: Creates a new message from a conversation. ### NOTE > The new message created by the endpoint will be associated with the same customer as the conversation. Any one of the following roles is required for this endpoint: |Legacy Role|Equivalent Permission Set Role| |-----|--------| |org.user.message.write|org.permission.message.create| ### Authorization `org.admin` role is required for setting `createdAt`, `createdBy`, `modifiedAt`, and `modifiedBy`. Otherwise, the token automatically sets these attributes. ### Rate Limit Messages are subject to a rate limit. A single client can create up to 120 messages per minute per customer. Messages with `importedAt` in their body will not be subject to the rate limit. A `429 Too Many Requests` response will be returned if the rate limit has been reached for a customer.; Conversations (Messages)Messages
Create note within conversation: Creates a new note within a conversation. Optionally, allows you to @mention another user in your Kustomer organization. Any one of the following roles is required for this endpoint: |Legacy Role|Equivalent Permission Set Role| |-----|--------| |org.user.note.read|org.permission.note.create| ### Authorization The `org.admin` role is required for setting `createdAt`, `createdBy`, `modifiedAt`, and `modifiedBy`. Otherwise, these attributes are automatically set by the token. ### Rate limit Notes are subject to a rate limit. A single client can create up to 120 notes per minute per customer.; Notes (Conversations)Conversations (Notes)
Create tracking event: Creates a new tracking event. The following role is required for this endpoint: org.tracking; Tracking Events
Create tracking identity: Identifies a user. The following role is required for this endpoint: org.tracking; Tracking Events
Create tracking identity and track event: Identifies a user and tracks an event with a single API call. The following role is required for this endpoint: org.tracking; Tracking Events
Create customer archive search: Searches across all customer data with criteria based on a limited number of attributes on standard objects, including Message, Conversation, and Company objects, and on custom objects. Returns standard objects and custom objects older than 2 years ago that are unavailable in standard searches. Any one of the following roles is required for this endpoint: |Legacy Role|Equivalent Permission Set Role| |-----|--------| |org.user.search.read|org.permission.search.create| |org.admin.search.read|org.permission.search.update| ||org.permission.search_global.create| ||org.permission.search_preview.create| ## Filter on dates You can filter by dates in either a local date `YYYY-MM-DD` format or a UTC date format. If you include a timezone in the query, a local date will be adjusted to account for the included timezone. UTC dates will not be timezone adjusted. <br> ### Example of search criteria with local date ```json { "and": [ { "conversation_created_at": { "lte": "2020-11-19" } } ], "queryContext": "conversation", "timeZone": "America/New_York" } ``` #### Note > The default `GMT` timezone is applied when you exclude a timezone. ### Example of search criteria with UTC date ```json { "and": [ { "conversation_created_at": { "lte": "2020-11-20T16:34:00.000Z" } } ], "queryContext": "conversation" } ``` ## Filtering For a list of available standard attributes, see [Standard attributes JSON schema](https://developer.kustomer.com/kustomer-api-docs/reference/search#standard-attributes-json-schema). ### Example of search criteria with standard attributes ```json [ {"conversation_updated_at": {"gte": "2016-06-24" }}, {"conversation_customer_id": {"equals": "65f49506237963001f01a391" }} ] ``` ## Sort on attributes You can sort based on the following attributes: ``` conversation_created_at conversation_updated_at conversation_customer_id conversation_deleted customer_companyId customer_created_at customer_updated_at customer_deleted message_id message_created_at message_updated_at kobject_created_at kobject_updated_at ^kobject.*_created_at$ ^kobject.*_updated_at$ company_created_at company_updated_at ``` ### Example of sort with attributes ``` {"sort": [{"conversation_created_at": "asc"}]} {"sort": [{"message_id": "asc"}, {"message_created_at": "asc"}]} ``` #### Note > Sorting based on other standard Object attributes is unavailable. ## Pagination There is a hard limit of **100** for the maximum number of pages. There may be cases where you want to page through more records. For example, let's say you'd like to get an initial snapshot of data and then update the data. To work around the pagination limit, you can write a query based on the `updated_at` attribute for a standard Object. You can then use the returned information in following API requests based on the last `updated_at` value from the response. ## Filterable attributes JSON Schema ```json { "type": "object", "properties": { "customer_any_text_new": { "type": "string", "operator": "any" }, "customer_id": { "type": "string", "operator": "string_notanalyzed" }, "customer_created_at": { "type": "string", "format": "date-time", "operator": "datetime" }, "customer_updated_at": { "type": "string", "format": "date-time", "operator": "datetime" }, "customer_companyId": { "type": "string", "operator": "string_notanalyzed" }, "company_created_at": { "type": "string", "format": "date-time", "operator": "datetime" }, "company_updated_at": { "type": "string", "format": "date-time", "operator": "datetime" }, "message_any_text": { "type": "string", "operator": "any" }, "message_created_at": { "type": "string", "format": "date-time", "operator": "datetime" }, "message_updated_at": { "type": "string", "format": "date-time", "operator": "datetime" }, "message_conversation_id": { "type": "string", "operator": "string_notanalyzed" }, "conversation_any_text": { "type": "string", "operator": "any" }, "conversation_created_at": { "type": "string", "format": "date-time", "operator": "datetime" }, "conversation_updated_at": { "type": "string", "format": "date-time", "operator": "datetime" }, "conversation_customer_id": { "type": "string", "operator": "string_notanalyzed" }, "kobject_any_text": { "type": "string", "operator": "any" }, "kobject_created_at": { "type": "string", "format": "date-time", "operator": "datetime" }, "kobject_updated_at": { "type": "string", "format": "date-time", "operator": "datetime" }, }, "additionalProperties": false } ```; SearchCustomers (Search)
Create customer search: Searches across customer data with criteria based on standard Object data and any custom attribute data for standard Objects, including Message, Conversation, and Company objects. Standard object data, custom object data, and conversation time data is limited to objects that have an updatedAt more recent than in the past 2 years. To query for older, archived data for standard and custom objects, see the [Archive Search API](https://developer.kustomer.com/kustomer-api-docs/reference/customerarchivesearch). Older conversation time data is not available via search. Any one of the following roles is required for this endpoint: |Legacy Role|Equivalent Permission Set Role| |-----|--------| |org.user.search.read|org.permission.search.create| |org.admin.search.read|org.permission.search.update| ||org.permission.search_global.create| ||org.permission.search_preview.create| ## Filter on dates You can filter by dates in either a local date `YYYY-MM-DD` format or a UTC date format. If you include a timezone in the query, a local date will be adjusted to account for the included timezone. UTC dates will not be timezone adjusted. <br> ### Example of search criteria with local date ```json { "and": [ { "conversation_created_at": { "lte": "2020-11-19" } } ], "queryContext": "conversation", "timeZone": "America/New_York" } ``` #### Note > The default `GMT` timezone is applied when you exclude a timezone. ### Example of search criteria with UTC date ```json { "and": [ { "conversation_created_at": { "lte": "2020-11-20T16:34:00.000Z" } } ], "queryContext": "conversation" } ``` ## Filter on standard attributes For a list of available standard attributes, see [Standard attributes JSON schema](https://developer.kustomer.com/kustomer-api-docs/reference/search#standard-attributes-json-schema). ### Example of search criteria with standard attributes ```json [ {"customer_updated_at": {"gte": "2016-06-24" }}, {"conversation_status": {"equals": "done" }} ] ``` ## Filter on custom attributes for standard Objects You can query custom attibutes on on standard Objects with the following syntax: `<<standard_object_name>>_custom_<<custom_field_name>>`. ### Example of search criteria with custom attributes ```json { "customer_custom_myCustomStr": { "equals": "some value" }} { "message_custom_myCustomNum": { "gte": 5 }} ``` ## Filter on custom attributes for custom Objects You can query custom attributes for custom Object with the following syntax: `kobject_custom_<<klass_name>>_<<custom_field_name>>`. ### Examples ```json { "kobject_custom_myKlass_myCustomNum": { "gte": 5 }} ``` ## Sort on customer attributes You can sort based on the following customer attributes: ``` customer_name customer_gender customer_created_at customer_updated_at customer_modified_at customer_externalId customer_activity_at customer_last_seen_at customer_signed_up_at customer_lastmessage_preview customer_progressive_status customer_done customer_open customer_snoozed customer_last_message_sent_at customer_last_message_out_sent_at customer_last_message_unresponded_to_sent_at customer_last_message_at ``` ### Example of sort with customer attributes ``` {"sort": [{"customer_updated_at": "asc"}]} {"sort": [{"customer_gender": "asc"}, {"customer_created_at": "asc"}]} ``` #### Note > Sorting based on other standard Object attributes is unavailable. ## Pagination There is a hard limit of **100** for the maximum number of pages. There may be cases where you want to page through more records. For example, let's say you'd like to get an initial snapshot of data and then update the data. To work around the pagination limit, you can write a query based on the `updated_at` attribute for a standard Object. You can then use the returned information in following API requests based on the last `updated_at` value from the response. ## Standard attributes JSON Schema ```json { "type": "object", "properties": { "customer_any_text": { "type": "string", "operator": "any" }, "customer_name": { "type": "string", "operator": "string" }, "customer_gender": { "type": "string", "enum": ["m", "f"], "operator": "list" }, "customer_presence": { "type": "string", "enum": ["online", "offline", "idle"], "operator": "list" }, "customer_email": { "type": "string", "format": "email", "operator": "string" }, "customer_shared_email": { "type": "string", "format": "email", "operator": "string" }, "customer_phone": { "type": "string", "pattern": "^\\+?[1-9]\\d{1,14}$", "operator": "string" }, "customer_shared_phone": { "type": "string", "pattern": "^\\+?[1-9]\\d{1,14}$", "operator": "string" }, "customer_urls": { "type": "string", "operator": "string" }, "customer_address": { "type": "string", "operator": "string" }, "customer_locale": { "type": "string", "operator": "string" }, "customer_activity_at": { "type": "string", "format": "date-time", "operator": "datetime" }, "customer_last_seen_at": { "type": "string", "format": "date-time", "operator": "datetime" }, "customer_signed_up_at": { "type": "string", "format": "date-time", "operator": "datetime" }, "customer_last_message_sent_at": { "type": "string", "format": "date-time", "operator": "datetime" }, "customer_last_message_out_sent_at": { "type": "string", "format": "date-time", "operator": "datetime" }, "customer_last_message_unresponded_to_sent_at": { "type": "string", "format": "date-time", "operator": "datetime" }, "customer_last_message_at": { "type": "string", "format": "date-time", "operator": "datetime" }, "customer_externalId": { "type": "string", "operator": "string_notanalyzed" }, "customer_shared_externalId": { "type": "string", "operator": "string_notanalyzed" }, "customer_created_at": { "type": "string", "format": "date-time", "operator": "datetime" }, "customer_updated_at": { "type": "string", "format": "date-time", "operator": "datetime" }, "customer_modified_at": { "type": "string", "format": "date-time", "operator": "datetime" }, "customer_created_by": { "$ref": "#/definitions/user", "operator": "list" }, "customer_modified_by": { "$ref": "#/definitions/user", "operator": "list" }, "customer_satisfaction_avg_score": { "type": "number", "operator": "number" }, "customer_satisfaction_avg_rating": { "type": "number", "operator": "number" }, "customer_conversations_count": { "type": "number", "operator": "number" }, "customer_status": { "type": "string", "enum": ["snoozed", "open", "done"], "operator": "list" }, "customer_progressive_status": { "type": "string", "enum": ["snoozed", "open", "done"], "operator": "list" }, "customer_active_users": { "$ref": "#/definitions/user", "operator": "list" }, "customer_watchers": { "$ref": "#/definitions/user", "operator": "list" }, "customer_tags": { "type": "string", "operator": "list" }, "customer_sentiment": { "type": "string", "enum": ["happy", "unhappy", "indifferent"], "operator": "list" }, "customer_social_type": { "type": "string", "enum": ["facebook", "instagram", "whatsapp", "linkedin", "pinterest", "twitter"], "operator": "list" }, "customer_social_userid": { "type": "string", "operator": "string_notanalyzed" }, "customer_social_username": { "type": "string", "operator": "string_notanalyzed" }, "customer_shared_social_type": { "type": "string", "enum": ["facebook", "instagram", "whatsapp", "linkedin", "pinterest", "twitter"], "operator": "list" }, "customer_shared_social_userid": { "type": "string", "operator": "string_notanalyzed" }, "customer_shared_social_username": { "type": "string", "operator": "string_notanalyzed" }, "customer_default_lang": { "type": "string", "operator": "string_notanalyzed" }, "customer_imported_at": { "type": "string", "format": "date-time", "operator": "datetime" }, "customer_imported": { "type": "boolean", "operator": "boolean" }, "company_any_text": { "type": "string", "operator": "any" }, "company_name": { "type": "string", "operator": "string" }, "company_tags": { "type": "string", "operator": "list" }, "company_default_lang": { "type": "string", "operator": "string_notanalyzed" }, "company_imported_at": { "type": "string", "format": "date-time", "operator": "datetime" }, "company_imported": { "type": "boolean", "operator": "boolean" }, "message_any_text": { "type": "string", "operator": "any" }, "message_body": { "type": "string", "operator": "text" }, "message_channel": { "type": "string", "enum": ["sms", "chat", "email", "facebook", "voice", "twitter-dm", "twitter-tweet", "instagram", "whatsapp"], "operator": "list" }, "message_size": { "type": "number", "operator": "number" }, "message_direction": { "type": "string", "enum": ["in", "out"], "operator": "boolean" }, "message_sent_at": { "type": "string", "format": "date-time", "operator": "datetime" }, "message_created_at": { "type": "string", "format": "date-time", "operator": "datetime" }, "message_updated_at": { "type": "string", "format": "date-time", "operator": "datetime" }, "message_created_by": { "$ref": "#/definitions/user", "operator": "list" }, "message_modified_by": { "$ref": "#/definitions/user", "operator": "list" }, "message_sentiment": { "type": "string", "enum": ["happy", "unhappy", "indifferent"], "operator": "list" }, "message_customer_id": { "type": "string", "operator": "string_notanalyzed" }, "message_status": { "type": "string", "enum": ["sent", "received", "error"], "operator": "list" }, "message_error_at": { "type": "string", "format": "date-time", "operator": "datetime" }, "message_error_title": { "type": "string", "operator": "string" }, "message_external_id": { "type": "string", "operator": "string_notanalyzed" }, "message_direction_type": { "type": "string", "enum": ["initial-in", "initial-out", "response-in", "response-out", "followup-in", "followup-out"], "operator": "list" }, "message_created_by_teams": { "type": "string", "operator": "string_notanalyzed" }, "message_redacted": { "type": "string", "operator": "boolean" }, "message_redacted_at": { "type": "string", "format": "date-time", "operator": "datetime" }, "message_imported_at": { "type": "string", "format": "date-time", "operator": "datetime" }, "message_imported": { "type": "boolean", "operator": "boolean" }, "message_recipients": { "type": "string", "operator": "string" }, "message_sender": { "type": "string", "operator": "string" }, "message_shortcuts": { "type": "string", "operator": "string_notanalyzed" }, "message_subject": { "type": "string", "operator": "text" }, "message_source": { "type": "string", "enum": ["bulk"], "operator": "list" }, "message_attachment_count": { "type": "number", "operator": "number" }, "message_auto": { "type": "string", "operator": "boolean" }, "message_lang": { "type": "string", "operator": "string_notanalyzed" }, "note_any_text": { "type": "string", "operator": "any" }, "note_body": { "type": "string", "operator": "text" }, "note_created_at": { "type": "string", "format": "date-time", "operator": "datetime" }, "note_modified_at": { "type": "string", "format": "date-time", "operator": "datetime" }, "note_updated_at": { "type": "string", "format": "date-time", "operator": "datetime" }, "note_created_by": { "$ref": "#/definitions/user", "operator": "list" }, "note_modified_by": { "$ref": "#/definitions/user", "operator": "list" }, "note_deleted": { "$ref": "#/definitions/user", "operator": "boolean" }, "note_user_mentions": { "$ref": "#/definitions/user", "operator": "list" }, "note_team_mentions": { "type": "string", "pattern": "^(?=[A-Fa-f\\d]{24}$)(\\d+[A-Fa-f]|[A-Fa-f]+\\d)", "collection": "teams", "operator": "list" }, "note_attachment_count": { "$ref": "#/definitions/user", "operator": "number" }, "note_external_id": { "type": "string", "operator": "string_notanalyzed" }, "note_customer_id": { "type": "string", "operator": "string_notanalyzed" }, "note_conversation_id": { "type": "string", "operator": "string_notanalyzed" }, "note_lang": { "type": "string", "operator": "string_notanalyzed" }, "note_imported_at": { "type": "string", "format": "date-time", "operator": "datetime" }, "note_imported": { "type": "boolean", "operator": "boolean" }, "conversation_any_text": { "type": "string", "operator": "any" }, "conversation_name": { "type": "string", "operator": "string" }, "conversation_sentiment": { "type": "string", "enum": ["happy", "unhappy", "indifferent"], "operator": "list" }, "conversation_status": { "type": "string", "enum": ["snoozed", "open", "done"], "operator": "list" }, "conversation_sub_status": { "type": "string", "operator": "string_notanalyzed" }, "conversation_created_at": { "type": "string", "format": "date-time", "operator": "datetime" }, "conversation_updated_at": { "type": "string", "format": "date-time", "operator": "datetime" }, "conversation_modified_at": { "type": "string", "format": "date-time", "operator": "datetime" }, "conversation_modified_by": { "$ref": "#/definitions/user", "operator": "list" }, "conversation_message_count": { "type": "number", "operator": "number" }, "conversation_note_count": { "type": "number", "operator": "number" }, "conversation_satisfaction_survey_id": { "type": "string", "operator": "list" }, "conversation_satisfaction_sent_by": { "$ref": "#/definitions/user", "operator": "list" }, "conversation_satisfaction_sent_by_teams": { "type": "string", "pattern": "^(?=[A-Fa-f\\d]{24}$)(\\d+[A-Fa-f]|[A-Fa-f]+\\d)", "collection": "teams", "operator": "list" }, "conversation_satisfaction_created_at": { "type": "string", "format": "date-time", "operator": "datetime" }, "conversation_satisfaction_score": { "type": "number", "operator": "number" }, "conversation_satisfaction_rating": { "type": "number", "operator": "number" }, "conversation_satisfaction_status": { "type": "string", "enum": [ "canceled", "scheduled", "offered", "unresponded", "rated", "commented" ], "operator": "list" }, "conversation_channels": { "type": "string", "enum": ["sms", "chat", "email", "facebook", "voice", "twitter-dm", "twitter-tweet", "instagram", "whatsapp"], "operator": "list" }, "conversation_satisfaction": { "type": "string", "operator": "string" }, "conversation_priority": { "type": "integer", "operator": "number", "minimum": 1, "maximum": 5 }, "conversation_tags": { "type": "string", "operator": "list" }, "conversation_assigned_users": { "$ref": "#/definitions/user", "operator": "list" }, "conversation_assigned_teams": { "type": "string", "pattern": "^(?=[A-Fa-f\\d]{24}$)(\\d+[A-Fa-f]|[A-Fa-f]+\\d)", "collection": "teams", "operator": "list" }, "conversation_last_message_sent_at": { "type": "string", "format": "date-time", "operator": "datetime" }, "conversation_last_message_out_sent_at": { "type": "string", "format": "date-time", "operator": "datetime" }, "conversation_last_message_unresponded_to_sent_at": { "type": "string", "format": "date-time", "operator": "datetime" }, "conversation_last_message_at": { "type": "string", "format": "date-time", "operator": "datetime" }, "conversation_first_response_sent_at": { "type": "string", "format": "date-time", "operator": "datetime" }, "conversation_first_response_time": { "type": "number", "operator": "number" }, "conversation_first_response_created_by": { "$ref": "#/definitions/user", "operator": "list" }, "conversation_last_response_created_by": { "$ref": "#/definitions/user", "operator": "list" }, "conversation_last_message_direction": { "type": "string", "enum": ["in", "out"], "operator": "list" }, "conversation_direction": { "type": "string", "enum": ["in", "out"], "operator": "list" }, "conversation_outbound_message_count": { "type": "number", "operator": "number" }, "conversation_customer_id": { "type": "string", "operator": "string_notanalyzed" }, "conversation_campaign_id": { "type": "string", "operator": "string_notanalyzed" }, "conversation_first_message_in_sent_at": { "format": "date-time", "operator": "datetime" }, "conversation_first_message_in_direction_type": { "type": "string", "enum": ["initial-in", "initial-out", "response-in", "response-out", "followup-in", "followup-out"], "operator": "list" }, "conversation_first_message_in_channel": { "type": "string", "enum": ["sms", "chat", "email", "facebook", "voice", "twitter-dm", "twitter-tweet", "instagram", "whatsapp"], "operator": "list" }, "conversation_first_message_out_sent_at": { "format": "date-time", "operator": "datetime" }, "conversation_first_message_out_direction_type": { "type": "string", "enum": ["initial-in", "initial-out", "response-in", "response-out", "followup-in", "followup-out"], "operator": "list" }, "conversation_first_message_out_channel": { "type": "string", "enum": ["sms", "chat", "email", "facebook", "voice", "twitter-dm", "twitter-tweet", "instagram", "whatsapp"], "operator": "list" }, "conversation_time_created_at": { "type": "string", "format": "date-time", "operator": "datetime" }, "conversation_time_conversation_id": { "type": "string", "operator": "string_notanalyzed" }, "conversation_time_created_by_teams": { "type": "string", "pattern": "^(?=[A-Fa-f\\d]{24}$)(\\d+[A-Fa-f]|[A-Fa-f]+\\d)", "collection": "teams", "operator": "list" }, "conversation_time_assigned_users": { "$ref": "#/definitions/user", "operator": "list" }, "conversation_time_assigned_teams": { "type": "string", "pattern": "^(?=[A-Fa-f\\d]{24}$)(\\d+[A-Fa-f]|[A-Fa-f]+\\d)", "collection": "teams", "operator": "list" }, "conversation_time_touched": { "type": "string", "operator": "boolean" }, "conversation_time_reopened": { "type": "string", "operator": "boolean" }, "conversation_time_snoozed": { "type": "string", "operator": "boolean" }, "conversation_time_resolved": { "type": "string", "operator": "boolean" }, "conversation_time_message_at": { "type": "string", "format": "date-time", "operator": "datetime" }, "conversation_time_message_time": { "type": "number", "operator": "number" }, "conversation_time_messages_sent": { "type": "number", "operator": "number" }, "conversation_time_note_at": { "type": "string", "format": "date-time", "operator": "datetime" }, "conversation_time_note_time": { "type": "number", "operator": "number" }, "conversation_time_notes_sent": { "type": "number", "operator": "number" }, "conversation_time_handle_at": { "type": "string", "format": "date-time", "operator": "datetime" }, "conversation_time_handle_time": { "type": "number", "operator": "number" }, "conversation_time_channels": { "type": "string", "enum": ["sms", "chat", "email", "facebook", "voice", "twitter-dm", "twitter-tweet", "instagram", "whatsapp"], "operator": "list" }, "conversation_default_lang": { "type": "string", "operator": "string_notanalyzed" }, "any_text": { "type": "string", "operator": "any" }, "tracking_events": { "type": "string", "operator": "number" }, "conversation_sla_status": { "type": "string", "enum": ["done", "pending", "paused"], "operator": "list" }, "conversation_sla_version_id": { "type": "string", "operator": "string_notanalyzed" }, "conversation_sla_id": { "type": "string", "operator": "list" }, "conversation_sla_breached": { "type": "boolean", "operator": "boolean" }, "conversation_sla_breach_at": { "type": "string", "format": "date-time", "operator": "datetime" }, "conversation_sla_satisfied_at": { "type": "string", "format": "date-time", "operator": "datetime" }, "conversation_sla_breach_metric": { "type": "string", "enum": [ "firstResponse", "totalCustomerWaitTime", "longestUnrespondedMessage", "totalConversationOpenTime" ], "operator": "list" }, "conversation_first_done_created_by": { "$ref": "#/definitions/user", "operator": "list" }, "conversation_last_done_created_at": { "type": "string", "format": "date-time", "operator": "datetime" }, "conversation_last_done_created_by": { "$ref": "#/definitions/user", "operator": "list" }, "conversation_last_done_created_by_teams": { "type": "string", "pattern": "^(?=[A-Fa-f\\d]{24}$)(\\d+[A-Fa-f]|[A-Fa-f]+\\d)", "collection": "teams", "operator": "list" }, "conversation_reply_channel": { "type": "string", "enum": ["sms", "chat", "email", "facebook", "voice", "twitter-dm", "twitter-tweet", "instagram", "whatsapp"], "operator": "list" }, "conversation_queue": { "type": "string", "pattern": "^(?=[A-Fa-f\\d]{24}$)(\\d+[A-Fa-f]|[A-Fa-f]+\\d)", "collection": "queues", "operator": "list" }, "conversation_external_queue": { "type": "string", "enum": ["amazon-connect"], "operator": "list" }, "conversation_ended": { "type": "boolean", "operator": "boolean" }, "conversation_ended_at": { "type": "string", "format": "date-time", "operator": "datetime" }, "conversation_ended_reason": { "type": "string", "operator": "string" }, "conversation_imported_at": { "type": "string", "format": "date-time", "operator": "datetime" }, "conversation_imported": { "type": "boolean", "operator": "boolean" }, "kobject_any_text": { "type": "string", "operator": "any" }, "kobject_created_at": { "type": "string", "format": "date-time", "operator": "datetime" }, "kobject_updated_at": { "type": "string", "format": "date-time", "operator": "datetime" }, "kobject_imported_at": { "type": "string", "format": "date-time", "operator": "datetime" }, "kobject_imported": { "type": "boolean", "operator": "boolean" } }, "definitions": { "user": { "type": "string", "pattern": "^(?=[A-Fa-f\\d]{24}$)(\\d+[A-Fa-f]|[A-Fa-f]+\\d)", "collection": "users" } }, "additionalProperties": false } ```; SearchCustomers (Search)
Delete conversation: Delete a conversation based on the unique conversation ID. Any one of the following roles is required for this endpoint: |Legacy Role|Equivalent Permission Set Role| |-----|--------| |org.user.conversation.delete|org.permission.conversation.delete|; Conversations
Delete customer: Deletes a customer record based on the unique customer ID. Any one of the following roles is required for this endpoint: |Legacy Role|Equivalent Permission Set Role| |-----|--------| |org.user.customer.delete|org.permission.customer.delete|; Customers
Delete draft attachment: Deletes a draft attachment resource.; Drafts (Attachments)
Delete Forward Attachment: Deletes a forward attachment resource.; Forwards (Attachments)
Delete KObject (custom object) by ID: Deletes a KObject (custom object) based on the unique KObject ID. Any one of the following roles is required for this endpoint: |Legacy Role|Equivalent Permission Set Role| |-----|--------| |org.user.kobject.delete|org.permission.kobject.delete| ||org.permission.kobject.kobject_*.delete|; KObjects (Custom Objects)
Delete note by ID: Deletes a note based on the unique note ID. Any one of the following roles is required for this endpoint: |Legacy Role|Equivalent Permission Set Role| |-----|--------| |org.user.note.write|org.permission.note.delete|; Notes
Delete a business schedule by ID: Deletes a business schedule based on the schedule ID. Any one of the following roles is required for this endpoint: Legacy Role|Equivalent Permission Set Role| |-----|--------| |org.admin.schedule.write|org.permission.schedule.delete|; Business Schedules
Delete snooze: Deletes a snooze. Any one of the following roles is required for this endpoint: |Legacy Role|Equivalent Permission Set Role| |-----|--------| |org.admin.content.snooze.write|org.permission.snooze.delete| |org.admin.snooze.write||; Snoozes
Delete sub-status: Deletes a sub-status. Any one of the following roles is required for this endpoint: |Legacy Role|Equivalent Permission Set Role| |-----|--------| |org.admin.sub_status.write|org.permission.sub_status.delete| |org.admin.content.sub_status.write||; Sub-Statuses
Deletes unmasking window by customer ID: Deletes an unmasking window based on the unique customer ID. Any one of the following roles is required for this endpoint: |Legacy Role|Equivalent Permission Set Role| |-----------------------|--------------------------------------| |org.user.customer.write|org.permission.unmasking_window.delete| ### Note > If an unmasking window is deleted for a customer, any sensitive attributes for the customer and for the customer's conversations, messages, and custom objects will be returned masked.; Customers (Unmasking Windows)Unmasking Windows
Delete draft: Deletes a draft.; Drafts
Delete Klass: Deletes a Klass based on the unique Klass ID. ### Note > You cannot delete a Klass if KObjects (custom objects) exist for the Klass in your Kustomer organization. Any one of the following roles is required for this endpoint: |Legacy Role|Equivalent Permission Set Role| |-----|--------| |org.admin.klass.write|org.permission.klass.delete|; Klasses
Delete a spam sender: Deletes a spam sender based on the unique sender ID. Any one of the following roles is required for this endpoint: |Legacy Role|Equivalent Permission Set Role| |-----|--------| |org.admin.spam.write|org.permission.spam.delete|; Spam
Find company KObjects (custom Objects): Retrieves all [KObjects (custom Objects)](https://help.kustomer.com/en_us/define-attributes-Skr924HI) that are linked to a company based on the unique company ID and unique Klass name. Any one of the following roles is required for this endpoint: |Legacy Role|Equivalent Permission Set Role| |-----|--------| |org.user.company.read|org.permission.company.read|; CompaniesKlasses
Find customer KObjects (custom Objects): Finds all [KObjects (custom objects)](https://help.kustomer.com/define-attributes-Skr924HI) linked to a customer based on the name of the Klass. Any one of the following roles is required for this endpoint: |Legacy Role|Equivalent Permission Set Role| |-----|--------| |org.user.customer.read|org.permission.customer.read|; Customers (KObjects)KObjects (Custom Objects)
Get all business schedules: Retrieves business schedules for a Kustomer organization. Any one of the following roles is required for this endpoint: |Legacy Role|Equivalent Permission Set Role| |-----|--------| |org.user.schedule.read|org.permission.schedule.read| |org.admin.schedule.read| To learn more, see [Business Schedules](https://help.kustomer.com/business-schedules-SJj3ZxD1E) in the Kustomer Help Center.; Business Schedules
Get attachment by message ID and attachment ID (inbound or outbound): Retrieves attachments based on the unique ID of the attachment for a specific message ID. Any one of the following roles is required for this endpoint: |Legacy Role|Equivalent Permission Set Role| |-----|--------| |org.user.attachment.read|org.permission.attachment.read|; AttachmentsMessages
Get attachments by ID [Outbound Only]: Retrieves attachments using the unique ID of the attachment or an array of unique attachment IDs, if given. Any one of the following roles is required for this endpoint: |Legacy Role|Equivalent Permission Set Role| |-----|--------| |org.user.attachment.read|org.permission.attachment.read|; Attachments
Query events associated with your organization: |Legacy Role|Equivalent Permission Set Role| |-----|--------| |org.user.audit_logs.read|org.permission.audit_logs.read| --------; Audit Logs
Get bulk operation batches: Retrieves detailed batch information for a specific bulk operation, including individual object IDs created or processed during the operation. This endpoint provides comprehensive details about each batch within a bulk operation. Any one of the following roles is required for this endpoint: |Legacy Role|Equivalent Permission Set Role| |-----|--------| |org.user.bulk.read|org.permission.bulk.read| ### Use Cases * Retrieve object IDs of newly created entities from bulk create operations * Get detailed error information for failed batch items * Monitor individual batch processing status and completion times * Access success/failure counts at the batch level ### Batch Status Values * `queued` - Batch is waiting to be processed * `scheduled` - Batch has been scheduled for processing * `complete` - Batch processing has finished ### Response Details Each batch includes: * `objectIds` - Array of IDs for successfully created/updated objects * `successCount` - Number of items processed successfully in this batch * `failureCount` - Number of items that failed in this batch * `completedAt` - Timestamp when batch processing finished * `errors` - Detailed error information for failed items ### Sorting and Filtering * **Sorting**: Supports sorting by `createdAt` field - `sort=createdAt` - Sort by creation time (ascending, oldest first) - `sort=-createdAt` - Sort by creation time (descending, newest first) - **Default**: `createdAt` ascending (oldest first) * **Status Filtering**: Filter by batch status (`queued`, `scheduled`, `complete`) * **Completion Filtering**: Filter by completion state (`true`/`false`) ### Pagination Results are paginated. Use standard pagination parameters (`page`, `limit`) to navigate through large batch lists.; Bulk Operations
Get bulk operation by ID: Retrieves a specific bulk operation by its unique identifier. This endpoint allows you to check the status and details of a bulk operation after it has been created. Any one of the following roles is required for this endpoint: |Legacy Role|Equivalent Permission Set Role| |-----|--------| |org.user.bulk.read|org.permission.bulk.read| ### Status Values * `queued` - Operation is waiting to be processed * `running` - Operation is currently being processed * `complete` - Operation has completed ### Getting Detailed Results For comprehensive details about batch processing, including individual object IDs created during bulk operations, use the `/v1/bulk/{id}/batches` endpoint. This is particularly useful for bulk create operations where you need to retrieve the IDs of newly created objects. ### Alternative Approach for Bulk Creates When performing bulk create operations, consider including an `externalId` for each object. Once the bulk operation status is `complete`, you can perform lookups using the external IDs to retrieve the corresponding internal object IDs. This approach provides more reliable object tracking across bulk operations. ### Response Field Details * `batches.complete` - Number of batches that have finished processing * `batches.total` - Total number of batches created for this operation * `completedAt` - Timestamp when the bulk operation finished ### Common Usage 1. Create a bulk operation (POST to bulk endpoint) 2. Poll this endpoint to check status until `status` is `complete` 3. Use `/v1/bulk/{id}/batches` to get detailed results and object IDs 4. For failed items, check batch errors for specific failure reasons ### Performance Notes * Large bulk operations are processed in batches of up to 100 items each * Processing time varies based on operation type and data complexity * Poll interval recommendation: every 5-10 seconds for active operations ### Error Handling When `batchErrors` is `true`: * Check `lastBatchError` for the most recent failure details * Use the batches endpoint to identify which specific items failed * Check individual batch success/failure counts for detailed results ### Related Endpoints * `GET /v1/bulk/{id}/batches` - Get detailed batch processing results; Bulk Operations
Get companies: Retrieves all companies. You can optionally filter this list by the company name or the unique external company ID. Any one of the following roles is required for this endpoint: |Legacy Role|Equivalent Permission Set Role| |-----|--------| |org.user.company.read|org.permission.company.read| ### Note > If you use both the `externalId` and `filter` query params, the request ignores both query params.; Companies
Get company by ID: Retrieves a company by their unique company ID. Any one of the following roles is required for this endpoint: |Legacy Role|Equivalent Permission Set Role| |-----|--------| |org.user.company.read|org.permission.company.read|; Companies
Get conversation by ID: Retrieves a single conversation based on the unique conversation ID. You can also retrieve multiple conversations with a comma-separated list of IDs. Any one of the following roles is required for this endpoint: |Legacy Role|Equivalent Permission Set Role| |-----|--------| |org.user.conversation.read|org.permission.conversation.read|; Conversations
Get conversation attachments: Retrieves a paginated list of conversation attachments. Any attachment shared in a conversation via inbound and outbound messages. |Legacy Role|Equivalent Permission Set Role| |-----|--------| |org.user.attachment.read|org.permission.attachment.read|; ConversationsAttachments
Get conversation events: Retrieves a paginated list of conversation events based on the unique ID of the conversation. You can use the `name` and/or `changed` query parameters to filter the results. Any one of the following roles is required for this endpoint: |Legacy Role|Equivalent Permission Set Role| |-----|--------| |org.user.event.read|org.permission.event.read|; Conversations
Get conversation by external ID: Retrieves a single conversation based on a unique external ID. Any one of the following roles is required for this endpoint: |Legacy Role|Equivalent Permission Set Role| |-----|--------| |org.user.conversation.read|org.permission.conversation.read|; Conversations
Get conversations: Retrieves a paginated list of conversations for the organization. Any one of the following roles is required for this endpoint: |Legacy Role|Equivalent Permission Set Role| |-----|--------| |org.user.conversation.read|org.permission.conversation.read|; Conversations
Get conversations by customer: Retrieves a paginated list of conversations using the unique Customer ID. Any one of the following roles is required for this endpoint: |Legacy Role|Equivalent Permission Set Role| |-----|--------| |org.user.conversation.read|org.permission.conversation.read|; Customers (Conversations)
Get custom attribute metadata: Retrieves the [metadata properties](https://developer.kustomer.com/kustomer-apps-platform/docs/klasses#metadataproperties) for the custom attributes of a specific resource (for example, Company, Conversation, Customer, Message, and KObject (custom Object)). Any one of the following roles is required for this endpoint: |Legacy Role|Equivalent Permission Set Role| |-----|--------| |org.user.metadata.read|org.permission.metadata.read| |org.admin.metadata.read||; Custom Attributes
Get customer merges by customer ID: Retrieves customer merges based on the unique ID of the customer. Any one of the following roles is required for this endpoint: |Legacy Role|Equivalent Permission Set Role| |-----|--------| |org.user.customer.read|org.permission.customer_merge.read| |org.admin.customer.merge.read|; Customers (Merges)
Get all customer sessions: Retrieves all sessions for a single customer based on the unique customer ID. Any one of the following roles is required for this endpoint: |Legacy Role|Equivalent Permission Set Role| |-----|--------| |org.user.event.read|org.permission.event.read|; Customers (Events)
Get customer by email: Retrieves a customer based on their email address. Any one of the following roles is required for this endpoint: |Legacy Role|Equivalent Permission Set Role| |-----|--------| |org.user.customer.read|org.permission.customer.read|; Customers
Get customer by external ID: Retrieves a customer based on their unique external ID. The `externalId` is typically the ID of the customer within your database or an external service. This provides a unique way to create and identify users by mapping a unique customer ID in Kustomer to a unique customer ID in an external system. Any one of the following roles is required for this endpoint: |Legacy Role|Equivalent Permission Set Role| |-----|--------| |org.user.customer.read|org.permission.customer.read|; Customers
Get customer by ID: Retrieves a customer record based on the unique customer ID. Any one of the following roles is required for this endpoint: |Legacy Role|Equivalent Permission Set Role| |-----|--------| |org.user.customer.read|org.permission.customer.read|; Customers
Get customer by phone number: Retrieves a customer based on their phone number. Any one of the following roles is required for this endpoint: |Legacy Role|Equivalent Permission Set Role| |-----|--------| |org.user.customer.read|org.permission.customer.read|; Customers
Get customers: Retrieves all customers in your organization. Results include customer data, such as their phone number, sentiment score, and the last message in a conversation. Any one of the following roles is required for this endpoint: |Legacy Role|Equivalent Permission Set Role| |-----|--------| |org.user.customer.read|org.permission.customer.read| ### Example Request URL > /v1/customers?filter[createdAt][gte]=2023-01-01T00:00:00Z&filter[updatedAt][lt]=2023-12-31T23:59:59Z&sort=-createdAt&page=1&pageSize=100 This example URL demonstrates: * Filtering for customers created on or after January 1, 2023 * Filtering for customers updated before December 31, 2023 * Sorting by creation date in descending order (newest first) * Pagination parameters for page 1 with 100 results per page; Customers
Get default business schedule: Retrieves default business schedules for a Kustomer organization. Any one of the following roles is required for this endpoint: |Legacy Role|Equivalent Permission Set Role| |-----|--------| |org.user.schedule.read|org.permission.schedule.read| |org.admin.schedule.read||; Business Schedules
Get draft attachment: Retrieves a draft attachment. Any one of the following roles is required for this endpoint: |Legacy Role|Equivalent Permission Set Role| |-----|--------| |org.user.attachment.read|org.permission.attachment.read| ### Pre-signed URL When you request the resource, the response will include a **related** URL in the **links** section. You can use this URL to download the attachment file. This URL is a Pre-Signed URL from S3 and provides access for a limited duration to download a file.; Drafts (Attachments)
Get draft attachments: Retrieves all draft attachments. Any one of the following roles is required for this endpoint: |Legacy Role|Equivalent Permission Set Role| |-----|--------| |org.user.attachment.read|org.permission.attachment.read|; Drafts (Attachments)
Get forward attachment: Retrieves a forward attachment. ### Pre-signed URL When you request the resource, the response will include a **related** URL in the **links** section. You can use this URL to download the attachment file. This URL is a Pre-Signed URL from S3 and provides access for a limited duration to download a file.; Forwards (Attachments)
Get forward attachments: Retrieves all forward attachments.; Forwards (Attachments)
Get Klass by ID: Retrieves a Klass based on the unique Klass ID. Any one of the following roles is required for this endpoint: |Legacy Role|Equivalent Permission Set Role| |-----|--------| |org.user.klass.read|org.permission.klass.read| |org.admin.klass.read||; Klasses
Get Klasses: Retrieves all [Klasses](https://help.kustomer.com/define-attributes-Skr924HI#Attributes). ## Filter by `status` You can filter results based on the `status` of the Klass. Valid values are `enabled`, `existing_only`, and `disabled`. The default value is `enabled`. Any one of the following roles is required for this endpoint: |Legacy Role|Equivalent Permission Set Role| |-----|--------| |org.user.klass.read|org.permission.klass.read| |org.admin.klass.read||; Klasses
Get KObject by external ID: Retrieve KObject by name and unique external ID.; KObjects (Custom Objects)
Get KObject (custom object) by ID: Retrieves a KObject (custom object) based on the unique KObject ID. Any one of the following roles is required for this endpoint: |Legacy Role|Equivalent Permission Set Role| |-----|--------| |org.user.kobject.read|org.permission.kobject.read| ||org.permission.kobject.kobject_*.read|; KObjects (Custom Objects)
Get KObjects (custom objects): Retrieves a KObject (custom object) based on the Klass name. To learn more, see [Data Model Overview](https://support.kustomer.com/data-model-overview-SyIS1S3zM). Any one of the following roles is required for this endpoint: |Legacy Role|Equivalent Permission Set Role| |-----|--------| |org.user.klass.read|org.permission.klass.read| |org.admin.klass.read||; KObjects (Custom Objects)
Get media by ID: Retrieves a media object that matches the unique ID or an array of media objects (if multiple IDs are given). Any one of the following roles is required for this endpoint: |Legacy Role|Equivalent Permission Set Role| |-----|--------| |org.user.media.read|org.permission.kb.read| |org.user.setting.read|| |org.user.content.kb.read|| |org.user.kb.read|| |org.admin.content.kb.read|| |org.admin.kb.read||; Media
Get messages: Retrieves [messages](https://help.kustomer.com/message-options-H1tSk3QOI) for your Kustomer organization. Any one of the following roles is required for this endpoint: |Legacy Role|Equivalent Permission Set Role| |-----|--------| |org.user.message.read|org.permission.message.read|; Messages
Get messages by conversation: Retrieves messages for a conversation. Any one of the following roles is required for this endpoint: |Legacy Role|Equivalent Permission Set Role| |-----|--------| |org.user.message.read|org.permission.message.read|; Conversations (Messages)Messages
Get messages by customer ID: Retrieves messages for a specific customer based on the unique customer ID. Any one of the following roles is required for this endpoint: |Legacy Role|Equivalent Permission Set Role| |-----|--------| |org.user.message.read|org.permission.message.read|; Customers (Messages)Messages
Get note by ID: Retrieves a note based on the unique note ID. Any one of the following roles is required for this endpoint: |Legacy Role|Equivalent Permission Set Role| |-----|--------| |org.user.note.read|org.permission.note.read|; Notes
Get notes by conversation: Retrieves notes found in a specific conversation based on the conversation ID. To learn more, see [Notes](https://help.kustomer.com/using-notes-HJvDjNP58) in the Kustomer Help Center. Any one of the following roles is required for this endpoint: |Legacy Role|Equivalent Permission Set Role| |-----|--------| |org.user.note.read|org.permission.note.read|; Conversations (Notes)Notes (Conversations)
Get notes by customer ID: Retrieves notes for a specific customer based on the unique customer ID. [Notes](https://help.kustomer.com/using-notes-HJvDjNP58) are internal communications visible only to users in your Kustomer organization. Any one of the following roles is required for this endpoint: |Legacy Role|Equivalent Permission Set Role| |-----|--------| |org.user.note.read|org.permission.note.read|; Customers (Notes)Notes
Get notes: Retrieves all [notes](https://help.kustomer.com/using-notes-HJvDjNP58) for a Kustomer organization. Any of the following roles is required for this endpoint: |Legacy Role|Equivalent Permission Set Role| |-----|--------| |org.user.note.read|org.permission.note.read|; Notes
Get outbound accounts: Retrieves all outbound accounts. Any one of the following roles is required for this endpoint: |Legacy Role|Equivalent Permission Set Role| |-----|--------| |org.user.apps.read|org.permission.apps.read|; Drafts
Get Satisfactions: Retrieves a paginated list of satisfaction forms for the organization. Any one of the following roles is required for this endpoint: |Legacy Role|Equivalent Permission Set Role| |-----|--------| |org.user.satisfaction.read|org.permission.satisfaction.read|; Satisfaction
Get satisfaction response: Retrieves a satisfaction response by ID. Any one of the following roles is required for this endpoint: |Legacy Role|Equivalent Permission Set Role| |-----|--------| |org.user.satisfaction.read|org.permission.satisfaction.read|; Satisfaction
Get business schedule by ID: Retrieves a business schedule by the schedule ID. Any one of the following roles is required for this endpoint: |Legacy Role|Equivalent Permission Set Role| |-----|--------| |org.user.schedule.read|org.permission.schedule.read| |org.admin.schedule.read||; Business Schedules
Get snooze by ID: Retrieves a specific snooze by ID. Any one of the following roles is required for this endpoint: |Legacy Role|Equivalent Permission Set Role| |-----|--------| |org.user.setting.read|org.permission.snooze.read| |org.admin.content.snooze.read|| |org.admin.snooze.read||; Snoozes
Get snoozes: Retrieves a paginated list of snoozes for a specific resource type. Any one of the following roles is required for this endpoint: |Legacy Role|Equivalent Permission Set Role| |-----|--------| |org.user.setting.read|org.permission.snooze.read| |org.admin.content.snooze.read|| |org.admin.snooze.read||; Snoozes
Get snoozes by klass ID: Retrieves snoozes for a specific klass (kobject type). Any one of the following roles is required for this endpoint: |Legacy Role|Equivalent Permission Set Role| |-----|--------| |org.user.setting.read|org.permission.snooze.read| |org.admin.content.snooze.read|| |org.admin.snooze.read||; Snoozes
Get sub-status by ID: Retrieves a specific sub-status by ID, or multiple sub-statuses by comma-separated IDs. Any one of the following roles is required for this endpoint: |Legacy Role|Equivalent Permission Set Role| |-----|--------| |org.user.conversation.read|org.permission.conversation.read| |org.user.kobject.read|org.permission.kobject.read| |org.admin.sub_status.read|org.permission.sub_status.read| |org.admin.content.sub_status.read||; Sub-Statuses
Get sub-statuses: Retrieves a paginated list of sub-statuses for a specific resource type. Any one of the following roles is required for this endpoint: |Legacy Role|Equivalent Permission Set Role| |-----|--------| |org.user.conversation.read|org.permission.conversation.read| |org.user.kobject.read|org.permission.kobject.read| |org.admin.sub_status.read|org.permission.sub_status.read| |org.admin.content.sub_status.read||; Sub-Statuses
Get customer event: Retrieves a single customer event based on the unique IDs of the customer and the event. Any one of the following roles is required for this endpoint: |Legacy Role|Equivalent Permission Set Role| |-----|--------| |org.user.event.read|org.permission.event.read|; Customers (Events)
Get customer merge: Retrieves an existing customer merge based on the unique ID. Any one of the following roles is required for this endpoint: |Legacy Role|Equivalent Permission Set Role| |-----|--------| |org.user.customer.read|org.permission.customer_merge.create| |org.admin.customer.merge.read|; Customers (Merges)
Get draft forward by ID: Retrieves a draft forward based on the unique forward ID. Any one of the following roles is required for this endpoint: |Legacy Role|Equivalent Permission Set Role| |-----|--------| |org.user.draft.read|org.permission.draft.read|; Drafts
Get message by ID: Retrieves a single message based on the unique message ID. Any one of the following roles is required for this endpoint: |Legacy Role|Equivalent Permission Set Role| |-----|--------| |org.user.message.read|org.permission.message.read|; Messages
Get a Message by External ID: Retrieves a single message using its unique external message ID. Any one of the following roles is required for this endpoint: |Legacy Role|Equivalent Permission Set Role| |-----|--------| |org.user.message.read|org.permission.message.read| | Key | Value | Description | |-|-|-| | externalID | string | Unique external ID of the message. |; Messages
Get all customer events (deprecated): Retrieves a single customer event based on the unique IDs of the customer and the event. ### Deprecation notice > This endpoint has been deprecated and returns a `404 Not Found` error. Use [Get all events by customer for session](https://developer.kustomer.com/kustomer-api-docs/reference/customers-events#getalleventsbycustomerforsession) or [Get conversation events](https://developer.kustomer.com/kustomer-api-docs/reference/conversations#getconversationevents) instead. Any one of the following roles is required for this endpoint: |Legacy Role|Equivalent Permission Set Role| |-----|--------| |org.user.event.read|org.permission.event.read|; Customers (Events)
Get all drafts for customer: Retrieves all outbound drafts to a customer based on the unique customer ID. Any one of the following roles is required for this endpoint: |Legacy Role|Equivalent Permission Set Role| |-----|--------| |org.user.draft.read|org.permission.draft.read|; Customers (Drafts)
Get all events by customer for session: Retrieves all tracking events for a specific customer session based on the unique IDs of the customer and the session. Any one of the following roles is required for this endpoint: |Legacy Role|Equivalent Permission Set Role| |-----|--------| |org.user.event.read|org.permission.event.read|; Customers (Events)
Get all forwards by conversation: Retrieves all forwarded conversations based on the unique conversation ID. To learn more, see [Forwarding conversations](https://help.kustomer.com/forwarding-SJN_iaACN) in the Kustomer Help Center. Any one of the following roles is required for this endpoint: |Legacy Role|Equivalent Permission Set Role| |-----|--------| |org.user.draft.read|org.permission.draft.read|; Conversations (Forwards)
Get SLA by ID: Retrieves an [SLA](https://help.kustomer.com/service-level-agreements-SyZ4xWcgf) based on the unique SLA ID. Use the optional `versions` query param to retrieve information about SLA versions. Any one of the following roles is required for this endpoint: |Legacy Role|Equivalent Permission Set Role| |-----|--------| |org.user.sla.read|org.permission.sla.read|; SLAs
Get brand by ID: Retrieves a brand by its unique ID. Any one of the following roles is required for this endpoint: |Legacy Role|Equivalent Permission Set Role| |-----|--------| |org.admin.brand.read|org.permission.brand.read| |org.user.brand.read|; Brands
Get brands: Retrieves a paginated list of all brands belonging to your organization. Any one of the following roles is required for this endpoint: |Legacy Role|Equivalent Permission Set Role| |-----|--------| |org.admin.brand.read|org.permission.brand.read| |org.user.brand.read|; Brands
Get conversation time by ids: Retrieves `conversation_time`s base on the unique ID or the IDs of `conversation_time`(s). Any one of the following roles is required for this endpoint: |Legacy Role|Equivalent Permission Set Role| |-----|--------| |org.user.conversation.read|org.permission.conversation.read|; Conversations (Time)
Get conversation times by conversation: Retrieves `conversation_time`s by the unique ID of the related conversation. Any one of the following roles is required for this endpoint: |Legacy Role|Equivalent Permission Set Role| |-----|--------| |org.user.conversation.read|org.permission.conversation.read|; Conversations (Time)
Get default brand: Retrieves the default brand that was created for your Kustomer organization during registration. Learn more about the default brand in the [Kustomer Help Center](https://help.kustomer.com/create-and-manage-multiple-brands-ryc8HBZnD#customize). Any one of the following roles is required for this endpoint: |Legacy Role|Equivalent Permission Set Role| |-----|--------| |org.admin.brand.read|org.permission.brand.read| |org.user.brand.read|; Brands
Get spam senders: Retrieves a paginated list of senders. Any one of the following roles is required for this endpoint: |Legacy Role|Equivalent Permission Set Role| |-----|--------| |org.admin.spam.read|org.permission.spam.read|; Spam
Update brand: Updates a brand resource. |Legacy Role|Equivalent Permission Set Role| |-----|--------| |org.admin.brand.write|org.permission.brand.update|; Brands
Create brand: Creates a brand resource. Any one of the following roles is required for this endpoint: |Legacy Role|Equivalent Permission Set Role| |-----|--------| |org.admin.brand.write|org.permission.brand.create|; Brands
Redact a message: Redacts a message. Any one of the following roles is required for this endpoint: |Legacy Role|Equivalent Permission Set Role| |-----|--------| |org.admin.message.write|org.permission.message_redaction.create|; Messages
Remove tags from conversation: Removes tags from a conversation by tag name and/or the unique ID of the conversation. Any one of the following roles is required for this endpoint: |Legacy Role|Equivalent Permission Set Role| |-----|--------| |org.user.conversation.write|org.permission.conversation.delete| ### Note > This endpoint is subject to Object Rate Limiting, which limits how many updates a single User can make to a single Conversation. See [Rate limiting](https://developer.kustomer.com/kustomer-api-docs/reference/rate-limiting) for more information.; Conversations (Tags)
Update company attributes: Updates the attributes of a company based on the company ID. Any one of the following roles is required for this endpoint: |Legacy Role|Equivalent Permission Set Role| |-----|--------| |org.user.company.write|org.permission.company.update| ### Note >This endpoint is subject to Object Rate Limiting, which limits how many updates a single user can make to a single company attribute. To learn more, see [Rate limiting](https://developer.kustomer.com/kustomer-api-docs/reference/rate-limiting). ### Custom Attributes [Custom attributes](https://help.kustomer.com/define-attributes-Skr924HI) 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 * `Num` *number* or *null* * `At` *date-time* or *null* * `Str` *string* or *null*, length: [ 0 .. 1024 ] characters * `Txt` *string* or *null*, length: [ 0 .. 1024 ] characters * `Bool` *boolean* or *null* * `Url` *string* or *null*, format: *uri*; Companies
Update conversation: Updates a conversation based on the unique conversation ID. Any one of the following roles is required for this endpoint: |Legacy Role|Equivalent Permission Set Role| |-----|--------| |org.user.conversation.write|org.permission.conversation.update| ### Note >This endpoint is subject to Object Rate Limiting, which limits how many updates a single user can make to a single conversation. To learn more, see [Rate limiting](https://developer.kustomer.com/kustomer-api-docs/reference/rate-limiting). ### Custom Attributes [Custom attributes](https://help.kustomer.com/define-attributes-Skr924HI) 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 * `Num` *number* or *null* * `At` *date-time* or *null* * `Str` *string* or *null*, length: [ 0 .. 1024 ] characters * `Txt` *string* or *null*, length: [ 0 .. 1024 ] characters * `Bool` *boolean* or *null* * `Url` *string* or *null*, format: *uri*; Conversations
Update conversation attributes: Updates the data attributes of a conversation based the unique conversation ID. Any one of the following roles is required for this endpoint: |Legacy Role|Equivalent Permission Set Role| |-----|--------| |org.user.conversation.write|org.permission.conversation.update| ### Note >This endpoint is subject to Object Rate Limiting, which limits how many updates a single user can make to a single company attribute. To learn more, see [Rate limiting](https://developer.kustomer.com/kustomer-api-docs/reference/rate-limiting). ### Custom Attributes [Custom attributes](https://help.kustomer.com/define-attributes-Skr924HI) 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 * `Num` *number* or *null* * `At` *date-time* or *null* * `Str` *string* or *null*, length: [ 0 .. 1024 ] characters * `Txt` *string* or *null*, length: [ 0 .. 1024 ] characters * `Bool` *boolean* or *null* * `Url` *string* or *null*, format: *uri*; Conversations
Update custom attribute metadata: Sets the [metadata properties](https://developer.kustomer.com/kustomer-apps-platform/docs/klasses#metadataproperties) for custom attributes on any of the available resources (for example, Company, Conversation, Customer, Message, and KObject (custom Object)). Metadata property options are dependent on the data type as specified by the suffix of the property name. The `displayName` default value is set to the title cased version of the camelCase property name and the type is determined automatically. For example, a property named `totalOrdersNum` will have a default `displayName` value of `Total Orders` (if no alternative `displayName` value is set) and the type is set to `number` based on the `Num` suffix in the property name `totalOrdersNum`. To learn more about options for metadata properties, visit [Klasses](https://developer.kustomer.com/kustomer-apps-platform/docs/klasses#metadataproperties). ### Note > When you configure metadata property types for custom attributes, you must configure metadata for custom properties ending with `Id` before you can use the attributes. When you update these properties, Kustomer validates these values to ensure that the related object exists and matches the specified target type. > When configuring attributes as sensitive, note that some attributes will inherit any permissions and metadata from other attributes. These are - `customer.externalId` inherits permissions and metadata from `customer.externalIds` - `customer.firstName`, `customer.lastName`, and `customer.displayName` inherits permissions and metadata from `customer.name` ### Custom Attributes [Custom attributes](https://help.kustomer.com/define-attributes-Skr924HI) 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 * `Num` *number* or *null* * `At` *date-time* or *null* * `Str` *string* or *null*, length: [ 0 .. 1024 ] characters * `Txt` *string* or *null*, length: [ 0 .. 1024 ] characters * `Bool` *boolean* or *null* * `Url` *string* or *null*, format: *uri* Any one of the following roles is required for this endpoint: |Legacy Role|Equivalent Permission Set Role| |-----|--------| |org.admin.metadata.write|org.permission.metadata.update|; Custom Attributes
Update customer: Updates a customer based on the unique customer ID. Any one of the following roles is required for this endpoint: |Legacy Role|Equivalent Permission Set Role| |-----|--------| |org.user.customer.write|org.permission.customer.update| ### 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](https://developer.kustomer.com/kustomer-api-docs/reference/rate-limiting). ### Company If you omit the company, the customer will no longer be linked to the company. ### Custom Attributes [Custom attributes](https://help.kustomer.com/define-attributes-Skr924HI) 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 * `Num` *number* or *null* * `At` *date-time* or *null* * `Str` *string* or *null*, length: [ 0 .. 1024 ] characters * `Txt` *string* or *null*, length: [ 0 .. 1024 ] characters * `Bool` *boolean* or *null* * `Url` *string* or *null*, format: *uri*; Customers
Update customer attributes: Updates customer attributes. Any one of the following roles is required for this endpoint: |Legacy Role|Equivalent Permission Set Role| |-----|--------| |org.user.customer.write|org.permission.customer.update| ### 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](https://developer.kustomer.com/kustomer-api-docs/reference/rate-limiting). ### Company If you omit the company, the customer will no longer be linked to the company. ### Custom Attributes [Custom attributes](https://help.kustomer.com/define-attributes-Skr924HI) 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 * `Num` *number* or *null* * `At` *date-time* or *null* * `Str` *string* or *null*, length: [ 0 .. 1024 ] characters * `Txt` *string* or *null*, length: [ 0 .. 1024 ] characters * `Bool` *boolean* or *null* * `Url` *string* or *null*, format: *uri*; Customers
Update KObject (custom object) by ID: Updates an existing KObject (custom object) based on the unique ID. Any one of the following roles is required for this endpoint: |Legacy Role|Equivalent Permission Set Role| |-----|--------| |org.user.kobject.write|org.permission.kobject.update| ||org.permission.kobject.kobject_*.update| ### Note > This endpoint is subject to "Object Rate Limiting", meaning that a single user is limited in how many updates they can make to a single KObject. To learn more, see [Rate limiting](https://developer.kustomer.com/kustomer-api-docs/reference/rate-limiting). ### Custom Attributes [Custom attributes](https://help.kustomer.com/define-attributes-Skr924HI) 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 * `Num` *number* or *null* * `At` *date-time* or *null* * `Str` *string* or *null*, length: [ 0 .. 1024 ] characters * `Txt` *string* or *null*, length: [ 0 .. 1024 ] characters * `Bool` *boolean* or *null* * `Url` *string* or *null*, format: *uri*; KObjects (Custom Objects)
Update media by ID: Updates a media object based on the unique media ID. Any one of the following roles is required for this endpoint: |Legacy Role|Equivalent Permission Set Role| |-----|--------| |org.user.media.write|org.permission.kb.update|; Media
Update message attributes by ID: Updates attributes for a message based on the unique message ID. Any one of the following roles is required for this endpoint: |Legacy Role|Equivalent Permission Set Role| |-----|--------| |org.user.message.write|org.permission.message.update| ### Note > This endpoint is subject to Object Rate Limiting, which limits how many updates single user can make to a single message. To learn more, see [Rate limiting](https://developer.kustomer.com/kustomer-api-docs/reference/rate-limiting). ### Authorization > The `org.admin` role is required for setting `createdAt`, `createdBy`, `modifiedAt`, and `modifiedBy`. Otherwise, these attributes are automatically set by the token. ### Custom Attributes [Custom attributes](https://help.kustomer.com/define-attributes-Skr924HI) 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 * `Num` *number* or *null* * `At` *date-time* or *null* * `Str` *string* or *null*, length: [ 0 .. 1024 ] characters * `Txt` *string* or *null*, length: [ 0 .. 1024 ] characters * `Bool` *boolean* or *null* * `Url` *string* or *null*, format: *uri*; Messages
Update note by ID: Updates a note based on the unique note ID. Any one of the following roles is required for this endpoint: |Legacy Role|Equivalent Permission Set Role| |-----|--------| |org.user.note.write|org.permission.note.update| ### Note > This endpoint is subject to Object Rate Limiting, which limits how many updates single user can make to a single note. To learn more, see [Rate limiting](https://developer.kustomer.com/kustomer-api-docs/reference/rate-limiting). ### Authorization > The `org.admin` role is required for setting `createdAt`, `createdBy`, `modifiedAt`, and `modifiedBy`. Otherwise, these attributes are automatically set by the token.; Notes
Update note attributes by ID: Updates one or more note attibutes based on the unique note ID. Any one of the following roles is required for this endpoint: |Legacy Role|Equivalent Permission Set Role| |-----|--------| |org.user.note.write|org.permission.note.update| ### Note > This endpoint is subject to Object Rate Limiting, which limits how many updates single user can make to a single note. To learn more, see [Rate limiting](https://developer.kustomer.com/kustomer-api-docs/reference/rate-limiting). ### Authorization > The `org.admin` role is required for setting `createdAt`, `createdBy`, `modifiedAt`, and `modifiedBy`. Otherwise, these attributes are automatically set by the token.; Notes
Update business schedule by ID: Modifies a business schedule based on the schedule ID. Any one of the following roles is required for this endpoint: |Legacy Role|Equivalent Permission Set Role| |-----|--------| |org.admin.schedule.write|org.permission.schedule.update|; Business Schedules
Update snooze: Updates an existing snooze. Any one of the following roles is required for this endpoint: |Legacy Role|Equivalent Permission Set Role| |-----|--------| |org.admin.content.snooze.write|org.permission.snooze.update| |org.admin.snooze.write||; Snoozes
Update sub-status: Updates an existing sub-status. Any one of the following roles is required for this endpoint: |Legacy Role|Equivalent Permission Set Role| |-----|--------| |org.admin.sub_status.write|org.permission.sub_status.update| |org.admin.content.sub_status.write||; Sub-Statuses
Update draft: Updates a draft. You can use this endpoint to update any available properties for a channel. ## `sendAt` property options * If the `sendAt` property is set to a valid timestamp, the draft will be scheduled to be sent. * If the `sendAt` property is empty, the draft will be unscheduled. * If the `sendAt` property is omitted, the draft status won't change.; Drafts
Update draft forward: Updates a draft forward.; Drafts
Update Klass by ID: Updates Klass attributes based on the unique Klass ID. Any one of the following roles is required for this endpoint: |Legacy Role|Equivalent Permission Set Role| |-----|--------| |org.admin.klass.write|org.permission.klass.update|; Klasses
Update message by ID: Updates a message based on the unique message ID. Any one of the following roles is required for this endpoint: |Legacy Role|Equivalent Permission Set Role| |-----|--------| |org.user.message.write|org.permission.message.update| ### Note > This endpoint is subject to Object Rate Limiting, which limits how many updates single user can make to a single message. To learn more, see [Rate limiting](https://developer.kustomer.com/kustomer-api-docs/reference/rate-limiting). ### Authorization > The `org.admin` role is required for setting `createdAt`, `createdBy`, `modifiedAt`, and `modifiedBy`. Otherwise, these attributes are automatically set by the token. ### Custom Attributes [Custom attributes](https://help.kustomer.com/define-attributes-Skr924HI) 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 * `Num` *number* or *null* * `At` *date-time* or *null* * `Str` *string* or *null*, length: [ 0 .. 1024 ] characters * `Txt` *string* or *null*, length: [ 0 .. 1024 ] characters * `Bool` *boolean* or *null* * `Url` *string* or *null*, format: *uri*; Messages
Update or upsert attachment: Updates the requested attachment. Upserts the attachment if an attachment does not exist. Any one of the following roles is required for this endpoint: |Legacy Role|Equivalent Permission Set Role| |-----|--------| |org.admin.message.write|org.permission.message.update|; Attachments
Upsert spam sender: Assigns a spam list status for a new sender, or updates the spam list status for an existing sender. You can assign senders to a `list` status: `whitelist` (never considered spam) or `blacklist` (always considered spam). Any one of the following roles is required for this endpoint: |Legacy Role|Equivalent Permission Set Role| |-----|--------| |org.admin.spam.write|org.permission.spam.update|; Spam

FAQ

Kustomer integration, answered

How do AI agents use Kustomer through Open Connector?: Your user connects Kustomer once with one of its cataloged authentication methods. Open Connector stores the credential in an encrypted vault and exposes Kustomer tools to your agent over MCP or a typed API, with credentials injected server-side on each call.
Is this a Kustomer MCP server?: Yes. Open Connector can serve Kustomer as a named MCP server with a scoped allowlist and a per-user connection URL, so any MCP client can call Kustomer actions with credentials injected server-side.
Where do Kustomer credentials live?: In your own infrastructure. Open Connector keeps credentials in its own vault and injects them at call time, so they never leave your environment.

Give your agents Kustomer — keep the keys.

Open source, self-hostable, with Kustomer credentials that never leave your infrastructure. Run it from source today.

View source on GitHub How the MCP gateway works →