A reference guide for building AI agents: every method, how to authenticate, and the permissions each one needs.
The Kustomer API is how an app or AI agent works with a Kustomer organization: reading and creating customer records, opening and updating conversations, sending messages on a customer timeline, and adding internal notes. Access is granted through an API key sent as a Bearer token, and the roles attached to that key set which objects a call can read or write. A create or update emits a Kustomer Event that an outbound web hook can deliver to a registered endpoint.
How an app or AI agent connects to Kustomer determines what it can reach. There is a route for making calls, a route for receiving events, and a hosted server that exposes Kustomer data to agents, and each is governed by the API key behind it and the roles that key carries.
The REST API answers at https://{orgname}.api.kustomerapp.com, where {orgname} is the organization's name. It returns JSON in a data envelope with id, attributes, and relationships, and the customer-experience methods live under the /v1 path while the knowledge-base methods live under /v3. A call authenticates with an API key sent as a Bearer token.
Kustomer POSTs a Kustomer Event object to a registered URL when a subscribed event fires, like kustomer.customer.create or kustomer.conversation.update. The payload carries a snapshot of the changed customer, conversation, message, user, or team, along with what changed. Web hooks are managed through the /v1/hooks/web methods.
Kustomer publishes a first-party Model Context Protocol server that connects an MCP-compatible AI client, like Claude or ChatGPT, to an organization's Kustomer data. In this version it gives read-only access to conversations, customers, companies, and more. It is included on the Enterprise and Ultimate plans.
Every request carries an API key in the Authorization header as 'Bearer {API_KEY}'. The key is a signed JSON Web Token (JWT) created in Settings under Security, where it is assigned one or more roles that limit what it can do. The key is shown once when created and authenticates first-party calls.
A key is scoped by the roles attached to it when it is created. Legacy roles follow org.user.
The Kustomer API is split into areas an agent can act on, like customers, conversations, messages, notes, teams, and users. Each area has its own methods, and a write here can reply to a real customer, change a conversation, or delete a customer record.
Create, read, update, and delete customer records, and look a customer up by id, email, phone, or external id.
Create, read, update, and delete conversations, and list a customer's conversations.
Create messages on a conversation or for a customer, read messages, and update a message.
Create internal notes and list the notes on a conversation.
Create and read KObjects, the records that belong to custom object types (klasses).
List and read the users and teams in the organization.
Create knowledge-base article tags and reusable shortcuts (saved replies).
Run a customer search query across the organization's data.
List the organization's outbound web hooks and create a new one.
Filter by method, access, or permission, or search any path. Select a row for version detail, rate limits, the related webhook event, and the source.
| Method | Endpoint | What it does | Access | Permission | Version | |
|---|---|---|---|---|---|---|
CustomersCreate, read, update, and delete customer records, and look a customer up by id, email, phone, or external id.6 | ||||||
| POST | /v1/customers | Create a new customer record. | write | org.user.customer.write | Current | |
Legacy role org.user.customer.write, or the permission-set role org.permission.customer.create. Acts oncustomer Permission (capability) org.user.customer.writeVersionAvailable since the API’s base version Webhook event kustomer.customer.createRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v1/customers/{id} | Get a customer by id. | read | org.user.customer.read | Current | |
Read-only. Legacy role org.user.customer.read, or the permission-set role org.permission.customer.read. Acts oncustomer Permission (capability) org.user.customer.readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v1/customers/email={email} | Look a customer up by email address. | read | org.user.customer.read | Current | |
Read-only. Acts oncustomer Permission (capability) org.user.customer.readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v1/customers/externalId={externalId} | Look a customer up by external id. | read | org.user.customer.read | Current | |
Read-only. The external id is the customer's id in another system. Acts oncustomer Permission (capability) org.user.customer.readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PUT | /v1/customers/{id} | Update a customer by id. | write | org.user.customer.write | Current | |
A single customer can be updated up to 600 times per 10 minutes by the per-object limit. Acts oncustomer Permission (capability) org.user.customer.writeVersionAvailable since the API’s base version Webhook event kustomer.customer.updateRate limit600 updates per 10 minutes per customer SourceOfficial documentation ↗ | ||||||
| DELETE | /v1/customers/{id} | Delete a customer by id. | write | org.user.customer.write | Current | |
Irreversible. Removes the customer and its associated timeline. Acts oncustomer Permission (capability) org.user.customer.writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
ConversationsCreate, read, update, and delete conversations, and list a customer's conversations.6 | ||||||
| POST | /v1/conversations | Create a new conversation. | write | org.user.conversation.write | Current | |
Legacy role org.user.conversation.write, or the permission-set role org.permission.conversation.create. Acts onconversation Permission (capability) org.user.conversation.writeVersionAvailable since the API’s base version Webhook event kustomer.conversation.createRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v1/customers/{id}/conversations | Create a conversation for a specific customer. | write | org.user.conversation.write | Current | |
Held to 120 conversations per minute per customer by the per-object limit. Acts onconversation Permission (capability) org.user.conversation.writeVersionAvailable since the API’s base version Webhook event kustomer.conversation.createRate limit120 per minute per customer SourceOfficial documentation ↗ | ||||||
| GET | /v1/conversations/{id} | Get a conversation by id, or several with a comma-separated list of ids. | read | org.user.conversation.read | Current | |
Read-only. Acts onconversation Permission (capability) org.user.conversation.readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v1/customers/{id}/conversations | List a customer's conversations (paginated). | read | org.user.conversation.read | Current | |
Read-only. Acts onconversation Permission (capability) org.user.conversation.readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PUT | /v1/conversations/{id} | Update a conversation by id (status, assignee, tags, custom attributes). | write | org.user.conversation.write | Current | |
A single conversation can be updated up to 100 times per 10 minutes by the per-object limit. Acts onconversation Permission (capability) org.user.conversation.writeVersionAvailable since the API’s base version Webhook event kustomer.conversation.updateRate limit100 updates per 10 minutes per conversation SourceOfficial documentation ↗ | ||||||
| DELETE | /v1/conversations/{id} | Delete a conversation by id. | write | org.user.conversation.write | Current | |
Irreversible. Acts onconversation Permission (capability) org.user.conversation.writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
MessagesCreate messages on a conversation or for a customer, read messages, and update a message.4 | ||||||
| POST | /v1/messages | Create a message and add it to a customer timeline. | write | org.user.message.write | Current | |
Held to 120 messages per minute per customer; a message with importedAt set is exempt from that limit. Acts onmessage Permission (capability) org.user.message.writeVersionAvailable since the API’s base version Webhook event kustomer.message.createRate limit120 per minute per customer SourceOfficial documentation ↗ | ||||||
| POST | /v1/conversations/{id}/messages | Create a message on an existing conversation. | write | org.user.message.write | Current | |
Held to 120 messages per minute per customer. Acts onmessage Permission (capability) org.user.message.writeVersionAvailable since the API’s base version Webhook event kustomer.message.createRate limit120 per minute per customer SourceOfficial documentation ↗ | ||||||
| GET | /v1/messages | List messages. | read | org.user.message.read | Current | |
Read-only. Acts onmessage Permission (capability) org.user.message.readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PUT | /v1/messages/{id} | Update a message by id. | write | org.user.message.write | Current | |
A single message can be updated up to 100 times per 10 minutes by the per-object limit. Acts onmessage Permission (capability) org.user.message.writeVersionAvailable since the API’s base version Webhook event kustomer.message.updateRate limit100 updates per 10 minutes per message SourceOfficial documentation ↗ | ||||||
NotesCreate internal notes and list the notes on a conversation.2 | ||||||
| POST | /v1/notes | Create an internal note. | write | org.user.note.write | Current | |
Held to 120 notes per minute per customer by the per-object limit. Acts onnote Permission (capability) org.user.note.writeVersionAvailable since the API’s base version Webhook eventNone Rate limit120 per minute per customer SourceOfficial documentation ↗ | ||||||
| GET | /v1/conversations/{id}/notes | List the notes on a conversation. | read | org.user.note.read | Current | |
Read-only. Acts onnote Permission (capability) org.user.note.readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Custom objects (KObjects)Create and read KObjects, the records that belong to custom object types (klasses).2 | ||||||
| POST | /v1/klasses/{name} | Create a KObject in a custom object type (klass). | write | org.user.kobject.write | Current | |
The klass name in the path is the custom object type. Held to 120 custom objects per minute per customer by the per-object limit. Acts onkobject Permission (capability) org.user.kobject.writeVersionAvailable since the API’s base version Webhook eventNone Rate limit120 per minute per customer SourceOfficial documentation ↗ | ||||||
| GET | /v1/klasses/{name} | Read the KObjects in a custom object type (klass). | read | org.user.kobject.read | Current | |
Read-only. Acts onkobject Permission (capability) org.user.kobject.readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Users & teamsList and read the users and teams in the organization.3 | ||||||
| GET | /v1/users | List the users in the organization, with optional filters. | read | org.user.user.read | Current | |
Read-only. Can filter by pending or deactivated status, user type, or email. Acts onuser Permission (capability) org.user.user.readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v1/teams | List the teams in the organization. | read | org.user.team.read | Current | |
Read-only. Acts onteam Permission (capability) org.user.team.readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v1/teams/{id} | Get a team by id. | read | org.user.team.read | Current | |
Read-only. Acts onteam Permission (capability) org.user.team.readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Tags & shortcutsCreate knowledge-base article tags and reusable shortcuts (saved replies).2 | ||||||
| POST | /v3/kb/tags | Create a knowledge-base tag for articles. | write | org.user.tag.write | Current | |
Knowledge-base tags are served under the v3 path, not v1. Acts ontag Permission (capability) org.user.tag.writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v1/shortcuts | Create a shortcut, a reusable saved reply or snippet. | write | org.user.shortcut.write | Current | |
A shortcut is a saved reply agents can insert into messages. Acts onshortcut Permission (capability) org.user.shortcut.writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
SearchRun a customer search query across the organization's data.1 | ||||||
| POST | /v1/customers/search | Run a customer search query across the organization's data. | read | org.user.customer.read | Current | |
A POST that only queries data. Search has its own limit of 100 requests per minute for machine users, and returns at most 100 pages. Acts onsearch result Permission (capability) org.user.customer.readVersionAvailable since the API’s base version Webhook eventNone Rate limit100 per minute (machine users) SourceOfficial documentation ↗ | ||||||
WebhooksList the organization's outbound web hooks and create a new one.2 | ||||||
| GET | /v1/hooks/web | List the organization's outbound web hooks. | read | org.admin | Current | |
Read-only. Managing web hooks needs an admin role. Acts onwebhook Permission (capability) org.adminVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v1/hooks/web | Create an outbound web hook that posts events to a URL. | write | org.admin | Current | |
Managing web hooks needs an admin role. Acts onwebhook Permission (capability) org.adminVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Kustomer can notify an app when something happens in an organization, like a customer being created or a conversation being updated. It sends a POST with a Kustomer Event object that holds a snapshot of the changed record, so an integration learns about activity without polling.
| Event | What it signals | Triggered by |
|---|---|---|
kustomer.customer.create | Fires when a customer record is created. | /v1/customers |
kustomer.customer.update | Fires when a customer record is updated. | /v1/customers/{id} |
kustomer.conversation.create | Fires when a conversation is created. | /v1/conversations/v1/customers/{id}/conversations |
kustomer.conversation.update | Fires when a conversation is updated, like a status change or reassignment. | /v1/conversations/{id} |
kustomer.message.create | Fires when a message is created on a conversation or customer timeline. | /v1/messages/v1/conversations/{id}/messages |
kustomer.message.update | Fires when a message is updated. | /v1/messages/{id} |
kustomer.user.update | Fires when a user is created or updated. Kustomer also emits kustomer.user.create on user creation. | In-app only |
kustomer.team.update | Fires when a team is created or updated. Kustomer also emits kustomer.team.create on team creation. | In-app only |
Kustomer limits how fast an app can call, through a per-organization request rate that depends on the plan and a separate set of per-object limits on how often a single record can change.
Kustomer meters requests per organization across all of its API keys, within a rolling 60-second window, and the ceiling depends on the plan: 300 requests per minute on legacy Professional, 500 on legacy Business, 1,000 on Enterprise, and 2,000 on Ultimate. Customer search has its own limit of 100 requests per minute for machine users. Separate per-object limits cap how often one record can change: a conversation, company, or message can be updated 100 times in 10 minutes, a customer 600 times in 10 minutes, and a single customer can receive up to 120 new drafts, messages, conversations, notes, or custom objects per minute. Going over returns HTTP 429, and the response carries x-ratelimit-limit, x-ratelimit-remaining, and x-ratelimit-reset, plus x-ratelimit-object-limit, x-ratelimit-object-remaining, and x-ratelimit-object-reset for the per-object limits.
List endpoints are paginated. A customer search returns results in pages with a hard cap of 100 pages per query, and list endpoints return a page of records with links to fetch the next page.
Responses are JSON in a data envelope, with each record carrying id, attributes, and relationships. A single customer can receive at most 120 new drafts, messages, conversations, notes, or custom objects per minute.
The status codes an agent should handle, and what to do about each.
| Status | Code | Meaning | What to do |
|---|---|---|---|
| 400 | Bad Request | The request was malformed or a parameter was invalid. The body carries an errors array describing what went wrong. | Read the errors array, correct the request, and resend. It is not retryable as-is. |
| 401 | Unauthorized | The API key is missing, malformed, or invalid. | Send a valid key as 'Authorization: Bearer {API_KEY}', and rotate the key if it is compromised. |
| 403 | Forbidden | The key is valid but its roles do not allow this operation. | Attach the role the method needs to the key, like org.user.customer.write, or use a key that has it. |
| 404 | Not Found | The requested record does not exist, or is not visible to this key. | Confirm the id and that the key's roles can see the record. |
| 429 | Too Many Requests | A per-organization rate limit or a per-object limit was exceeded. The x-ratelimit and x-ratelimit-object headers report the current state. | Back off until the window in x-ratelimit-reset, then retry. Smooth bursts of writes to one record. |
| 500 | Internal Server Error | An error on Kustomer's side. It is rare. | Retry with backoff, and contact Kustomer support if it persists. |
Kustomer carries the version in the request path, with the customer-experience methods served under v1 and the knowledge-base methods under v3. There is no dated version string to pin.
Kustomer versions its API in the request path rather than through a dated version header. The customer-experience methods, covering customers, conversations, messages, notes, teams, users, search, and custom objects, are served under the /v1 path, and there is no dated version string to pin. The knowledge-base methods are served under a separate /v3 path.
The version is part of each method's path, so an integration targets it directly.
Kustomer API reference ↗Bollard AI sits between a team's AI agents and Kustomer. Grant each agent exactly the access it needs, read or write, resource by resource, and every call is checked and logged.