CRM overview - KeebAI

The CRM surface exposes the four core entities of Keebai’s customer relationship data — customers, tickets, tasks, and notes — as a plain REST API under /v1/crm. 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.

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.

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.

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
`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.

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.
`502`	The CRM service is unreachable. Retry with backoff.

Next steps

Create a customer

Open a ticket

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

​Data model

Customers

Tickets

Tasks

Notes

​Scopes

​Tenancy is implicit

​Identifiers

​Pagination

​Updates are partial

​Errors

​Next steps