Kustomer

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.

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*

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|

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|

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|

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|

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|

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*

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|

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|

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|

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|

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|

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|

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|

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|

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".

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|

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]" ```

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]" ```

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.

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

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.

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.

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|

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||

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||

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.

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*

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.

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*

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*

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

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`

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|

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|

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.

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.

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.

Creates a new tracking event. The following role is required for this endpoint: org.tracking

Identifies a user. The following role is required for this endpoint: org.tracking

Identifies a user and tracks an event with a single API call. The following role is required for this endpoint: org.tracking

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 } ```

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 } ```

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|

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|

Deletes a draft attachment resource.

Deletes a forward attachment resource.

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|

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|

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|

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||

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||

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.

Deletes a draft.

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|

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|

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|

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|

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.

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|

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|

|Legacy Role|Equivalent Permission Set Role| |-----|--------| |org.user.audit_logs.read|org.permission.audit_logs.read| --------

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.

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

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.

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|

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|

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|

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|

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|

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|

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|

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||

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|

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|

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|

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|

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|

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|

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

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||

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.

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|

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.

Retrieves all forward attachments.

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||

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||

Retrieve KObject by name and unique external 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|

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||

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||

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|

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|

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|

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|

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|

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|

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|

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|

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|

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|

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||

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||

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||

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||

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||

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||

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|

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|

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|

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|

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. |

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|

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|

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|

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|

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|

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|

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|

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|

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|

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|

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|

Updates a brand resource. |Legacy Role|Equivalent Permission Set Role| |-----|--------| |org.admin.brand.write|org.permission.brand.update|

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|

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|

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.

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*

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*

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*

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|

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*

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*

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*

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|

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*

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.

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.

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|

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||

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||

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.

Updates a draft forward.

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|

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*

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|

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|