A
Account / clinic host & region
One clinic is one account, with its own subdomain and its own isolated database — there is no cross-account id space. Your base URL ishttps://{clinic}.{region}.practicehub.io/v3/api, where the region host is the one in the practice’s own login URL: neptune (London), mercury (Frankfurt), vulcan (Ohio), jupiter (Singapore) or apollo (Sydney). A credential only ever reaches the account it was created on. See Introduction and Authentication.
Allocation
Apayment_allocations row is what turns a payment into “paid” against a specific invoice — it ties one payment_id to one invoice_id for an amount. The invoice’s owner and the payment’s owner don’t have to be the same patient (family accounts, group care plans); allocations aren’t edited, only created and deleted. See Billing → Allocations.
Appointment type
appointment_type_id, required on every booking, drives defaults the API applies when you don’t specify them yourself — duration (via ends_at) and whether online booking is available for that type. It’s read-only reference data over the API today. See Appointments and Booking.
Appointment vs. Visit
The same thing — there’s oneappointments resource, and this documentation set uses “visit” as the plain-English word for a record in it (as in “a visit that’s already been processed”). Don’t look for a separate visits resource. See Appointments.
Arrived
One of the four statuses settable viaPATCH .../appointments/{id} (pending, arrived, cancelled, missed). Marks the patient as arrived; status: "pending" un-arrives it again. See Appointments → Lifecycle.
Availability
GET /availability is a live computation — free time left once practitioner_availabilities, existing appointments, closures, resources and the appointment type are all accounted for — not a stored record. It’s how you find a slot before booking it with POST /appointments. See Booking.
B
Balance (derived)
invoices.balance / patient_balance / third_party_balance and the matching fields on patients are computed by PracticeHub’s billing service from line items, payments and allocations — never a value any write path accepts. On patients.balance, positive means debt, negative means credit, zero means settled. See The data model → The ledger is derived, not entered.
Billable item
line_items[].billable_item_id is the required link from an invoice line into PracticeHub’s service/product catalogue: every new line must carry one. Omitting it on a line sent with an id leaves the existing link unchanged; billable_item_id: null is refused — a line can never be stripped of its link. See Billing.
C
Care plan
A read-only resource:GET /care_plans lists a patient’s plans with billing, schedules and members, and GET /care_plans/{id} carries the whole plan — phases, billing periods, services, products and visit tracking. Plans are sold, scheduled and billed in PracticeHub; the API reports them. You also see care plans indirectly: voiding an invoice reverses the visit’s care-plan usage if it was one, a care-plan invoice refuses direct edits because the care plan engine reconciles it, and patient_logs has a membership type for care-plan-related activity. See Resources & roadmap and Billing.
Clinic-local time vs. UTC stamps
Every domain date/time (appointments.starts_at/ends_at, invoice_date, payment_date, …) is the clinic’s local wall-clock time, no offset, no Z — the same time the front desk would say. Only the server-managed created_at and updated_at stamps are UTC, meant for sync cursors rather than for reading as a calendar date. GET /me returns account.timezone. See Dates, timezones and currency.
Connector (MCP)
An OAuth 2.1 connection a team member approves between an AI app (Claude, ChatGPT, …) and the MCP server. It acts as that person — their PracticeHub role, their name on the audit trail — not as the clinic in the abstract. Contrast with an integration key. See Connectors.Credit (unallocated payment)
A payment with nothing allocated to it — money the practice holds against a patient that isn’t attached to a bill yet. It shows up as a negativepatients.balance; there’s no separate “credit” resource, it’s simply the gap between what’s been paid and what’s been allocated. See Billing → Credit.
Cursor
An opaque, forward-only pagination token (cursor=) that resumes a list strictly after the last row it saw, via an index seek rather than an offset skip — every page costs the same however deep you walk, and rows created or deleted elsewhere can’t shift or duplicate what you’ve already read. A cursor is bound to the filters, sort and page_size it was issued for. See Querying → Cursor pagination.
D
Deleted entities (tombstones)
deleted_entities is the read-only resource recording what disappeared and when — entity_type, entity_id, patient_id where applicable, and timestamps — for patients and appointments deleted anywhere in PracticeHub (API, app, or a background job). A sync asks “what’s gone since I last looked” with GET /deleted_entities?deleted_at=gte:{last sync} instead of diffing full listings. See The data model → deleted_entities.
Domain refusal (409 / 422 with a code)
Because writes follow the same business rules as the PracticeHub app, a rejection is never a bare failure: a business rule refusing the change is409 (group_full, appointment_rule, billing_rule, …), invalid input is 422 with errors keyed by attribute. Both carry a stable code you branch on — message is for showing to a human, code is the contract. See Errors and Writing → The app’s rules apply.
F
PracticeHub 2.0 account
The API, MCP server and AI connectors are part of PracticeHub 2.0. An account gets PracticeHub API keys, connectors and API Logs once it’s on 2.0; an account not yet on 2.0 gets404 not_available on the API until it moves. See Authentication → Which keys an account can create.
G
Group appointment & master
A group session is one master appointment (time, place, practitioner, capacity) with attendee rows hanging off it viagroup_master_id. Joining is POST /appointments with patient_id and group_master_id; capacity is counted live against pending/arrived/processed attendees, and a full session refuses with 409 group_full. See Appointments → Group appointments.
I
Idempotency key
AnIdempotency-Key header (any unique string, up to 255 characters) on a POST. A repeat with the same key and same body within 24 hours replays the original response instead of creating a duplicate; the same key with a different body is 422; a duplicate sent while the first is still running is 409 idempotency_key_in_flight. See Writing → Retrying safely.
Integration key vs. connector
An API key is one integration: a bearer credential belonging to no person, used by headless agents and automations on the REST API (it is not accepted on the MCP server), logged as that integration (“Created via API: Booking widget”). A connector is an OAuth grant a team member approves for an AI app, acting as them with their role’s permissions — see Connector (MCP). See Authentication and MCP Server.L
Ledger
Not a single resource — a patient’s ledger isinvoices, payments and payment_allocations filtered by patient_id and read together. PracticeHub recomputes every derived balance from those three whenever one of them changes. See Billing → The shape of the ledger.
Line item
A row on an invoice (line_items), each with description, a whole-number quantity (≥ 1) and a 2-decimal, sign-free price — a negative price is how a discount or credit line is written. Every invoice needs at least one, and the last one can’t be removed (void the invoice instead). Reconciled by id the same way patients.numbers[] is. See Billing → Invoices.
Location calendar view (resource vs. practitioner)
locations.calendar_view: 1 is resource-view — appointments sit in a room, table or bench and need a real resource_id from GET /resources?location_id=…; 2 is practitioner-view — the practitioner’s own column is the booking, and resource_id must be left out. See Appointments → Resource-view locations.
M
MCP server
PracticeHub’s Model Context Protocol server at/v3/api/mcp. An AI client connects with OAuth (a team member approves it — API keys are not accepted), discovers every resource with list_entity_types, then reads under the same rules as the REST API — same audit trail, same permissions. Read-only during the limited rollout; write tools come later. See MCP Server.
Metadata
Ametadata object on every record: up to 50 of your own key/value pairs (strings, numbers or booleans), merged on write — keys you send are set, keys you omit are untouched, null removes a key — and filterable on every resource with metadata[key]=operator:value. PracticeHub never reads or displays it. See Metadata.
Modality
modalities is a small reference resource (id, name, active) naming the clinical discipline a practitioner is categorised under (practitioners.modality_id). Read-only over the API today, created and edited in PracticeHub’s Settings. See The data model → Reference data and Resources & roadmap.
P
Patient log
patient_logs is the patient’s activity timeline — the same feed the Activity Log tab renders — with seven types (note, comms, financial, appt, membership, system, historical). Entries written through the API are stamped source: api automatically, and a file can attach to one via file_type=patient_log + patient_log_id. See Files and patient history → Patient logs.
Payment method vs. special payment types (negative ids)
payment_method_id on a payment you record is a real, active method of the account from GET /payment_methods (a positive id). PracticeHub’s own pseudo-types sit at negative ids — -1 Refund, -2 Credit, -3/-4 Transfers, -5 Write-off, -10 Reward Points Credit, -20 Card on File, -21 Direct Debit — and you will read them on payments PracticeHub wrote, but none can be recorded through the API (422 payment_method_not_recordable); provider-collected methods are refused too, because no charge is made through this endpoint. See Billing → Payments.
Practitioner
practitioners is the read-only reference resource that appointments, invoices and payments point at via practitioner_id. It’s created and edited in PracticeHub because creating one has side effects (team member + user account + licence) a plain write would skip. See The data model and Resources & roadmap.
Processed (app-only state)
The one appointment status the API cannot set or clear directly — it means “billed through the app’s own checkout flow.” Once a visit is processed, nothing (reschedule, retype, cancel, delete) can touch it — exceptnote — until it’s unprocessed or its invoice is voided back in the app. See Appointments → Lifecycle.
R
Rate limit bucket
120 requests per minute, keyed to the account per surface: every API key shares one REST bucket, every connector shares a separate MCP bucket. One integration’s burst spends its surface’s whole budget for the account, so pace accordingly. An unauthenticated request is limited to 2 per minute per IP address instead. See Rate limits.Resource (chair/room)
Two meanings share the word on this site. In REST terms, a “resource” is a collection likepatients or invoices — see Querying. The resources resource is the narrower, physical sense: a chair, room, table or bench that a resource-view location books appointments against via resource_id. See Appointments → Resource-view locations.
Revision
Readable, not yet writable. A clinical note (clinical_notes) carries its revision lineage on every read — revision_number, is_current (always true here, since only current revisions are ever served), previous_revision_id, revised_by_uid. A note created through the API always starts a fresh chain as revision 1; there’s no way to write a revision onto an existing note yet, so an edit made in PracticeHub itself is the only way a note’s revision_number advances. custom_form_responses (non-note form submissions) remains Not yet on the roadmap. See Clinical notes and Resources & roadmap.
S
Schema endpoint
GET /schema (every resource) and GET /schema/{resource} (one resource) return the machine-readable contract: every attribute with its filterable/sortable flags, the related records a read embeds (embeds, plus detail_embeds for what a single-record read adds), the write_operations a resource supports, and the exact validation rules per attribute per operation. The OpenAPI reference on this site is generated from the same source. See Querying → Discovering the model.
Scope (read/write key)
An API key carries one of two scopes chosen at creation —read (every GET; any write is 403 key_read_only) or read and write. An OAuth connector token instead carries a fixed scope, mcp:use, and is governed by the approving team member’s PracticeHub role rather than a read/write choice. See Authentication and Connectors.
T
Tombstone
The rowdeleted_entities leaves behind for a record that’s been deleted — its type, its id, and a few identifying fields — once the record itself has disappeared from its own resource. See Deleted entities.
V
Void
The only way an invoice goes away:DELETE /invoices/{id} releases its active allocations, optionally voids payments left with nothing else to pay (?void_payments=true), clears its care-plan billing links, and resets the appointment it was raised from to unprocessed — all in one transaction. Voiding an already-void invoice is 409. Deleting a payment voids it too — soft-deleted, its allocations released. See Billing → Void.