> ## Documentation Index
> Fetch the complete documentation index at: https://build.practicehub.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Glossary

> PracticeHub domain language as the API uses it, A to Z

Short, linkable definitions for the words this documentation set uses with a specific meaning. Each entry points at the page that goes deeper — this page is a map, not a replacement for [The data model](/concepts/data-model), [Writing](/guides/writing) or [Errors](/guides/errors).

## 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 is `https://{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](/introduction) and [Authentication](/authentication).

### Allocation

A `payment_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](/resources-guide/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](/resources-guide/appointments) and [Booking](/guides/booking).

### Appointment vs. Visit

The same thing — there's one `appointments` 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](/resources-guide/appointments).

### Arrived

One of the four statuses settable via `PATCH .../appointments/{id}` (`pending`, `arrived`, `cancelled`, `missed`). Marks the patient as arrived; `status: "pending"` un-arrives it again. See [Appointments → Lifecycle](/resources-guide/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](/guides/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](/concepts/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](/resources-guide/billing#create).

## 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](/resources#not-on-the-api-today) and [Billing](/resources-guide/billing#editing).

### 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](/concepts/dates-timezones-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](#integration-key-vs-connector). See [Connectors](/mcp/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 negative `patients.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](/resources-guide/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](/guides/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](/concepts/data-model#deleted_entities-the-tombstone-feed).

### 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 is `409` (`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](/guides/errors) and [Writing → The app's rules apply](/guides/writing#the-apps-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 gets `404 not_available` on the API until it moves. See [Authentication → Which keys an account can create](/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 via `group_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](/resources-guide/appointments#group-appointments).

## I

### Idempotency key

An `Idempotency-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](/guides/writing#retrying-safely-idempotency-keys).

### 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)](#connector-mcp). See [Authentication](/authentication) and [MCP Server](/mcp/overview#authentication).

## L

### Ledger

Not a single resource — a patient's ledger is `invoices`, `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](/resources-guide/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](/resources-guide/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](/resources-guide/appointments#resource-view-locations).

## M

### MCP server

PracticeHub's [Model Context Protocol](https://modelcontextprotocol.io) 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](/mcp/overview).

### Metadata

A `metadata` 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](/guides/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](/concepts/data-model#the-shape-of-it) and [Resources & roadmap](/resources).

## 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](/resources-guide/files-and-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](/resources-guide/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](/concepts/data-model) and [Resources & roadmap](/resources).

### 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 — except `note` — until it's unprocessed or its invoice is voided back in the app. See [Appointments → Lifecycle](/resources-guide/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](/concepts/rate-limits).

### Resource (chair/room)

Two meanings share the word on this site. In REST terms, a "resource" is a collection like `patients` or `invoices` — see [Querying](/guides/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](/resources-guide/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](/resources-guide/clinical-notes) and [Resources & roadmap](/resources#not-on-the-api-today).

## 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](/guides/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](/authentication) and [Connectors](/mcp/connectors).

## T

### Tombstone

The row `deleted_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](#deleted-entities-tombstones).

## 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](/resources-guide/billing#void).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.