Skip to content
Knobs Docs

CRM

All CRM endpoints are workspace-scoped and require a session token or personal access token (see Authentication). Duplicate identity keys return 409 with duplicate_domain / duplicate_email. Enrichment and AI endpoints return 503 (enrich_unavailable / ai_unavailable) when no provider / LLM is configured, and 403 (feature_disabled) when the workspace has turned the feature off.

Companies

Section titled “Companies”
  • GET /v1/workspaces/{wid}/crm/companies — list (newest-updated first, ?limit=).
  • POST /v1/workspaces/{wid}/crm/companies — create. domain is required and is normalized (lowercase, scheme/www./port stripped); one company per domain per workspace.
  • GET /v1/workspaces/{wid}/crm/companies/{id} — fetch one record, including provenance (per-field data source), summary, and lastActivityAt.
  • PATCH /v1/workspaces/{wid}/crm/companies/{id} — partial update; only provided fields change; user-set fields gain manual provenance (enrichment will never overwrite them).
  • DELETE /v1/workspaces/{wid}/crm/companies/{id} — delete; the domain (and aliases) become claimable again.
  • POST /v1/workspaces/{wid}/crm/companies/{id}/aliases — body {"domain": "acme.io"}; claims an additional domain for the company.
  • POST /v1/workspaces/{wid}/crm/companies/{id}/enrich — run the provider waterfall now; returns the merged record.
  • POST /v1/workspaces/{wid}/crm/companies/{id}/summarize — generate + cache the AI account summary; returns the record with summary/summaryAt.

Contacts

Section titled “Contacts”
  • GET /v1/workspaces/{wid}/crm/contacts — list; ?companyId= filters to one company.
  • POST /v1/workspaces/{wid}/crm/contacts — create. email required (normalized lowercase); one contact per email per workspace; optional companyId must exist.
  • GET /v1/workspaces/{wid}/crm/contacts/{id}
  • PATCH /v1/workspaces/{wid}/crm/contacts/{id} — partial update (manual-provenance rules as for companies).
  • DELETE /v1/workspaces/{wid}/crm/contacts/{id}
  • POST /v1/workspaces/{wid}/crm/contacts/{id}/enrich — provider waterfall.
  • POST /v1/workspaces/{wid}/crm/contacts/{id}/score — AI lead score; returns the record with score (0-100), scoreRationale, nextBestAction, scoredAt.
  • POST /v1/workspaces/{wid}/crm/contacts/{id}/outreach — body {"goal": "..."} (optional); returns {"to", "subject", "body"} — a draft for the composer, nothing is sent.

Pipelines & deals

Section titled “Pipelines & deals”
  • GET /v1/workspaces/{wid}/crm/pipelines — list; provisions the workspace default pipeline (Lead/Qualified/Proposal/Negotiation) on first use.
  • POST /v1/workspaces/{wid}/crm/pipelines — create with {"name", "stages": [{"id","name","probability"}]}.
  • PATCH /v1/workspaces/{wid}/crm/pipelines/{id} — rename / replace stages. Removing a stage that still holds deals is rejected.
  • DELETE /v1/workspaces/{wid}/crm/pipelines/{id} — only non-default, empty pipelines.
  • GET /v1/workspaces/{wid}/crm/deals — list, board-ordered (stage, then fractional order); ?pipelineId= (default pipeline if omitted), ?status=open|won|lost.
  • POST /v1/workspaces/{wid}/crm/deals — create; defaults to the default pipeline’s first stage, appended at the end. amountCents + currency for value.
  • GET /v1/workspaces/{wid}/crm/deals/{id}
  • PATCH /v1/workspaces/{wid}/crm/deals/{id} — fields + status transitions (won/lost stamp closedAt; open clears it).
  • DELETE /v1/workspaces/{wid}/crm/deals/{id}
  • POST /v1/workspaces/{wid}/crm/deals/{id}/move — {"stageId", "order"}; empty order appends to the target stage. order is a fractional key — take the midpoint of the neighbors’ keys to insert between them.

Activities

Section titled “Activities”
  • GET /v1/workspaces/{wid}/crm/activities — timeline for exactly one of ?contactId=, ?companyId=, ?dealId=; newest first; ?before= (RFC 3339) + ?limit= for keyset paging. Auto-captured email activities carry source: "auto", the thread/message ids, and direction.
  • POST /v1/workspaces/{wid}/crm/activities — log a manual call / meeting / note with at least one link (contactIds, companyId, dealId).

Settings

Section titled “Settings”
  • GET /v1/workspaces/{wid}/crm/settings — capture/enrich/AI toggles (absent booleans mean the default: enabled) + freemail overrides.
  • PUT /v1/workspaces/{wid}/crm/settings — partial update; workspace admins only.