# Kustomer Developers

> Build on Kustomer: REST APIs, webhooks, workflows, apps, chat SDKs and AI tooling, documented for engineers and for the models they work with.

Kustomer is an AI-native customer service CRM. These docs cover the REST API (customers, conversations, messages, custom objects and more), webhooks and events, workflows and the expressions language, the apps platform (JSON app definitions), chat SDKs for web, iOS, Android and React Native, the AI API, and kusty, the CLI and MCP server for Kustomer.

Every page is available as Markdown by appending `.md` to its URL. Requests use `https://{orgname}.api.kustomerapp.com` with `Authorization: Bearer <API key>`.

## Get started

Make your first authenticated call in five minutes.

- [Build on Kustomer](https://developer.kustomer.com/docs/get-started.md): What you can build on the Kustomer platform, how the pieces fit together, and where to start.
- [Quickstart](https://developer.kustomer.com/docs/get-started/quickstart.md): Create an API key, verify it, create a customer, open a conversation and add a message, in about five minutes.
- [Making requests](https://developer.kustomer.com/docs/get-started/making-requests.md): Base URLs, headers, HTTP methods, update semantics, lookups by external ID, timestamps and retries for the Kustomer REST API.
- [Authentication overview](https://developer.kustomer.com/docs/get-started/authentication.md): The ways to authenticate with Kustomer (API keys, OAuth 2.0 and chat keys) and how to choose between them.
- [API keys and roles](https://developer.kustomer.com/docs/get-started/api-keys-and-roles.md): Create Kustomer API keys, understand machine users and role naming, and pick least-privilege roles for common integrations.
- [OAuth 2.0](https://developer.kustomer.com/docs/get-started/oauth.md): Authenticate users with the OAuth 2.0 authorization code flow and PKCE, exchange and refresh tokens, and request scopes.
- [Regions and base URLs](https://developer.kustomer.com/docs/get-started/regions-and-base-urls.md): Kustomer's US, EU and India regions, the org-specific API host, and the other hostnames an integration talks to.

## Core concepts

The data model, request format and platform limits every integration builds on.

- [Core concepts](https://developer.kustomer.com/docs/concepts.md): The data model, request and response format, and platform limits that every Kustomer integration builds on.
- [Data model overview](https://developer.kustomer.com/docs/concepts/data-model.md): How customers, companies, conversations, messages, notes, custom objects, users and teams relate in Kustomer, and which endpoints work with each.
- [Conversations and messages](https://developer.kustomer.com/docs/concepts/conversations-and-messages.md): Conversation status, assignment and lifecycle; message channels, direction and threading; notes and drafts.
- [Custom objects (KObjects)](https://developer.kustomer.com/docs/concepts/custom-objects.md): Model orders, bookings, devices and other records from your systems with Klasses and KObjects, and attach them to customer timelines.
- [Custom attributes](https://developer.kustomer.com/docs/concepts/custom-attributes.md): Add typed fields to customers, companies, conversations, messages and custom objects using name suffixes and attribute metadata.
- [Request and response format](https://developer.kustomer.com/docs/concepts/json-api-format.md): The JSON shapes the Kustomer API accepts and returns, covering request bodies, the data envelope, relationships, side-loaded includes, lists and errors.
- [Pagination](https://developer.kustomer.com/docs/concepts/pagination.md): Page through Kustomer list endpoints with page and pageSize, follow links.next, and handle cursor-based and very large result sets.
- [Search](https://developer.kustomer.com/docs/concepts/search.md): Query customers, conversations, messages, companies, notes and custom objects with Kustomer's search API, including filters, operators, dates, custom attributes, sorting, limits and every standard attribute.
- [Rate limits](https://developer.kustomer.com/docs/concepts/rate-limits.md): Kustomer's org-wide request limits by plan, search and webhook limits, per-object update limits, rate-limit headers, and how to stay under them.
- [Errors](https://developer.kustomer.com/docs/concepts/errors.md): HTTP status codes, error codes and response shapes returned by the Kustomer API, what causes each, and which to retry.
- [Versioning and deprecation](https://developer.kustomer.com/docs/concepts/versioning.md): How the Kustomer API is versioned, how deprecations are marked, and how to build clients that keep working as the API grows.

## Guides

End-to-end recipes for the integrations teams build most.

- [Guides](https://developer.kustomer.com/docs/guides.md): End-to-end recipes for the integrations teams build most on Kustomer, from CRM syncs and custom channels to order data, bulk imports, attachments and search.
- [Sync customers from a CRM](https://developer.kustomer.com/docs/guides/sync-customers-from-crm.md): Build a production two-way sync between a CRM and Kustomer, with an initial bulk backfill, incremental upserts by externalId, companies, webhooks back to the CRM, and loop prevention.
- [Bring messages from a custom channel](https://developer.kustomer.com/docs/guides/custom-channel-messages.md): Record conversations from your own messaging channel (an in-app inbox, a marketplace, a partner platform) on Kustomer timelines, thread them correctly, and deliver agent replies back.
- [Show orders with custom objects](https://developer.kustomer.com/docs/guides/kobject-orders-integration.md): Build an e-commerce orders integration with a Klass, KObjects synced from your store, a link from conversations to orders, and a KView that shows order details to agents.
- [Model company hierarchies](https://developer.kustomer.com/docs/guides/company-hierarchy.md): Represent B2B accounts as trees of companies with the hierarchy API. Link parents and subsidiaries, read a company's parent, children and breadcrumbs, move and unlink branches, delete companies safely, and sync a tree from your CRM within the depth and size limits.
- [Bulk operations](https://developer.kustomer.com/docs/guides/bulk-operations.md): Create, update and delete up to 100 records per request with Kustomer's asynchronous bulk API, then poll for completion and match per-item results with _clientRef.
- [Upload attachments](https://developer.kustomer.com/docs/guides/attachments.md): Attach files to messages, notes and drafts using presigned uploads, register files that stay in your own storage, and download attachments.
- [Search recipes](https://developer.kustomer.com/docs/guides/search-recipes.md): Copy-paste Kustomer search queries for common tasks, plus patterns for exporting beyond the 100-page limit, incremental sync and counting.

## Events and webhooks

Subscribe to changes in Kustomer and push data in from anywhere.

- [Events and webhooks](https://developer.kustomer.com/docs/events.md): How data moves in and out of Kustomer as events. Outbound webhooks push changes to your systems, inbound hooks accept data from anywhere, and every change carries a before-and-after diff.
- [Outbound webhooks](https://developer.kustomer.com/docs/events/outbound-webhooks.md): Subscribe an HTTPS endpoint to Kustomer events. Create webhooks with the API, in Settings or from an app definition, then receive signed JSON for every customer, conversation, message, user, team and tag change.
- [Event catalog](https://developer.kustomer.com/docs/events/event-catalog.md): Every event an outbound webhook can subscribe to, with payload examples and the attributes that matter, plus the additional events that only workflows can react to.
- [Delivery and security](https://developer.kustomer.com/docs/events/delivery-and-retries.md): How Kustomer delivers outbound webhooks. HMAC-SHA256 signatures, the retry schedule, at-least-once delivery, ordering, timeouts, automatic disabling and how to debug failed deliveries.
- [Inbound webhooks](https://developer.kustomer.com/docs/events/inbound-webhooks.md): Send data into Kustomer from forms, servers and email with form hooks, web hooks and email hooks. Each hook gets a unique address and triggers workflows with the data you send.

## Workflows

Event-driven automation: triggers, conditions, actions and code.

- [Workflows](https://developer.kustomer.com/docs/workflows.md): How Kustomer workflows run. A trigger event starts a run, steps call actions with params built from earlier outputs, and transitions with conditions choose the path. Covers the anatomy, run lifecycle, limits and API.
- [How workflows run](https://developer.kustomer.com/docs/workflows/how-workflows-run.md): The workflow engine's mental model, in depth. How an event picks the workflows that run, what a step is, how its output becomes /#steps.<id>, how transitions choose the next step, and what happens on timeouts, failures, not-found lookups, server errors, loops and callable workflows.
- [Data and variables](https://developer.kustomer.com/docs/workflows/data-and-variables.md): The language of workflow data. Covers /#steps path references and {{{ }}} Handlebars templates side by side, what each produces and when to use it, every path you can address (trigger output, changes, step outputs, variables by ID, /#error, callable inputs), path syntax, missing values, type conversion, common helpers, escaping, and how builder picks translate to JSON.
- [Build a workflow in the builder](https://developer.kustomer.com/docs/workflows/build-in-the-builder.md): A hands-on tutorial in Kustomer's visual workflow builder. Build a workflow that tags conversations from VIP customers, and see the JSON each builder action writes. Covers the workflows list, the canvas, triggers, the data picker, conditions, variables, testing, logs, saving and enabling, and what the builder can't do.
- [Write a workflow in JSON](https://developer.kustomer.com/docs/workflows/write-workflow-json.md): A hands-on tutorial that builds a find-or-create workflow as JSON, one key at a time, then creates, tests, enables and updates it with the Workflows API and kusty. Covers root keys, triggers, steps and params, transitions, error cases, variables by ID, partial updates, and the validation errors you'll meet.
- [Workflow patterns](https://developer.kustomer.com/docs/workflows/patterns.md): A cookbook of proven workflow shapes, each with a diagram, a JSON snippet and its pitfalls. Covers find or create, guarding update triggers with changes, branching on lookups, regex keyword tagging, calling your own API, callable workflows, scheduled follow-ups instead of loops, idempotent steps for retries, and copying workflows between orgs.
- [Triggers and actions](https://developer.kustomer.com/docs/workflows/triggers-and-actions.md): Every built-in workflow trigger and action, the shape of trigger output, how Kustomer actions report not-found and errors, and how to build callable and scheduled workflows.
- [Conditions and variables](https://developer.kustomer.com/docs/workflows/conditions-and-expressions.md): How workflow params and conditions get their values. Covers /#steps references, Handlebars templates and escaping, every condition operator and its casting rules, the changes diff, workflow variables for secrets, and error cases.
- [Expressions reference](https://developer.kustomer.com/docs/workflows/expressions-reference.md): Complete reference for Kustomer's expression languages. Covers every /#fn function, every Handlebars helper with its arguments and defaults, and the criteria format and operators used by queue rules and satisfaction surveys.
- [Call your own code](https://developer.kustomer.com/docs/workflows/code-steps.md): Run your own logic from a Kustomer workflow with REST steps. Covers building requests, authentication and signing, branching on status codes, network retries, URL restrictions, timeouts, long-running work, and getting results back into Kustomer.
- [Workflow JSON](https://developer.kustomer.com/docs/workflows/workflow-json.md): The complete workflow document schema, field by field, with limits and patterns. Covers root keys and flat meta, triggers (event and callable), steps, transitions and the save-time loop check, error cases, the replaces field for overriding app workflows, and creating and partially updating workflows through the API.
- [Debugging and logs](https://developer.kustomer.com/docs/workflows/debugging.md): Find out why a workflow did or didn't run. Covers live logs in the builder, failed-run records from the processes API, reading their context, the most common error messages, and a checklist for workflows that silently do nothing.

## Apps platform

Package Klasses, KViews, workflows and settings into installable apps.

- [Apps platform](https://developer.kustomer.com/docs/apps.md): Package custom objects, UI, automations, settings and integrations into one JSON app definition that any Kustomer org can install, configure and update.
- [App definition anatomy](https://developer.kustomer.com/docs/apps/app-definition.md): Every top-level key of a Kustomer app definition, with types, validation rules, naming conventions and a complete example.
- [Klasses](https://developer.kustomer.com/docs/apps/klasses.md): Define custom object types and add namespaced attributes to customers, companies, conversations, messages and users from an app definition.
- [KViews](https://developer.kustomer.com/docs/apps/kviews.md): Render JSX inside the Kustomer timeline and insights panel, embed hosted UI with DynamicCard and the Cards SDK, and call external APIs safely with commands.
- [KView components](https://developer.kustomer.com/docs/apps/kview-components.md): Every component and helper Kustomer gives KView templates, with live previews, a map of where each one fits, a playground, and the props for each.
- [Widgets](https://developer.kustomer.com/docs/apps/widgets.md): Add an iframe agents can open from the Kustomer navigation rail on any page, with per-org URLs, sizing, browser permissions and background loading.
- [Workflows, actions and triggers](https://developer.kustomer.com/docs/apps/workflows-actions-triggers.md): Bring data into Kustomer with app hooks, name it with triggers, call your API with REST actions, ship ready-made workflows, and subscribe to events with outbound webhooks.
- [Settings](https://developer.kustomer.com/docs/apps/settings.md): Declare per-org configuration such as API keys and subdomains, get an auto-generated settings page or embed your own, and read the values from actions, commands, workflows, widgets and KViews.
- [Internationalization](https://developer.kustomer.com/docs/apps/i18n.md): The i18n key formats for app settings pages, widgets, workflow actions, action inputs and triggers, with locale fallback rules.
- [OAuth for apps](https://developer.kustomer.com/docs/apps/oauth.md): Use an app as an OAuth client of Kustomer so your service can act as a user, or configure auth.oauth2 so Kustomer connects to a third-party API on the admin's behalf.
- [Versioning and updates](https://developer.kustomer.com/docs/apps/versioning.md): Semantic versioning rules for app definitions, what each bump means, changelogs, beta versions, upgrading installed apps, automatic updates, and editing listing details without a new version.
- [Register and install](https://developer.kustomer.com/docs/apps/register-and-install.md): Register app definitions with the API, how names are namespaced, installing into an org and tracking progress, disabling and enabling, the read endpoints, and every registration error with its fix.
- [Publish to the marketplace](https://developer.kustomer.com/docs/apps/marketplace.md): How to get a public app listed in the Kustomer App Directory, including listing assets, review requirements, the data and security questionnaire, timelines, and how updates are reviewed.
- [Legacy Apps SDK](https://developer.kustomer.com/docs/apps/legacy-apps-sdk.md): Reference for the deprecated TypeScript Apps SDK (KAppServer, the client and React SDKs, and the apps CLI), and how to migrate an SDK app to a JSON app definition.

## Chat SDKs

Embed Kustomer chat on web, iOS, Android and React Native.

- [Chat SDKs](https://developer.kustomer.com/docs/chat.md): Put Kustomer chat and the knowledge base in your website and mobile apps. Pick an SDK, compare what each platform supports, and see how identity, push and the server-side chat API fit together.
- [How chat works](https://developer.kustomer.com/docs/chat/realtime-architecture.md): The architecture shared by every Kustomer chat SDK. The UI and Core layers, chat keys and customer identity, HTTPS for writes and history, the realtime channel for delivery, and the conversation lifecycle.
- [Web quickstart](https://developer.kustomer.com/docs/chat/web.md): Embed Kustomer Chat on a website with widget.js, start it with Kustomer.start, control it from your code, and listen for widget events. Includes every start option and widget method.
- [Web Core API](https://developer.kustomer.com/docs/chat/web-core-api.md): Build a custom chat UI on KustomerCore, the headless web chat SDK. Loading core.js, init, conversations, messages, typing, read state, knowledge base, CSAT, identity, and every event.
- [Customization and security](https://developer.kustomer.com/docs/chat/web-customization.md): What to configure in Kustomer versus in code, custom launchers, language and right-to-left support, domain restrictions, Content Security Policy with nonces, and privacy considerations for web chat.
- [iOS](https://developer.kustomer.com/docs/chat/ios.md): Add Kustomer Chat to an iOS app with the KustomerChat Swift SDK. Swift Package Manager and CocoaPods setup, Kustomer.setup, presenting the chat UI, the headless ChatProvider and KUSChatListener, identity, theming, localization, and the privacy manifest.
- [Android](https://developer.kustomer.com/docs/chat/android.md): Add Kustomer Chat to an Android app with the Kotlin SDK. Gradle setup, Kustomer.init, opening the chat UI, the headless KustomerCore API and KusChatListener, identity, attachments, theming, localization, and R8.
- [React Native](https://developer.kustomer.com/docs/chat/react-native.md): Add Kustomer Chat to a React Native app with @kustomer/chat-react-native. Installation for iOS and Android, configure, opening the chat UI, events and hooks, identity, push, and the platform differences to know about.
- [Push notifications](https://developer.kustomer.com/docs/chat/push-notifications.md): Notify mobile customers of agent replies when your app is closed. APNs setup for iOS, Firebase Cloud Messaging for Android, forwarding pushes when your app has its own handlers, and React Native specifics.
- [Customer identity](https://developer.kustomer.com/docs/chat/identity.md): Log chat customers in with a JWT signed by your server so their conversations follow them across devices. Getting the signing secret, building the token, calling login on each SDK, describing customers, and logging out.
- [Server-side chat API](https://developer.kustomer.com/docs/chat/server-chat-api.md): Create chat sessions, post customer and agent messages, show typing indicators, hand off bot conversations, and record CSAT from your backend with an API key, using the v2.1 chat endpoints.

## AI

Kustomer AI APIs, the kusty CLI and MCP server, and docs built for models.

- [AI](https://developer.kustomer.com/docs/ai.md): Build with Kustomer AI and build Kustomer integrations with AI. The AI and automations API, the kusty CLI and MCP server for coding agents, and docs published in formats models can read.
- [AI and automations API](https://developer.kustomer.com/docs/ai/ai-api.md): Read AI-generated summaries of conversations, customers and custom objects, list your AI agents, and test them with evaluations, test cases and runs. Includes a CI script that fails a build when an agent's score drops.
- [kusty CLI](https://developer.kustomer.com/docs/ai/kusty.md): kusty is a command-line interface for the Kustomer API built for AI agents and scripts. Every command returns a stable JSON envelope and a numbered exit code. Install it, connect an org with an API key or OAuth, and make your first calls.
- [kusty MCP server](https://developer.kustomer.com/docs/ai/kusty-mcp.md): Give Claude Code, Cursor, Codex, Gemini CLI or any MCP client typed access to the Kustomer API. Install the kusty MCP server and /kusty skill, understand the tools it exposes, and keep agents safe with dry runs, confirmations and read-only mode.
- [kusty command reference](https://developer.kustomer.com/docs/ai/kusty-reference.md): Every kusty command, global flag, environment variable, error code and exit code, plus the resource commands generated from the Kustomer API.
- [Docs for AI](https://developer.kustomer.com/docs/ai/docs-for-ai.md): Every page on this site is published for models as well as people. llms.txt and llms-full.txt, a Markdown version of every page and API operation, structured data, and one-click handoff to AI assistants.

## API reference

- [API overview](https://developer.kustomer.com/api.md): Base URLs, auth and the list of APIs
- [Core resources API](https://developer.kustomer.com/api/core-resources.md): Customers, companies, conversations, messages, notes, drafts, KObjects, Klasses, search, bulk operations and more. Lists all 171 operations with links to each operation's Markdown.
- [Core resources v2 API](https://developer.kustomer.com/api/core-resources-v2.md): Newer v2 endpoints for core CRM data, starting with conversation times. Lists all 1 operations with links to each operation's Markdown.
- [Queues and routing API](https://developer.kustomer.com/api/queues-and-routing.md): Queues, queue rules, routing statuses, team routing settings, work sessions, work items and live metrics. Lists all 37 operations with links to each operation's Markdown.
- [Chat conversations API](https://developer.kustomer.com/api/chat.md): Server-side chat sessions, messages and handoff with an API token (v2.1). Lists all 10 operations with links to each operation's Markdown.
- [Knowledge base API](https://developer.kustomer.com/api/knowledge-base.md): Knowledge bases, articles, categories, versions and languages, forms, themes, templates, routes and custom domains. Lists all 71 operations with links to each operation's Markdown.
- [Workflows API](https://developer.kustomer.com/api/workflows.md): Create and update workflows, manage workflow variables and inspect process errors. Lists all 10 operations with links to each operation's Markdown.
- [Apps platform API](https://developer.kustomer.com/api/apps-platform.md): Apps, cards, KViews, inbound email/form/web hooks and outbound webhooks with their transactions. Lists all 40 operations with links to each operation's Markdown.
- [Settings and configurations API](https://developer.kustomer.com/api/settings-and-configurations.md): Chat settings, notifications, search filters, shortcuts, snippets, satisfaction surveys, snoozes and user settings. Lists all 55 operations with links to each operation's Markdown.
- [Access management API](https://developer.kustomer.com/api/access-management.md): Users, teams, role groups, auth tokens (API keys) and authentication settings. Lists all 33 operations with links to each operation's Markdown.
- [AI and automations API](https://developer.kustomer.com/api/ai.md): AI automations, evaluations with test cases and runs, and conversation summaries. Lists all 19 operations with links to each operation's Markdown.

## Optional

- [Full docs corpus](https://developer.kustomer.com/llms-full.txt): Every docs page concatenated as Markdown
- [Operation index](https://developer.kustomer.com/api/operations.json): Every API operation's operationId, method, path and reference URL as JSON
- [Postman collection](https://developer.kustomer.com/api/kustomer.postman_collection.json): Every API operation as a Postman Collection v2.1, with example parameters, bodies and required roles
- [Changelog](https://developer.kustomer.com/changelog.md): Notable API, SDK and platform changes