Developers

API reference

Read-only access to a Cadence organization's clinical operations data. Every resource is scoped to the authenticated organization and keyed by an opaque `tokenRef`; protected health information — client names, note narratives — is never returned. Authenticate with `Authorization: Bearer <key>`; each key carries a set of read scopes (`clients`, `sessions`, `authorizations`, `notes`).

Getting started

Base URL: https://www.cadenceaba.com/api/v1. Authenticate every request with an organization API key (created in Settings → API, Practice plan):

curl https://www.cadenceaba.com/api/v1/clients \
  -H "Authorization: Bearer cad_sk_…"

Responses are JSON and de-identified — clients are keyed by an opaque tokenRef, and PHI (names, note narratives) never leaves. Requests are rate-limited per key and per IP; a 429 carries a Retry-After header. Create endpoints accept an Idempotency-Key header so retries never duplicate. The full machine-readable contract lives at /api/v1/openapi.json.

Scopes

Each key carries a least-privilege set. Read scopes gate the corresponding GET resources; write scopes are opt-in and gate create/update.

clientsGET /clients and /clients/{id}

sessionsGET /sessions

authorizationsGET /authorizations

notesGET /notes

authorizations:writePOST /authorizations and PATCH /authorizations/{id}

sessions:writeSchedule and update sessions

Endpoints

get/api/v1

Confirms the key works and lists the available resources plus the key's scopes. Requires any valid key — no specific scope.

get/api/v1/clients

Requires the `clients` scope.

get/api/v1/clients/{id}

Requires the `clients` scope.

get/api/v1/sessions

Requires the `sessions` scope.

post/api/v1/sessions

Requires the `sessions:write` scope. Creates a `scheduled` session (a calendar slot) — the client is referenced by id; no clinical capture data or direct patient identifiers are accepted.

Request body — CreateSession

Field	Type	Notes
clientIdreq	string <uuid>	A client in your organization.
scheduledStartreq	string <date-time>
scheduledEnd	string <date-time>	Must be after scheduledStart.
cptCode	string	One of: 97151, 97152, 97153, 97154, 97155, 97156, 97157, 97158.
location	string

get/api/v1/authorizations

Requires the `authorizations` scope.

post/api/v1/authorizations

Requires the `authorizations:write` scope. The client is referenced by id; no direct patient identifiers are accepted. `unitsUsed` is server-maintained and starts at 0.

Request body — CreateAuthorization

Field	Type	Notes
clientIdreq	string <uuid>	A client in your organization.
cptCodereq	string	One of: 97151, 97152, 97153, 97154, 97155, 97156, 97157, 97158.
unitsApprovedreq	integer
payer	string
authNumber	string
startDate	string <date-time>
endDate	string <date-time>
status	string	One of: active, expiring, expired, exhausted, pending.

get/api/v1/authorizations/{id}

Requires the `authorizations` scope.

patch/api/v1/authorizations/{id}

Requires the `authorizations:write` scope. Updates operational fields only — `id`, `clientId`, `cptCode`, and the server-maintained `unitsUsed` are immutable.

Request body — UpdateAuthorization

Field	Type	Notes
payer	string
authNumber	string
unitsApproved	integer
startDate	string <date-time>
endDate	string <date-time>
reauthDueAt	string <date-time>
status	string	One of: active, expiring, expired, exhausted, pending.

get/api/v1/notes

Note metadata only — the SOAP narrative is PHI and is never returned. Requires the `notes` scope.

Resource shapes

Client

Field	Type	Notes
idreq	string <uuid>
tokenRefreq	string	Opaque, de-identified client reference (never PHI).
statusreq	string	One of: active, inactive, discharged.
clinicIdreq	string <uuid>
createdAtreq	string <date-time>

Session

Field	Type	Notes
idreq	string <uuid>
clientIdreq	string <uuid>
clinicIdreq	string <uuid>
statusreq	string	One of: scheduled, in_progress, capture_complete, note_drafted, signed, billed, canceled, no_show.
cptCode	string \| null	Planned CPT code.
location	string \| null
scheduledStart	string \| null <date-time>
startedAt	string \| null <date-time>
endedAt	string \| null <date-time>
createdAtreq	string <date-time>

Authorization

Field	Type	Notes
idreq	string <uuid>
clientIdreq	string <uuid>
payer	string \| null
authNumber	string \| null
cptCodereq	string
unitsApprovedreq	integer
unitsUsedreq	integer
unitsRemainingreq	integer	Derived: unitsApproved − unitsUsed.
startDate	string \| null <date-time>
endDate	string \| null <date-time>
reauthDueAt	string \| null <date-time>
statusreq	string	One of: active, expiring, expired, exhausted, pending.
createdAtreq	string <date-time>

Note

Field	Type	Notes
idreq	string <uuid>
sessionIdreq	string <uuid>
clientIdreq	string <uuid>
statusreq	string	One of: draft, pending_signature, signed, amended.
formatreq	string
signedAt	string \| null <date-time>
signedByUserId	string \| null <uuid>
createdAtreq	string <date-time>

Questions about the API? Contact us.