Build on CRM City

1. Sign in and create an API key in Settings → API keys. Create one key per integration — each key is named, shown in full exactly once, and can be revoked independently without breaking your other integrations.
2. Copy the secret key (crm_sec_…) and store it in your platform's environment variables — never hardcode it or ship it to a browser.
3. Authenticate every request with the header X-CRM-API-Key: crm_sec_…Some clients — agent builders especially — make you pick the header name from a fixed list. Any of these work and mean the same thing: x-api-key, api-key, apikey, or Authorization: Bearer crm_sec_…
4. The base URL is your CRM's domain: https://<your-crm-domain>/api/crm/...
5. Smoke-test the key with GET /api/crm/me, then start syncing contacts with POST /api/crm/contacts.

Identity

Contacts

Companies

Deals

Products

Orders (sensitive)

Invoices (sensitive, read-only)

Bookings (sensitive, read-only)

Courses & enrollments

Certificates (sensitive)

Platform events

Groups

Hierarchy

Invitations

Webhook subscriptions

Segments

Pastoral alerts

Field permissions

Backup & export

/api/crm/segments/:slug/contacts accepts these standard slugs:

• all — all active contacts
• tag:<name> — contacts with the given tag
• leaders — contacts with the "leader" role in any group
• role:<role> — contacts with a specific role in any group
• group:<id> — members of a group
• inactive-30 — contacts with no activity for 30+ days

• X-CRM-Signature: sha256=<hex> — HMAC-SHA256 of the raw request body, keyed with your subscription secret (whs_…, shown once at creation)
• X-CRM-Event: <event name> — e.g. order.placed
• User-Agent: CRM-City-Webhook/1.0

The body is { "event", "occurred_at", "tenant_id", "data" } — use occurred_at (ISO timestamp inside the signed payload) to reject stale replays. Failed deliveries (non-2xx or timeout after 10s) are retried with exponential backoff: 1m, 5m, 30m, 2h, 12h.

Ingest endpoints

Connect (streamable HTTP)

Endpoint:  POST https://<your-crm-domain>/api/mcp
Header:    X-CRM-API-Key: crm_sec_...   (secret key required)

Example client config (Claude Code):
{
  "mcpServers": {
    "crm-city": {
      "type": "http",
      "url": "https://<your-crm-domain>/api/mcp",
      "headers": { "X-CRM-API-Key": "crm_sec_..." }
    }
  }
}

The tools

Each key decides which of these it may call — Settings → API Keys → Tools. A switched-off tool is not listed to the agent and is refused if called.

• search_contacts / get_contact — find and read contacts (tags, lead score included)
• get_contact_context — the full picture before writing: history, cadence, what was last said
• upsert_contact — create or enrich by email, fill-blanks-only (same contract as the REST upsert)
• update_contact — replace details on a contact; the previous value is written to the timeline first, and the tool is off until you switch it on per key
• reschedule_followup — set or move the date a contact should next be reached; the previous date goes to the audit log, not the timeline, so routine rescheduling does not bury the notes worth reading
• escalate_to_human — when someone asks to speak to a person, this logs the ask on their timeline and rings the bell for the account owner, with a link straight to the contact. It sends the person nothing: the agent still answers them, and tells them a human has been told
• delete_contact — a recoverable delete: the contact moves to the recycle bin, where a person can restore it. Nothing is removed on a timer
• log_activity — note/call/meeting/email on the timeline
• add_tag — tag a contact (auto-creates the tag)
• create_task — a task with a due date, optionally linked to a contact
• complete_task — tick off a task: a one-off one is closed, a repeating one moves to its next date, exactly as when you tick it in the app
• list_deals — open/won/lost deals with stage and contact
• list_invoices — invoices with number, status, total and dates; filter by contact or status. Never returns the invoice's public link token
• get_invoice — one invoice by id or number, with every line item
• list_receivables — unpaid invoices past their due date, oldest first, with days late and a total per currency
• list_campaign_results — what a campaign did: sent, delivered, opens, clicks, and the outcomes recorded per recipient with the money attached
• list_products — the active catalog
• list_flows — your automations and campaigns
• list_upcoming_occasions — birthdays and dates worth a message
• draft_personal_message — writes into drafts; it cannot send
• list_conversations — the inbox: who wrote to the bot, newest first
• get_conversation_messages — what the person actually said, oldest first
• send_telegram_message — replies in an existing Telegram thread. Off by default on every key, and it takes no phone number or username, so it cannot start a thread with someone who has not written to you first
• send_email — sends from a department box (sales, marketing, support…) to a contact already in your CRM, once your workspace can connect its own email account. Today every call is refused and logged as not sent: CRM City no longer sends a workspace's email to its contacts from its own account. Off by default on every key, and it takes no email address, only a contact id, so it cannot reach someone you have not added. It refuses rather than send when nothing would receive a reply, writes the send on the contact's timeline before it leaves, and respects the recipient's preferences and suppression
• get_help — the manual, so the agent answers from it instead of guessing

Tools are a fixed whitelist mapped onto the same internals as the REST API — an agent can never do more than the key allows, and each tool can be switched off per key in Settings → API Keys. Read tools are on unless you switch them off; a tool that sends to a person is off until you switch it on. No SSE stream in v1; responses are plain JSON.