Querying

Every resource is a uniform collection under https://{clinic}.{region}.practicehub.io/v3/api:

Request	Result
`GET /{resource}`	A page of records matching the filters
`GET /{resource}/{id}`	One record
`GET /schema`	Every resource: attributes, filterable/sortable flags, write operations, accepted input
`GET /schema/{resource}`	The same for one resource

Filters

Filter with ?attribute=operator:value. Any filterable attribute (see GET /schema/{resource}) accepts any operator; repeat an attribute to AND several conditions.

# Active patients born in the 1980s, surname starting with "Lo"
curl -g "https://your-clinic.your-region.practicehub.io/v3/api/patients?patient_status=eq:active&dob=between:1980-01-01,1989-12-31&last_name=like:Lo%25" \
  -H "Authorization: Bearer $KEY"

# Pending or arrived appointments in September, newest first
curl -g "https://your-clinic.your-region.practicehub.io/v3/api/appointments?status=in:pending,arrived&start=gte:2026-09-01%2000:00:00&start=lt:2026-10-01%2000:00:00&sort=start:desc" \
  -H "Authorization: Bearer $KEY"

Operator	Meaning	Example
`eq`	equals (also the default when no operator is given)	`status=eq:pending`, `status=pending`
`ne`	not equal	`status=ne:cancelled`
`gt` `gte` `lt` `lte`	comparison — dates, times and numbers	`start=gte:2026-09-01 00:00:00`
`like`	SQL `LIKE`; `%` is the wildcard (URL-encode it as `%25`)	`email=like:%25@example.com`
`contains`	Case-insensitive substring — no wildcards to escape	`last_name=contains:smith`
`in` `not-in`	comma-separated list	`location_id=in:81,82`
`between`	inclusive range, exactly two values	`dob=between:1980-01-01,1989-12-31`
`null` `not-null`	is (not) empty	`email=null`, `dob=not-null`

Dates and times are in the clinic’s timezone, formatted YYYY-MM-DD or YYYY-MM-DD HH:MM:SS. Attributes the API speaks in words (patients.sex: male, female, other) are filtered by those words — sex=eq:female, sex=in:male,female — never by a stored code; a word outside the set is a 422.

Filtering on an attribute the resource does not expose, or an unsortable attribute, is a 422 with the attribute named in errors — nothing is silently ignored.

Metadata filters

Your own identifiers stored in metadata are filterable on every resource with metadata[key]=operator:value — see Metadata.

Sorting

?sort=attr sorts ascending; ?sort=attr:desc descending; ?sort=last_name,first_name:asc applies one direction to several attributes. GET /schema/{resource} marks which attributes are sortable.

Pagination

Lists are paginated with page (from 1) and page_size (default and maximum 100). Every list response carries navigation links and counts:

{
  "data": [ { "id": 340, "first_name": "Ada", "metadata": {} } ],
  "links": {
    "first": "https://your-clinic.your-region.practicehub.io/v3/api/patients?page=1",
    "prev": null,
    "next": "https://your-clinic.your-region.practicehub.io/v3/api/patients?page=2"
  },
  "meta": { "current_page": 1, "per_page": 100, "total": 1342, "last_page": 14 }
}

Follow links.next until it is null; the links preserve your filters and sort. Ordering is stable — the record id is always applied as a final tiebreaker — so pages never repeat or skip rows for a fixed dataset. Records created or deleted between pages can still shift offset pages, and deep pages get slower on large tables — for syncs and exports use a cursor instead.

Cursor pagination

Add cursor= (empty) to a list request to walk it by cursor. Each page’s links.next carries an opaque token that encodes where the last row sat in the sort order; the server resumes strictly after it (an index seek, not a skip), so every page costs the same however deep you are, and a record created or deleted elsewhere in the set cannot shift or duplicate what you have already seen. Same filters, sort and page_size apply.

{
  "data": [ … ],
  "links": { "first": null, "prev": null, "next": "…/patients?cursor=eyJ2IjpbIjIwMjYtMDMtMDEgMTA6MDA6MDAiLDM0MF0sInMiOiIzZjA5In0&sort=created%3Aasc&page_size=100" },
  "meta": { "per_page": 100, "has_more": true }
}

Follow links.next until it is null. Cursors are forward-only, carry no total, and are bound to the query they were issued for — reusing one with different filters, sort or page_size is a 422.

Discovering the model

GET /schema/{resource} is the contract for that resource:

{
  "entity": "appointments",
  "attributes": {
    "id": { "filterable": true, "sortable": true },
    "start": { "filterable": true, "sortable": true },
    "status": { "filterable": true, "sortable": true }
  },
  "metadata": { "filterable": true, "syntax": "metadata[key]=op:value", "writable": true },
  "write_operations": ["create", "update", "delete"],
  "input": {
    "create": { "patient_id": { "required": true, "rules": ["required", "integer", "min:1"] } },
    "update": { "status": { "required": false, "rules": ["in:pending,arrived,cancelled,missed"] } }
  }
}

The API Reference is generated from the same source, so both always agree.

Response shape

Attributes are snake_case; ids are integers; empty values are null.
Every record includes id and a metadata object.
Only the attributes listed in GET /schema/{resource} are ever returned — new attributes may be added over time, existing ones are not renamed or removed within the current version.

Deleted records

Records deleted in PracticeHub disappear from their resource. GET /deleted_entities lists what was deleted and when, so a sync can remove its copies — filter with created=gte:{last sync} and read entity_type / entity_id.

Getting started

Working with the API

Moving from the legacy API

Filters

Metadata filters

Sorting

Discovering the model

Response shape

Deleted records

​Filters

​Metadata filters

​Sorting

​Pagination

​Cursor pagination

​Discovering the model

​Response shape

​Deleted records

Filters

Metadata filters

Sorting

Pagination

Cursor pagination

Discovering the model

Response shape

Deleted records