The Clerra API

1. 1

   Turn it on

   A firm admin opens Settings → API in Clerra and switches API access on.

2. 2

   Make a key

   Choose only what it needs, then copy the key — it's shown once.

3. 3

   Call it

   Send the key in the Authorization header. Start with GET /me.

curl "https://app.clerra.ca/api/v1/filings?status=upcoming&limit=2" \
  -H "Authorization: Bearer $CLERRA_KEY"

Keys look like clerra_ followed by two parts: a public id and a secret. Send the whole key as a bearer token: Authorization: Bearer clerra_…. A key in the URL is refused — URLs end up in logs.

• A key belongs to one firm. Which firm comes from the key itself, never from anything in the request.
• Clerra keeps only a one-way hash of the secret. Lost it? Revoke it and make another.
• Keys can expire (30 days, 90 days, a year) or not. Revoking one stops it on the next request.
• Only someone whose role covers every client can make a key, and a key can’t do anything its maker’s role can’t.

Building something many firms will use? Instead of asking each firm to paste a key, send them through OAuth 2.0: they sign in to Clerra, see exactly what your app is asking for, and approve. Your app gets tokens for that one firm. Apps are registered by Clerra — write to support@clerra.ca with your app’s name, redirect URL and the scopes it needs.

1. Send the person to https://app.clerra.ca/oauth/authorize with response_type=code, client_id, redirect_uri (exactly as registered), scope (space-separated), state, and PKCE: code_challenge with code_challenge_method=S256 (required for apps without a secret, recommended for all).
2. Someone in the firm with the “API keys” permission approves. They come back to your redirect_uri with code and your state — or error=access_denied.
3. Exchange the code (within 10 minutes, once) at POST https://app.clerra.ca/oauth/token.
4. Call the API with the access token exactly like a key: Authorization: Bearer clerra_at_….

curl -X POST https://app.clerra.ca/oauth/token \
  -u "$CLIENT_ID:$CLIENT_SECRET" \
  -d grant_type=authorization_code \
  -d code=$CODE \
  -d redirect_uri=https://yourapp.example/callback \
  -d code_verifier=$VERIFIER

{
  "access_token": "clerra_at_…",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "clerra_rt_…",
  "scope": "clients:read filings:read"
}

• Access tokens last an hour. Get a new pair with grant_type=refresh_token; each refresh token works once (it’s replaced every time) and expires after 180 days unused. Re-using a replaced refresh token disconnects the app.
• Client authentication: HTTP Basic (client_id:client_secret) or client_id and client_secret in the form body. Form-encoded bodies, JSON accepted.
• POST /oauth/revoke with token=… disconnects your app from that firm (RFC 7009). The firm can also disconnect it any time in Settings → API.
• A connection follows the same rules as a key — paid plan, API access on — and stops if the person who approved it leaves the firm.

The API is part of paid Clerra plans. It’s checked on every single request, so these take effect immediately:

Each key carries only the scopes it was given. An endpoint needing a scope the key lacks answers 403 insufficient_scope.

• JSON in and out. Successful responses wrap the result in data; lists add next_cursor.
• Lists come oldest first by id. Pass cursor = the last id you got to continue; next_cursor is null on the last page. Add updated_since to sync only what changed.
• Ids are UUIDs. Times are ISO 8601 in UTC; dates are YYYY-MM-DD. Money is integer cents, CAD unless the invoice says otherwise.
• Every response has an X-Request-Id — quote it if you contact us. Nothing is cached (Cache-Control: no-store).
• Sample clients a firm uses to try Clerra are never returned.

GET /api/v1/clients?limit=100
→ { "data": [ … 100 clients … ], "next_cursor": "c0ffee00-…" }

GET /api/v1/clients?limit=100&cursor=c0ffee00-…
→ { "data": [ … 37 clients … ], "next_cursor": null }

120 requests a minute per key. Each response says where you stand in X-RateLimit-Limit and X-RateLimit-Remaining; over the limit you get 429 with Retry-After (seconds). Separately, 20 failed key attempts in a minute from one address blocks that address for the rest of the minute.

Base URL https://app.clerra.ca/api/v1

• GET/meCheck a key
• GET/clientsList clients
• GET/clients/{id}Get a client
• GET/filingsList filings
• GET/invoicesList invoices
• GET/jobsList jobs
• GET/leadsList leads
• POST/leadsCreate a lead
• GET/eventsList events
• GET/hooksList hooks
• POST/hooksCreate a hook
• DELETE/hooks/{id}Delete a hook

