Build on CRM City

# Smoke test — works with both key types
curl https://<your-crm-domain>/api/crm/me \
  -H "X-CRM-API-Key: crm_sec_xxx..."

# → { "ok": true, "tenant": { ... }, "platform": { "name": "..." }, "key": { "level": "secret" } }

All endpoints live under https://<your-crm-domain>/api/crm and expect the X-CRM-API-Key header. Each entry below states which key level it accepts.

POST /api/crm/contacts deduplicates by email with fill-blanks-only semantics: if a contact with that email already exists, only fields that are currently empty (last_name, phone, notes) are filled in — existing values are never overwritten. That makes it safe for every platform you own to push the same person without clobbering each other's data.

POST /api/crm/contacts
X-CRM-API-Key: crm_sec_xxx...
Content-Type: application/json

{
  "email": "jane@example.com",
  "first_name": "Jane",
  "last_name": "Doe",
  "phone": "+44 7700 900123",
  "source": "my-shop",
  "notes": "Signed up via the summer landing page"
}

# New contact → 201
{ "data": { "id": "…", "first_name": "Jane", "email": "jane@example.com", ... }, "created": true }

# Existing contact → 200; blanks filled, nothing overwritten
{ "data": { ... }, "created": false }

Only genuinely new contacts count towards your plan's contact limit — upserts of existing contacts never do. If the limit is reached, you get 403 plan_limit.

# Place an order (contact by email — created if missing; product by SKU)
curl https://<your-crm-domain>/api/crm/orders \
  -X POST \
  -H "X-CRM-API-Key: crm_sec_xxx..." \
  -H "Content-Type: application/json" \
  -d '{
    "email": "jane@example.com",
    "first_name": "Jane",
    "items": [{ "sku": "PRO-1", "quantity": 2 }]
  }'
# → creates the order, computes the total from the catalogue, fires "order.placed"

# Mark a course enrollment completed (the key flow for external course platforms)
curl https://<your-crm-domain>/api/crm/enrollments/ENROLLMENT_ID \
  -X PATCH \
  -H "X-CRM-API-Key: crm_sec_xxx..." \
  -H "Content-Type: application/json" \
  -d '{ "status": "completed" }'
# → sets completed_at, fires "course.completed"

# Issue the certificate (response contains a public verification_url)
curl https://<your-crm-domain>/api/crm/certificates \
  -X POST \
  -H "X-CRM-API-Key: crm_sec_xxx..." \
  -H "Content-Type: application/json" \
  -d '{ "enrollment_id": "ENROLLMENT_ID" }'

Subscribe any HTTPS URL in Settings → Webhooks (or via POST /api/crm/webhooks) to any subset of the 18 bus events — an empty event list means all of them. Each delivery is an HTTP POST with a JSON body and these headers:

import { createHmac, timingSafeEqual } from "crypto";

// rawBody: the EXACT request body bytes (before any JSON parsing)
// signatureHeader: the X-CRM-Signature header value
// secret: the whs_... secret returned when you created the subscription
function verifyWebhook(rawBody, signatureHeader, secret) {
  const expected = "sha256=" + createHmac("sha256", secret).update(rawBody).digest("hex");
  const a = Buffer.from(expected);
  const b = Buffer.from(signatureHeader ?? "");
  return a.length === b.length && timingSafeEqual(a, b); // timing-safe compare
}

Create an ingest source in Settings → Ingest sources — each source gets a slug and a verify secret, and its own URL. Incoming payloads are normalised into contacts and activities: the contact is upserted by email, gaps are backfilled, and everything is journaled (including failures).

# Generic ingest — the simple JSON shape any platform can send
curl "https://<your-crm-domain>/api/ingest/generic?key=<verify_secret>" \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{
    "email": "jane@example.com",
    "first_name": "Jane",
    "last_name": "Doe",
    "phone": "+44 7700 900123",
    "event": "signed_up",
    "value": 49.99,
    "currency": "GBP"
  }'

CRM City ships a native Model Context Protocol (MCP) server. Point any MCP-capable AI agent (Claude, or your own) at it and the agent can search contacts, enrich them, log activities, tag, create tasks and read your deals and products — always inside the tenant of the API key, with the same rate limits as the REST API.

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_..." }
    }
  }
}