Create KObject

post/v1/klasses/{name}
Requires any one of these rolesAbout roles
org.permission.kobject.createorg.permission.kobject.kobject_*.create
Legacyorg.user.kobject.write

The API key or user must hold at least one of them. Legacy roles still work; prefer the others for new keys.

Creates a new KObject (custom object).

Custom Attributes

Custom attributes are optional and allow you to specify custom key-value pairs.

Kustomer uses a naming convention for custom attributes to specify the field data type with a name suffix:

Naming Suffix

  • 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.
About this resource

KObjects (custom objects)

A KObject is one record of a custom type that you define, such as a single order, booking or device. It belongs to a customer or company, shows up on their timeline, and can be searched and used in workflows like built-in data.

Custom objects bring records from your own systems into Kustomer. Two resources work together: a Klass is the type, such as "Order", with a name, icon, color and a set of typed attributes; a KObject is one instance of that type, such as order #4417 for Jane Doe. You define the Klass once, then create as many KObjects as you need. Agents see KObjects as cards on the customer or company timeline, and admins can use them in searches, workflows and KViews.

A KObject is created under its Klass and usually linked to a customer (customer) or company (company), most often by an integration that syncs records as they change. KObject endpoints address the Klass by its name in the path (for example /v1/klasses/ecomm-order/...), not by its ID.

Key fields

Field Meaning
title Required. The headline on the timeline card. description adds a second line.
externalId Your ID for the record. Look the KObject up with it later instead of storing Kustomer's ID.
custom Typed attributes defined in the Klass's metadata, named with suffixes such as orderStatusStr or totalPriceNum. These are searchable, for example as kobject_custom_ecomm-order_totalPriceNum.
data Free-form JSON for anything else, such as line items. Use it for display, not search.
images, icon, tags Up to 20 images, an icon that overrides the Klass icon, and up to 20 tags.
importedAt Marks a record as historical data you are importing.

KObjects of task Klasses also carry work-tracking fields: status (open or done), assignedUser, queue, doneCount, reopenCount, and firstDone/lastDone with timing details.

Limits and write behavior

A single client can create up to 120 KObjects per customer per minute; beyond that, creates return 429 Too Many Requests. Records that include importedAt are exempt, so set it when you backfill. Updates merge into the existing record unless you pass replace=true, and they are subject to object rate limiting on repeated changes to the same KObject (see rate limits). Custom Str attributes hold up to 1,024 characters.

Which endpoint to use

To Call
Create a KObject for a customer POST /v1/customers/{id}/klasses/{name}, or POST /v1/klasses/{name} with customer or company in the body
List a customer's KObjects of one Klass GET /v1/customers/{id}/klasses/{name}
List a company's KObjects of one Klass GET /v1/companies/{id}/klasses/{name}
List every KObject of a Klass GET /v1/klasses/{name}
Find a record by your own ID GET /v1/klasses/{name}/externalId={externalId}
Read, update or delete one KObject GET, PUT or DELETE /v1/klasses/{name}/{id}
Create, update or delete up to 100 at once POST, PUT or DELETE /v1/klasses/{name}/bulk

A typical sync looks the record up by externalId, creates it on 404, and updates it otherwise. List endpoints page with page and pageSize, and accept sort, fromDate and fields to narrow the results. Bulk requests run asynchronously and return a bulk operation to poll; see bulk operations. Bulk deletes take the IDs as a comma-separated ids query parameter. Add getS3DataUrls=true when reading a single KObject to get signed URLs for its attachment fields.

RelatedKlassesCustom objects (KObjects)Custom attributesComments

Path parameters

namestringrequired

Klass name of the KObjects (custom objects).

Example "orders"

Request body

application/jsonrequired
customerstring
companystring
externalIdstring
min length 1 · max length 256
titlestringrequired
min length 1 · max length 256
descriptionstring
max length 10240
imagesarray<string<url>>
max items 20 · unique items
iconstring
max length 64
dataobject
customobjectcustom_attrs
tagsarray<tag_name>
max items 20 · unique items
createdAtstring<date-time>
importedAtstring<date-time>

Responses

Created

objectrequired