curl -X POST https://app.clerra.ca/api/v1/leads \
  -H "Authorization: Bearer $CLERRA_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Northwind Bakery Ltd.","contact_name":"Amira Haddad","email":"amira@northwind.example","stage":"new","source":"Website form"}'

curl -X POST https://app.clerra.ca/api/v1/hooks \
  -H "Authorization: Bearer $CLERRA_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://hooks.example.com/clerra","events":["filing.filed","invoice.paid"],"description":"Our CRM"}'

What a key can follow, through GET /events or webhooks. data holds only ids, statuses, amounts and dates — never a name or a message. For the details, read the record (webhooks include it).

Instead of polling, have Clerra POST to your URL as things happen. Add one in Settings → API → Webhooks, or through the API with POST /hooks (how Zapier-style integrations subscribe). The URL must be https on a public host.

{
  "id": "0b7c2f9e-5a1d-4f63-9a0e-2c8d1e4b7f10",
  "object": "event",
  "api_version": "2026-10-14",
  "type": "filing.filed",
  "occurred_at": "2027-04-28T15:42:07.113Z",
  "firm_id": "3f1e9a2b-7c4d-4e8f-a6b5-1d2c3e4f5a6b",
  "client_id": "8a6d4c2e-1b3f-4a5c-9e7d-6f8a0b1c2d3e",
  "subject_type": "filing",
  "subject_id": "5e4d3c2b-1a0f-4e9d-8c7b-6a5f4e3d2c1b",
  "data": {
    "rule_code": "t1_filing",
    "due_date": "2027-04-30",
    "filed_source": "manual"
  },
  "record": {
    "id": "5e4d3c2b-1a0f-4e9d-8c7b-6a5f4e3d2c1b",
    "client_id": "8a6d4c2e-1b3f-4a5c-9e7d-6f8a0b1c2d3e",
    "name": "T1 return",
    "rule_code": "t1_filing",
    "category": "income_tax",
    "period_start": "2026-01-01",
    "period_end": "2026-12-31",
    "due_date": "2027-04-30",
    "status": "filed",
    "filed_at": "2027-04-28T15:42:07.000Z",
    "created_at": "2026-10-14T09:00:00.000Z",
    "updated_at": "2027-04-28T15:42:07.000Z"
  }
}

Headers

Check the signature

Always verify before trusting a message: recompute the HMAC over the raw body and refuse anything older than five minutes.

import crypto from "node:crypto";

// Use the raw request body — not a re-serialised object.
export function verifyClerra(rawBody, header, secret) {
  const parts = Object.fromEntries(header.split(",").map((p) => p.split("=")));
  const t = Number(parts.t);
  if (!t || Math.abs(Date.now() / 1000 - t) > 300) return false; // replayed or stale
  const expected = crypto.createHmac("sha256", secret).update(`${t}.${rawBody}`).digest("hex");
  return parts.v1?.length === expected.length &&
    crypto.timingSafeEqual(Buffer.from(parts.v1), Buffer.from(expected));
}

import hashlib, hmac, time

def verify_clerra(raw_body: bytes, header: str, secret: str) -> bool:
    parts = dict(p.split("=", 1) for p in header.split(","))
    t = int(parts.get("t", 0))
    if abs(time.time() - t) > 300:
        return False
    expected = hmac.new(secret.encode(), f"{t}.".encode() + raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, parts.get("v1", ""))

Delivery

• Answer with any 2xx within 10 seconds. Do slow work after you’ve answered.
• Anything else — or no answer — is retried up to six more times, waiting longer each time. Redirects aren’t followed.
• Delivery is at least once and not strictly in order. Use Clerra-Event-Id to skip repeats and occurred_at to order.
• record is the record as it is when the message is sent, which can be newer than the event.
• Answer 410 Gone and Clerra stops sending to that URL. After 20 failed deliveries in a row it’s switched off and the firm is told.
• Webhooks follow the same rules as keys: nothing is sent while the firm’s API access is off or unpaid, and a hook made with a key stops when the key is revoked.

Clerra stores firm data in Canada. Anything you pull through the API or receive by webhook is then wherever your system keeps it — check that it meets your firm’s obligations before connecting it. Ask only for the scopes you need, keep keys and signing secrets in a secrets manager, and revoke anything you stop using.

Questions or a scope you’re missing? Write to support@clerra.ca.