Data model overview

Kustomer is organized around the customer. Instead of a ticket queue where each request stands alone, every conversation, message, order and event hangs off one customer record and appears on one timeline. That shape explains most of the API: many endpoints are nested under /v1/customers/{id}, and most objects carry a customer relationship.

The objects

Every object has a 24-character id assigned by Kustomer, and most accept an externalId you choose. Use externalId to link records to your own systems.

The timeline

The customer timeline is the agent's view of this graph: conversations with their messages and notes, KObjects such as orders and subscriptions, and tracked events, merged and sorted by time.

That's why you should attach data to the right customer: an order KObject created under the customer shows up next to the conversation where the customer asks about it, and workflows can use both.

Standard and custom attributes

Every object has standard attributes defined by Kustomer, such as name, emails and status. Objects also accept custom attributes under a custom key, typed by their name suffix:

{
  "name": "Jane Doe",
  "custom": {
    "loyaltyTierStr": "gold",
    "lifetimeValueNum": 1840.5,
    "lastOrderAt": "2026-10-02T15:04:05Z",
    "marketingOptInBool": true
  }
}

Custom attributes covers the suffixes and how to give each attribute a display name, type and options.

Relationships in responses

Responses describe links to other objects in a relationships block, using IDs:

{
  "data": {
    "type": "conversation",
    "id": "58228e05d4e96711004eccb7",
    "attributes": { "name": "Where is my order?", "status": "open" },
    "relationships": {
      "customer": {
        "data": { "type": "customer", "id": "5822a4a5aa5f92110005d69a" },
        "links": { "self": "/v1/customers/5822a4a5aa5f92110005d69a" }
      }
    }
  }
}

In requests, you set a relationship with a plain ID attribute, such as "customer": "5822a4a5aa5f92110005d69a" or "company": "...". See Request and response format.

Where to go next