# Data model overview

> How customers, companies, conversations, messages, notes, custom objects, users and teams relate in Kustomer, and which endpoints work with each.

Source: https://developer.kustomer.com/docs/concepts/data-model

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.

_Interactive map of the Kustomer data model. Customer is at the center. A customer belongs to a Company and has many Conversations. Conversations have Messages and Notes; Messages have Attachments. Customers and companies own KObjects (custom objects), each an instance of a Klass. Conversations are assigned to Users and Teams. Selecting an object shows its key attributes and the endpoints that create and read it._

## The objects

| Object       | What it represents                                          | Belongs to                    | Base path            |
| ------------ | ----------------------------------------------------------- | ----------------------------- | -------------------- |
| Customer     | A person you support                                        | Optionally a company          | `/v1/customers`      |
| Company      | An organization customers belong to                         | Optionally a parent company   | `/v1/companies`      |
| Conversation | A thread with one customer, with status, assignment and SLA | A customer                    | `/v1/conversations`  |
| Message      | One inbound or outbound communication on a channel          | A conversation and a customer | `/v1/messages`       |
| Note         | An internal comment visible only to your team               | A conversation                | `/v1/notes`          |
| Draft        | An unsent outbound message                                  | A conversation                | `/v1/drafts`         |
| Attachment   | A file on a message, note or draft                          | Its parent                    | `/v1/attachments`    |
| KObject      | A record of a custom type, such as an order or booking      | A customer or company         | `/v1/klasses/{name}` |
| Klass        | The schema for a type of KObject                            | Your org                      | `/v1/klasses`        |
| User         | An agent, admin or machine user                             | Your org                      | `/v1/users`          |
| Team         | A group of users                                            | Your org                      | `/v1/teams`          |

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.

_Figure: A customer timeline in Kustomer showing an email conversation, an order custom object card and a chat conversation in date order. A customer's timeline combines conversations, custom objects and events._

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:

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

[Custom attributes](https://developer.kustomer.com/docs/concepts/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:

```json
{
  "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](https://developer.kustomer.com/docs/concepts/json-api-format).

## Where to go next

- [Conversations and messages](https://developer.kustomer.com/docs/concepts/conversations-and-messages): Status, assignment, channels, and how messages thread.
- [Custom objects](https://developer.kustomer.com/docs/concepts/custom-objects): Model orders, bookings and devices with Klasses and KObjects.
- [Search](https://developer.kustomer.com/docs/concepts/search): Query across customers, conversations, messages and custom objects.