API resource reference
The 22 resources the CuspFlow API exposes, which verbs and scopes each one takes, where to get the full field list, and the handful of things about the data model that will save you a wasted afternoon.
The machine-readable spec
https://cuspflow.co/api/openapi.json
OpenAPI 3.1, covering all 49 endpoints with every field, type, filter, sort key and response. Import it into Postman or Insomnia, or generate a client from it.
Use it as the authority rather than this page. It is generated from the API's own route table and column registry, and our build fails if the two disagree, so it cannot describe a field that does not exist or miss one that does. This page is the human summary.
Resources
| Resource | Verbs | Scope to read |
|---|---|---|
patients |
GET POST PATCH DELETE | patients:read |
families |
GET POST PATCH DELETE | patients:read |
patient_insurance |
GET POST PATCH DELETE | patients:read |
medical_history |
GET POST PATCH DELETE | clinical:read |
patient_journey |
GET | clinical:read |
appointments |
GET POST PATCH DELETE | appointments:read |
treatment_plans |
GET POST PATCH DELETE | treatment:read |
treatment_items |
GET | treatment:read |
billing |
GET | billing:read |
payments |
GET | billing:read |
insurance_claims |
GET | billing:read |
insurance_carriers |
GET POST PATCH DELETE | billing:read |
lab_cases |
GET | lab:read |
lab_case_procedures |
GET | lab:read |
laboratories |
GET POST PATCH DELETE | lab:read |
inventory_items |
GET POST PATCH DELETE | inventory:read |
inventory_batches |
GET | inventory:read |
inventory_transactions |
GET | inventory:read |
catalog_items |
GET POST PATCH DELETE | catalog:read |
branches |
GET | org:read |
dental_chairs |
GET | org:read |
staff |
GET | org:read |
Writing needs the matching :write scope. Deleting an appointment needs appointments:delete specifically. Writing a catalog item or an insurance carrier both need catalog:write, since carriers are a reference list maintained in Settings exactly like the catalog.
A resource listed with only GET is read-only in v1. POST to one returns 405 with Allow: GET.
Meta endpoints
| Endpoint | Scope | What it does |
|---|---|---|
GET /v1/meta/whoami |
none | Describes the calling key: clinic, bound role, scopes, branch restriction, clinic timezone, whether writes are allowed, and the rate limits |
Start every integration here. It needs no scope, so it works even when nothing else does, which makes it the right first call when you are debugging a key.
Import endpoints
| Endpoint | Scope |
|---|---|
POST /v1/imports |
imports:write |
POST /v1/imports/{id}/batches |
imports:write |
GET /v1/imports/{id} |
imports:write |
POST /v1/imports/{id}/rollback |
imports:rollback |
Both import scopes require a key bound to an Administrator. See Bulk import.
Five things about the data model
These are the ones that cost people time. None of them is guessable from the field names, which is exactly why they are here.
Invoices live in billing
The schema also contains an older invoices table. It is not exposed through the API and must not be used. Everything about money comes through billing (the invoice) and payments (what was actually received against it).
An appointment's assignee is staff_id, and it is text
Not uuid, and it carries no foreign key, which is a historical quirk rather than a design choice. Every value in it is a staff id, but the column will not stop something else being stored there, so resolve it defensively instead of casting it.
Appointments also carry dentist_id and doctor_id. Those are returned so that old records stay readable and are rejected in a request body. Do not build anything on them.
Treatment plans are different, and the similar-looking field means something real there: dentist_id on a treatment plan is the lead clinician, and the wider care team is recorded separately.
branch_id answers two different questions
On an appointment, treatment plan, payment, lab case or journey entry, branch_id records where it happened. That is the one a branch-restricted key filters on, and the one a write has to supply.
On a patient or a staff member, branch_id is a durable fact about a person: where the patient first registered, where the staff member is based for HR. It says nothing about where any given visit took place, since patients can be seen at any branch and staff cover for each other. A branch-restricted key deliberately does not filter patients or staff by it.
If you need to know which branch a patient was treated at, read it off the appointment or the treatment plan, never off the patient.
staff is a directory, not an HR feed
It returns working identity only: name, role, job roles, work email and phone, branch, active flag, hire date. Salary, hourly rate, commission rates, permissions, personal contact details, home address, date of birth and emergency contacts are not exposed in either direction. The endpoint exists so you can turn an assignee id into a name, not so you can replicate HR.
Service accounts (the invisible principals API keys are bound to) are filtered out of it, so everyone you see is a person.
Money and commission fields are withheld
treatment_items is readable but its commission snapshot is not returned, and catalog_items does not expose its commission overrides. Those fields configure staff pay, and payroll is out of v1 in both directions.
This is also why treatment_items is read-only. Changing one in the app recalculates that commission snapshot from the plan's clinician and the catalog entry, and that snapshot is what payroll pays against. A write that skipped the recalculation would leave it stale and quietly pay the wrong amount.
Fields the API never returns
- The soft-deletion timestamp. Deleted records are filtered out instead;
?include_deleted=truebrings them back as ordinary rows. - Anything to do with pay, permissions or authentication.
- Patients' portal login linkage and raw file storage paths. A bare storage path is useless without a signed URL, and exposing one only invites guessing.
- Free-form metadata blobs with no documented shape. Publishing one would freeze an undocumented structure into the contract permanently.
Still stuck? Our team is happy to help.
Email support