Core concepts

Every Kustomer API, from the REST endpoints to webhooks, workflows and apps, works with the same records and follows the same conventions. Read these pages once and the rest of the platform is predictable.

Data model

Kustomer organizes everything around the customer. Conversations, messages, notes and custom objects all hang off a customer and appear on their timeline.

Data model overview

How customers, companies, conversations, messages, notes, custom objects, users and teams relate.

Conversations and messages

Status, assignment and lifecycle; message channels, direction and threading.

Custom objects (KObjects)

Model orders, bookings and devices from your systems and attach them to timelines.

Custom attributes

Typed fields on standard and custom objects, named with type suffixes like Str and Num.

API conventions

Request and response format

The data envelope, relationships, includes and lists.

Pagination

page and pageSize, and why you should follow links.next.

Filters, operators, dates and sorting across every object.

Rate limits

The org-wide per-minute budget and the x-ratelimit-* headers.

Errors

Status codes, error shapes, and which errors to retry.

Versioning

How the API is versioned and how deprecations are announced.

The short version

If you only remember five things:

Requests go to your org's host, https://<org>.api.kustomerapp.com, with Authorization: Bearer <API key>. See regions and base URLs.
Responses wrap records in data, with fields under attributes and links to other records under relationships. See request and response format.
Lists are paged. Follow links.next until it's null instead of computing page numbers. See pagination.
The request budget is shared by the whole org, across every API key and app. Read the x-ratelimit-* headers and back off on 429. See rate limits.
Every change emits an event such as kustomer.conversation.update, which you can receive with webhooks or act on in workflows.