CRM overview - KeebAI

The CRM surface exposes the core entities of Keebai’s customer relationship data — customers, tickets, tasks, and notes — as a plain REST API under /v1/crm, plus an event ingest that records what happens in your own systems onto a contact’s timeline. Every endpoint authenticates with a Personal Access Token and is gated by its own scope.

Data model

Customers

A person or organization you do business with. Identified by name plus optional email, phone, and a national identification number that is unique within your company.

Tickets

A conversation, deal, or case moving through a pipeline. Always attached to a chat user (the contact behind a messaging conversation), and optionally to a stage, an owner, tags, and a monetary amount.

Tasks

A unit of work with a title, an optional assignee, a status, a priority, and a due date. Tasks stand on their own — they are not attached to a ticket or a customer.

Notes

A free-text annotation, optionally typed as a call, email, or meeting, and optionally attached to a chat user or a ticket.

Events

Something that happened to a contact, appended to their ticket’s timeline. Unlike the four above, events are append-only and their payload is validated against the fields their type declares.

Custom fields

Tickets and customers both carry a custom_fields object. The same field definitions compose the payload of an event type, which is how an event’s values end up on the ticket.

Customers and tickets are separate records that are not linked by a foreign key. A customer is the commercial identity; a ticket is a unit of work tied to a contact — the record created when someone writes to one of your channels, exposed as /v1/contacts and referred to as chat_user throughout the CRM. If you need to correlate a customer with a ticket, match on phone or email, or store the customer id in the ticket’s custom_fields.

Scopes

Scope	Grants
`crm:customers:read`	List and read customers.
`crm:customers:write`	Create and update customers.
`crm:customers:delete`	Delete customers. Permanent.
`crm:tickets:read`	List and read tickets.
`crm:tickets:write`	Create, update, and move between stages.
`crm:tickets:delete`	Delete tickets. Permanent.
`crm:tasks:read`	List and read tasks.
`crm:tasks:write`	Create and update tasks.
`crm:tasks:delete`	Delete tasks. Permanent.
`crm:notes:read`	List and read notes.
`crm:notes:write`	Create and update notes.
`crm:notes:delete`	Delete notes. Permanent.
`crm:events:write`	Emit CRM events onto a contact’s timeline. There is no read counterpart on the public API.

The delete scopes are split out on purpose: a sync job that keeps records in step with an external system should be able to create and update without being able to destroy. crm:events:write deserves its own token. It is the only CRM scope an external system needs to push history in, and it writes to tickets and contacts as a side effect — keeping it separate from your read tokens means you can revoke the ingest without blinding your dashboards.

Tenancy is implicit

Every CRM record belongs to a company, and most also belong to a project. You never send either one. Keebai derives them from the token on each request:

Field	Source	Applies to
`company`	The company that owns the token	Every CRM record
`project`	The project the token was minted for	Customers, tickets, notes, and the ticket an event opens
`created_by`	The user who owns the token	Notes

Sending any of these in the request body returns 400 Bad Request — the public API rejects unknown properties rather than silently ignoring them. This is deliberate: it makes an attempt to write into another tenant fail loudly instead of quietly doing nothing.

Reads are company-wide, writes are project-scoped.Records you create are stamped with the project your token belongs to. List endpoints, however, return every record in the company, including records that belong to other projects. A token minted for project A will see tickets, customers, notes, and tasks created under project B.If your company uses more than one project and you need per-project separation in the results, filter client-side on the project field of each record. Tasks have no project field at all — they are company-level by design.

Identifiers

All ids are MongoDB ObjectIds: 24 lowercase hexadecimal characters, for example 65a1f2b3c4d5e6f7a8b9c0d1. That includes the ids you pass in request bodies — chat_user, assigned_to, stage_id, ticket_id, and the entries of tags / tag_ids. The chat_user id comes from GET /v1/contacts, which is the supported way to look a contact up by phone or name before creating a ticket or a note. There is still no public endpoint for discovering pipelines, stages, tags, or users. Read those ids from the Keebai portal, or capture them from the payloads of the outbound webhooks your integration already receives.

Pagination

List endpoints take limit and offset and return a consistent envelope:

{
  "data": [],
  "total": 0,
  "limit": 50,
  "offset": 0
}

