#HTTP API

Base URL: https://undocrm.com/v1. JSON in, JSON out. Auth: Authorization: Bearer <key>.

The agent endpoints have the same semantics as the MCP tools, but return structured JSON — use them from backends, queues and agent frameworks without MCP.

Errors look like:

{ "error": { "code": "invalid_input", "message": "Could not read \"@jane\" as a person. …" } }

#Pagination

Lists page with keyset cursors, so every page is as fast as the first, even at millions of rows. Pass limit (default 50, max 200); the response includes next_cursor, which you send back unchanged as ?cursor= for the next page. next_cursor: null means you've reached the end.

curl "https://undocrm.com/v1/contacts?limit=100" -H "Authorization: Bearer $KEY"
# → { "contacts": [...], "next_cursor": "eyJ0IjoiMjAyNi0xMC0xNyAwMjo1NDozMi44NjQ3MjMrMDAiLCJpZCI6ImN0X..." }
curl "https://undocrm.com/v1/contacts?limit=100&cursor=eyJ0Ijoi..." -H "Authorization: Bearer $KEY"

Totals for headers come from cheap count endpoints: GET /contacts/groups (contacts per lifecycle stage), GET /follow-ups/counts (overdue / today / upcoming), and the totals in GET /deals/board.

#Authentication

#Workspaces for your customers — org key

#POST /workspaces

curl -X POST https://undocrm.com/v1/workspaces \
  -H "Authorization: Bearer $ORG_KEY" -H "content-type: application/json" \
  -d '{"name": "Acme Recruiting"}'

{ "workspace": { "id": "ws_cd7b82dcfdcc4ed0", "name": "Acme Recruiting", "org_id": "org_…", "created_at": "…" },
  "owner_key": "ucrm_own_…" }

The owner key is shown once; use it to create that workspace's agents. GET /workspaces lists your organization's workspaces.

#Accounts — signed-in people

These power the web app. All take a signed-in session token; none take API keys.

#Workspace administration — owner key or admin

#People — any key

:person accepts any person string, URL-encoded (/contacts/jane%40acme.com).

#Deals and pipelines — any key

#Agent operations — agent key (owner keys can read)

#GET /brief?person=&purpose=&max_tokens=

{ "text": "# Jane Doe — VP Engineering, Acme …", "contact_id": "ct_…", "tokens": 172,
  "omitted": { "facts": 0, "interactions": 0, "follow_ups": 0 } }

#POST /can-contact

{ "person": "jane@acme.com", "channel": "email", "purpose": "send SOC2 report" }

{ "allowed": true, "reason": "ok", "contact_id": "ct_…", "channel": "email", "block": null,
  "claim": { "id": "cl_…", "agent_id": "ag_…", "agent_name": "sdr-1", "purpose": "send SOC2 report", "expires_at": "…" },
  "last_outbound": { "channel": "email", "occurred_at": "…", "agent_name": "sdr-1" } }

reason is one of ok, do_not_contact, claimed_by_other_agent.

#POST /release

{ "person": "jane@acme.com" } → { "contact_id": "ct_…", "released": true }

#POST /interactions

Body as in log_interaction, plus optional source (default agent; sync integrations set their own, e.g. gmail). Returns 201:

{ "duplicate": false, "interaction_id": "ix_…", "contact_id": "ct_…", "created_contact": false,
  "facts": [{ "id": "fa_…", "key": "budget", "value": "$80k/yr", "previous": "$50k/yr" }],
  "follow_ups": [{ "id": "fu_…", "action": "Send the SOC2 report", "due_at": "…" }],
  "completed_follow_ups": [], "warning": null }

A repeated external_id (per source) returns { "duplicate": true, … } with 200.

#GET /follow-ups?due=&mine=&person=&limit=

due: overdue, today (default), week, all. mine defaults to true for agent keys.

#POST /follow-ups/:id/complete

{ "status": "done" | "cancelled", "outcome": "…" }