Get KObjects (custom objects)

get/v1/klasses/{name}
Requires any one of these rolesAbout roles
org.permission.klass.read
Legacyorg.user.klass.readorg.admin.klass.read

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

Retrieves a KObject (custom object) based on the Klass name.

To learn more, see Data Model Overview.

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"

Query parameters

pageinteger

Page number of results to return.

Example 1
pageSizeinteger

Number of results to return per page.

Example 100
sortstring

Sort direction for results.

One ofascdescExample "desc"
fromDatestring

Return resources after this date or cursor timestamp, using the endpoint's sort direction.

Example "2016-08-06T19:47:49.235Z"
fieldsstring

Comma-separated response fields to project. The example is representative, not exhaustive; supported values are resource field names and custom field paths accepted by the endpoint handler.

Example "name,createdAt,updatedAt"

Responses

OK

objectrequired
array<object>required
objectrequired