MetriCRM REST API

Authentication

Create a key in Settings → API keys and send it as a bearer token. Keys look like mck_your-workspace_…, act as the person who created them and only reach the resources in their scopes. Use api.metricrm.com/v1 or your workspace address followed by /api/v1.

curl https://api.metricrm.com/v1/me \
  -H "Authorization: Bearer mck_your-workspace_…"

Pagination and filters

Lists return up to 100 records per page with a nextCursor; pass it back as cursor to get the next page. Sort by createdAt or updatedAt in either order, and use updatedSince to sync only what changed.

curl "https://api.metricrm.com/v1/contacts?limit=50&updatedSince=2026-10-01T00:00:00Z&order=asc&sort=updatedAt"
# → { "data": [ … ], "nextCursor": "WyIyMDI2LTEwLTEz…" }
curl "https://api.metricrm.com/v1/contacts?limit=50&cursor=WyIyMDI2LTEwLTEz…"

Errors

Errors use normal HTTP status codes and one JSON shape: a code you can program against, a readable message and, for invalid input, the fields to fix. 401 means the key is missing or no longer valid; 403 means its scopes, its owner's role or its IP allowlist do not allow the call; 404 also covers records the key cannot see.

HTTP/1.1 400 Bad Request
{ "error": { "code": "invalid_request",
    "message": "Some fields are missing or invalid.",
    "details": [ { "path": "email", "message": "Invalid email address" } ] } }

Rate limits

Each key has its own limit per minute (600 by default, set when you create the key). Every response tells you where you stand; when you reach the limit, wait for the number of seconds in Retry-After.

HTTP/1.1 429 Too Many Requests
RateLimit-Limit: 600
RateLimit-Remaining: 0
RateLimit-Reset: 42
Retry-After: 42

Idempotency

Send an Idempotency-Key header with POST requests. If the network fails and you retry with the same key and body within 24 hours, you get the first response back instead of a duplicate record.

curl https://api.metricrm.com/v1/contacts \
  -H "Authorization: Bearer $METRICRM_API_KEY" \
  -H "Idempotency-Key: 6f1c2a9e-0b6d-4c1e-9a55-2f1d0e7b3c11" \
  -H "Content-Type: application/json" \
  -d '{"firstName":"Aisyah","lastName":"Rahman","email":"aisyah@sinar.my"}'

Webhooks

Settings → Webhooks sends events (case.created, invoice.paid …) to your HTTPS endpoint as JSON. Each request is signed following Standard Webhooks: verify webhook-signature with your endpoint's whsec_ secret, reject old timestamps and use webhook-id to ignore repeats. Answer with any 2xx status; anything else is retried for about 3½ days.

// Node.js: verify a MetriCRM webhook (Standard Webhooks)
import { createHmac, timingSafeEqual } from "node:crypto";

function verify(secret, headers, rawBody) {
  const id = headers["webhook-id"], ts = headers["webhook-timestamp"];
  if (Math.abs(Date.now() / 1000 - Number(ts)) > 300) return false; // too old
  const key = Buffer.from(secret.replace(/^whsec_/, ""), "base64");
  const expected = createHmac("sha256", key).update(`${id}.${ts}.${rawBody}`).digest();
  return headers["webhook-signature"].split(" ").some((s) => {
    const sig = Buffer.from(s.split(",")[1] ?? "", "base64");
    return sig.length === expected.length && timingSafeEqual(sig, expected);
  });
}

// Body: { "type": "case.created", "timestamp": "…",
//         "data": { "id": "…", "entityType": "case", "object": { … }, "changes": { … } } }

curl "https://api.metricrm.com/v1/me?limit=10" \
  -H "Authorization: Bearer $METRICRM_API_KEY"

curl "https://api.metricrm.com/v1/accounts?limit=10" \
  -H "Authorization: Bearer $METRICRM_API_KEY"

curl "https://api.metricrm.com/v1/contacts?limit=10" \
  -H "Authorization: Bearer $METRICRM_API_KEY"

curl "https://api.metricrm.com/v1/cases?limit=10" \
  -H "Authorization: Bearer $METRICRM_API_KEY"

curl "https://api.metricrm.com/v1/comments?limit=10" \
  -H "Authorization: Bearer $METRICRM_API_KEY"

curl "https://api.metricrm.com/v1/leads?limit=10" \
  -H "Authorization: Bearer $METRICRM_API_KEY"

curl "https://api.metricrm.com/v1/opportunities?limit=10" \
  -H "Authorization: Bearer $METRICRM_API_KEY"

curl "https://api.metricrm.com/v1/quotations?limit=10" \
  -H "Authorization: Bearer $METRICRM_API_KEY"

curl "https://api.metricrm.com/v1/orders?limit=10" \
  -H "Authorization: Bearer $METRICRM_API_KEY"

curl "https://api.metricrm.com/v1/invoices?limit=10" \
  -H "Authorization: Bearer $METRICRM_API_KEY"

curl "https://api.metricrm.com/v1/payments?limit=10" \
  -H "Authorization: Bearer $METRICRM_API_KEY"

curl "https://api.metricrm.com/v1/products?limit=10" \
  -H "Authorization: Bearer $METRICRM_API_KEY"

curl "https://api.metricrm.com/v1/tasks?limit=10" \
  -H "Authorization: Bearer $METRICRM_API_KEY"

curl "https://api.metricrm.com/v1/activities?limit=10" \
  -H "Authorization: Bearer $METRICRM_API_KEY"

curl "https://api.metricrm.com/v1/articles?limit=10" \
  -H "Authorization: Bearer $METRICRM_API_KEY"

curl "https://api.metricrm.com/v1/messages?limit=10" \
  -H "Authorization: Bearer $METRICRM_API_KEY"

curl "https://api.metricrm.com/v1/users?limit=10" \
  -H "Authorization: Bearer $METRICRM_API_KEY"