CRM API

REST endpoints for the CRM module — contacts, companies, deals, activities, pipelines.

Base path

All endpoints below are relative to the REST API base. Auth + pagination follow the global conventions documented there.

Endpoints

Method	Path	Purpose
GET	`/api/crm/contacts`	List contacts. Filters: `status`, `company_id`, `q` (name/email search).
POST	`/api/crm/contacts`	Create a contact.
GET	`/api/crm/contacts/{id}`	Fetch one contact + linked deals/activities.
PATCH	`/api/crm/contacts/{id}`	Update fields.
DELETE	`/api/crm/contacts/{id}`	Soft-delete (status='inactive').
GET	`/api/crm/companies`	List companies.
POST	`/api/crm/companies`	Create.
GET/PATCH/DELETE	`/api/crm/companies/{id}`	Standard CRUD on one row.
GET	`/api/crm/deals`	List deals. Filters: `stage_id`, `status`, `contact_id`, `min_value`, `max_value`.
POST	`/api/crm/deals`	Create.
GET/PATCH/DELETE	`/api/crm/deals/{id}`	Standard CRUD.
POST	`/api/crm/deals/{id}/stage`	Move a deal to a different pipeline stage. Emits `crm.deal.stage_changed` + (when reaching won/lost) `crm.deal.won
GET	`/api/crm/activities`	List activities. Filters: `contact_id`, `deal_id`, `company_id`, `type`.
POST	`/api/crm/activities`	Log a new activity (call, email, meeting, note).
GET	`/api/crm/pipelines`	List pipelines + their stages.

Key entity shapes

Contact

{
  "id": "uuid",
  "tenant_id": "uuid",
  "first_name": "string",
  "last_name": "string",
  "email": "string?",
  "phone": "string?",
  "job_title": "string?",
  "company_id": "uuid?",
  "status": "active | inactive | lead",
  "metadata": { },
  "created_at": "iso-8601",
  "updated_at": "iso-8601"
}

Deal

{
  "id": "uuid",
  "tenant_id": "uuid",
  "title": "string",
  "value": 0,
  "currency": "USD",
  "status": "open | won | lost",
  "stage_id": "uuid",
  "contact_id": "uuid?",
  "company_id": "uuid?",
  "expected_close_date": "iso-8601?"
}

Permissions

crm.contacts.read|create|update|delete
crm.companies.read|create|update|delete
crm.deals.read|create|update|delete
crm.activities.read|create|update|delete
crm.pipelines.read|update

Events

Mutations emit to the webhook event bus:

crm.contact.created|updated|deleted
crm.company.created|updated|deleted
crm.deal.created|updated|stage_changed|won|lost|deleted
crm.activity.created|updated|deleted

Subscribe via Settings → Webhooks.

Bulk operations

For high-volume ingest, use the bulk REST endpoint instead of looping POSTs.

OpenAPI

Full schema at /api/openapi.json.