API & webhooks
A legacy system that never gave you custom reports is why this exists, and it is the honest replacement: read your own data with your own tools. Everything here is set up at Lab → API & webhooks. Keys Create a key per integration and give it only the scopes it needs — `cases:read`, `cases:write`, `invoices:read`, `directory:read`. The key is shown once; we store a one-way hash and genuinely cannot show it again, so if it is lost, make a new one and revoke the old. Revoking takes effect on the next request. Each key’s row shows when it was last used, which is the quickest way to find one nothing is using any more. Set expires in N days for a key you are handing out temporarily — a contractor, a trial integration. Leave it blank and the key never expires. A key can never carry more access than the person who made it. If you do not have access to invoices yourself, `invoices:read` is not offered and asking for it is refused by name rather than quietly dropped — a key silently missing a scope fails later, inside someone else’s integration. Calling the API Base URL `https://api.casetop.io/api/public/v1`. Send the key as a bearer token: ```
curl https://api.casetop.io/api/public/v1/cases?limit=50 \
-H "Authorization: Bearer ct_live_..."
``` Start with `GET /me` — it returns your lab and the scopes on the key, which confirms you pasted the right secret. Then: `GET /cases` (filter by `stage`, `dentist_id`, `account_id`, `updated_since`), `GET /cases/{id}` (with its units and stage history), `POST /cases`, `GET /invoices` and `GET /invoices/{id}` (with line items), `GET /dentists`, `GET /accounts`, `GET /products`. Paging Lists return `{ data, has_more, next_cursor }`. Pass `next_cursor` back as `?cursor=` until `has_more` is false. It is cursor paging rather than page numbers on purpose: a page boundary stays correct while new cases arrive, so a job walking 100,000 cases never skips one. Up to 200 rows per page; 120 requests a minute per key. Creating a case `POST /cases` needs a `dentist_id` and takes the same fields the app does — `patient_ref`, `restoration_type`, `material`, `shade`, `tooth_numbers`, `due_date`, `notes`, and `units` for a multi-unit case. It runs the same path as typing one in: your case numbering, your assignment rules, your pipeline, the credit-hold check and the AI pre-flight all apply. A case created this way is an ordinary case on your board. Webhooks Add an https endpoint and we POST JSON to it when something happens. Events: `case.created`, `case.stage_changed`, `case.shipped`, `case.on_hold`, `intake.received`, `invoice.issued`, `invoice.paid`, and `audit.recorded`. Tick none to receive all of them except `audit.recorded`, which you must tick explicitly — it is far higher volume and carries sign-in IPs, so it never arrives at an endpoint that did not ask for it. `case.shipped` is sent in addition to `case.stage_changed`, so you can watch for “work is done” without knowing your lab’s stage names. A scan that advances a case fires the same events as a button press, so a lab running its floor on scanners needs no special handling. Streaming the audit log to a SIEM Subscribe an endpoint to `audit.recorded` and every audit entry is POSTed as it happens — sign-ins, invites, role and settings changes, API keys created or revoked, webhook endpoints added, edited, deleted or re-secreted, and the work itself (cases created, moved and deleted; doctors and practices edited; invoices issued and voided). Each payload carries the action, the actor (email, role, IP, user agent), the target and the details of what changed. Deliveries are signed and retried like any other webhook, so an ingest outage does not lose entries. New audit actions join the feed automatically — you never have to re-subscribe when Casetop starts recording something new. Prefer a pull? Lab → Audit log → Export CSV gives you the same entries as a file. The body is `{ "event": …, "created_at": …, "data": { … } }`. Reply with any 2xx; anything else (or a timeout past 10 seconds) is a failure and we retry after 1 minute, 5, 30, 2 hours and 6 hours before giving up on that delivery — about nine hours, so an afternoon of downtime at your end loses nothing. An endpoint that fails 25 deliveries in a row is switched off, and we email you when that happens — naming the endpoint and quoting what the far end answered, so you hear it from us rather than from whatever stopped arriving. The page says why too. Set whatever header it needs, press Send test until it answers 200, then turn it back on; turning it on clears the failure count. Events flow again from that moment — the ones that already failed are not replayed. Send test delivers a sample payload and shows you the exact response. Verifying the signature Every request carries `X-Casetop-Signature: t=<unix seconds>,v1=<hex>`, where the hex is HMAC-SHA256 of `"<t>.<raw body>"` using that endpoint’s signing secret. Sign the raw body, before any JSON parsing. Reject anything where `t` is more than a few minutes old — the timestamp is inside the signed material precisely so a captured request cannot be replayed later. Compare with a constant-time function, not `==`. Rotating the secret takes effect immediately, so update your end first. ```
import hmac, hashlib
ts, sig = [p.split("=", 1)[1] for p in header.split(",")]
expected = hmac.new(secret.encode(), f"{ts}.{body}".encode(), hashlib.sha256).hexdigest()
assert hmac.compare_digest(expected, sig)
``` If your endpoint needs to authenticate us Our signature proves a payload came from us and was not altered. It does not sign us IN, and plenty of receivers — Cursor automations, n8n, most internal services — reject an unauthenticated POST outright. On Lab → API & webhooks, each endpoint takes one optional request header: put `Authorization` in the name box and `Bearer <your key>` in the value box. We send it on every delivery alongside the signature. The value is stored encrypted and is never shown again — the endpoint lists the header NAME so you can see one is set, and you replace it by saving a new value. Headers we set ourselves (`Content-Type`, and anything starting `X-Casetop-`) are refused with a message rather than silently ignored, so the signature is always one we computed. When deliveries fail A failed delivery is retried six times over about nine hours. The count on the endpoint is attempts, not separate events — one event against a dead URL burns six of them. After 25 failed attempts in a row we switch the endpoint off and say so on the page; fix it and turn it back on, which also resets the count. Putting your lab's data into HubSpot (or any CRM) A lab running a marketing push at group practices wants its own case and revenue history beside the pipeline, and there is no plugin to install — the API and webhooks are the integration, and they work with whatever CRM you use. The pull. A nightly job reads `/accounts` and `/invoices` with a `directory:read` + `invoices:read` key and upserts each practice as a HubSpot *company*, keyed on your own account code so it matches rather than duplicating. That gives every company record its real order history and balance without anybody exporting a spreadsheet. The push. Subscribe a webhook endpoint to `invoice.paid` and `case.created` and let it write a HubSpot timeline event or bump a property. Signed, retried for about nine hours if your end is down, and you can give the endpoint an `Authorization` header if your middleware needs one. What to sync, in practice: the practice as a company, last-order date and units so a stalled customer is visible in the CRM, and the product mix (Office → Accounts → *What they buy*) if you want a sales rep to see what a practice has never ordered from you without opening Casetop. No developer required for the read side: point an AI coding tool at the API with your key and describe the report you want. One lab does exactly that in place of a report builder. What is not here yet The public API is read-mostly today: you can create cases, and everything else is read. Editing invoices, advancing stages and managing the catalog go through the app. If you need one of those, tell us what you are building — that is how this list gets shorter.
This page uses JavaScript to render its full interactive content. Enable JavaScript, or continue reading at
https://casetop.io/docs/api-and-webhooks.