limit caps at 200 on every list endpoint, and a value above it returns 400 — page with offset rather than trying to raise the ceiling. The default page size is 50 everywhere except notes, which defaults to 100.

Updates are partial

Every update endpoint is a PATCH and applies only the fields you send. Omitted fields keep their current value; there is no PUT-style full replacement. Two fields on tickets are worth calling out, because they behave differently from the rest:

tag_ids replaces the entire tag list.
add_tag_ids and remove_tag_ids modify the list incrementally, leaving the tags you did not mention alone.

Use the incremental pair whenever more than one system writes tags to the same ticket.

Custom fields

Tickets and customers both carry a custom_fields object — a flat map keyed by the field’s key, holding whatever your company configured in the portal under CRM → Fields. There is no public endpoint for reading the field definitions, so an integration has to know the keys it writes. Read them from the portal once and treat them as part of your contract.

Definition property	Effect on the API
`type`	`text`, `number`, `select`, `date`, `boolean`. Only enforced on the paths that validate — see below.
`options`	For `select`, the allowed values.
`is_required`	Enforced when the field composes an event type’s payload, not on plain ticket or customer writes.
`scope`	`ticket` or `client`. Decides which record the field belongs to.

custom_fields is merged, not replaced. A PATCH carrying {"custom_fields": {"a": 1}} leaves every other key alone. There is no way to delete a key through the API — set it to null.Values are not type-checked on ticket and customer writes. Sending a string into a number field stores the string. The one path that does validate is the event ingest, which rejects the whole request rather than storing a bad value.

Writes have side effects

CRM writes are not inert. Each one can trigger work you should know about before you build a sync loop:

What you do	What else happens
Create or update a ticket	`crm.ticket.updated` (and `crm.ticket.closed` when it closes) is delivered to your webhook subscribers, the portal updates in realtime, and the record is queued for write-back to any connected external CRM.
Move a ticket’s stage	`crm.ticket.stage_changed`, plus `conversation.escalated_to_human` when the destination stage is human-attended.
Emit an event	The event’s values are written onto the ticket and the contact, which in turn fires the ticket webhooks above.

Beware of loops. If your integration both subscribes to crm.ticket.updated and writes tickets in response, an event ingest that touches a ticket field will call you back. Guard with an idempotency check on your side, or filter out changes your own token produced.

Rate limits

The CRM endpoints draw from the shared per-project quota — 60 a minute, 200 an hour, 1,000 a day across every endpoint of the public API. The one exception is POST /v1/webhook/events, which carries a far higher allowance of its own (300 a minute, 50,000 a day) because an ingest is not interactive traffic. If you are syncing a CRM with tens of thousands of records, the daily cap is the binding constraint. Prefer outbound webhooks over polling, and email support before you start rather than after the first 429.

Errors

The CRM surface uses the same error envelope as the rest of the public API:

{
  "error": {
    "code": "INSUFFICIENT_SCOPE",
    "message": "Forbidden",
    "details": {
      "required": ["crm:tickets:write"],
      "missing": ["crm:tickets:write"]
    }
  }
}

Status	When
`400`	Invalid body or query, or a property the endpoint does not accept (including `company` and `project`).
`401`	Missing, invalid, revoked, or expired token.
`403`	The token lacks the scope the endpoint requires.
`404`	The record does not exist, or belongs to another company.
`422`	Only on the event ingest: the request was valid but the event was not recorded. `error.code` says why.
`429`	You hit a rate limit.
`502`	The CRM service is unreachable. Retry with backoff.

Branch on error.code, never on error.message — the wording is not stable and some of it is in Spanish.

Next steps

Create a customer

Open a ticket

Start a case in a pipeline and move it through its stages.

Emit an event

Push what happened in your ERP, POS, or backoffice onto the contact’s timeline.

Subscribe to changes

Get crm.ticket.* delivered to your server instead of polling for them.

​Data model

Customers

Tickets

Tasks

Notes

Events

Custom fields

​Scopes

​Tenancy is implicit

​Identifiers

​Pagination

​Updates are partial

​Custom fields

​Writes have side effects

​Rate limits

​Errors

​Next steps

Create a customer

Open a ticket

Emit an event

Subscribe to changes

Data model

Scopes

Tenancy is implicit

Identifiers

Pagination

Updates are partial

Custom fields

Writes have side effects

Rate limits

Errors

Next steps