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&starts_at=gte:2026-09-01T00:00:00&starts_at=lt:2026-10-01T00:00:00&sort=starts_at: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	`starts_at=gte:2026-09-01T00: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 take the shape the attribute reads back in: clinic wall time with no zone (starts_at=gte:2026-09-01T00:00:00), UTC stamps with Z (updated_at=gte:2026-09-01T00:00:00Z; an offset is accepted and converted), calendar days as YYYY-MM-DD — see Dates. 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. page is capped at 10,000 — higher values are clamped to the cap and meta.current_page reports the page actually served, not the one requested; walk deeper datasets with cursor pagination 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_at%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 },
    "starts_at": { "filterable": true, "sortable": true },
    "status": { "filterable": true, "sortable": true }
  },
  "embeds": {
    "patient": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }
  },
  "detail_embeds": [],
  "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"] } }
  }
}

embeds lists the related records every read of the resource carries (a patient’s numbers[], a care plan’s billing), each as a JSON Schema fragment keyed by the attribute name. detail_embeds lists what GET /{resource}/{id} adds on top of the list shape — a care plan’s schedule phases[], billing periods[], services[], products[] and visit tracking — and an embed named in both is the fuller shape a single-record read returns. Either is [] when the resource has nothing to embed. 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 deleted_at=gte:{last sync} (not created_at, which is the deleted record’s own original stamp) and read entity_type / entity_id.

Query cookbook

Every filter, operator and field below is verified against GET /schema/{resource} and the API’s query parser — copy, paste, swap in your own ids and dates. Patients updated since a timestamp — the standard incremental-sync query:

curl -g "https://your-clinic.your-region.practicehub.io/v3/api/patients?updated_at=gte:2026-08-01T00:00:00Z&sort=updated_at" \
  -H "Authorization: Bearer $KEY"

Appointments for a practitioner this week, earliest first:

curl -g "https://your-clinic.your-region.practicehub.io/v3/api/appointments?practitioner_id=eq:81&starts_at=gte:2026-08-17T00:00:00&starts_at=lt:2026-08-24T00:00:00&sort=starts_at" \
  -H "Authorization: Bearer $KEY"

Unpaid invoices — invoices.state is paid, unpaid or void:

curl -g "https://your-clinic.your-region.practicehub.io/v3/api/invoices?state=eq:unpaid&sort=invoice_date:desc" \
  -H "Authorization: Bearer $KEY"

balance (the amount still owed) is filterable and sortable too — balance=gt:0 is the numeric equivalent if you want it alongside other conditions. Payments in a date range, by method:

curl -g "https://your-clinic.your-region.practicehub.io/v3/api/payments?payment_date=between:2026-08-01,2026-08-31&payment_method_id=eq:3&sort=payment_date" \
  -H "Authorization: Bearer $KEY"

Patients by partial name or email — like needs an explicit % wildcard (URL-encoded); contains doesn’t:

curl -g "https://your-clinic.your-region.practicehub.io/v3/api/patients?first_name=like:An%25" \
  -H "Authorization: Bearer $KEY"

curl -g "https://your-clinic.your-region.practicehub.io/v3/api/patients?email=contains:example.com" \
  -H "Authorization: Bearer $KEY"

Records carrying a given metadata key value — any resource, any key you’ve written (see Metadata):

curl -g "https://your-clinic.your-region.practicehub.io/v3/api/appointments?metadata[source]=eq:booking-widget" \
  -H "Authorization: Bearer $KEY"

Null / not-null — patients missing an email, and patients with a dob on file:

curl -g "https://your-clinic.your-region.practicehub.io/v3/api/patients?email=null" \
  -H "Authorization: Bearer $KEY"

curl -g "https://your-clinic.your-region.practicehub.io/v3/api/patients?dob=not-null" \
  -H "Authorization: Bearer $KEY"

Combining filters — repeat an attribute to AND several conditions, in for an OR within one attribute: pending or arrived appointments at either of two locations, next month:

curl -g "https://your-clinic.your-region.practicehub.io/v3/api/appointments?status=in:pending,arrived&location_id=in:81,82&starts_at=gte:2026-09-01T00:00:00&starts_at=lt:2026-10-01T00:00:00&sort=starts_at" \
  -H "Authorization: Bearer $KEY"

Counting without fetching — page_size=1 still runs the full count; read meta.total and ignore data:

curl -g "https://your-clinic.your-region.practicehub.io/v3/api/patients?patient_status=eq:active&page_size=1" \
  -H "Authorization: Bearer $KEY" | jq '.meta.total'

A full cursor walk — the robust way to pull an entire resource for a sync or export, immune to rows shifting between pages:

url="https://your-clinic.your-region.practicehub.io/v3/api/patients?cursor=&sort=created_at:asc&page_size=100"

while [ -n "$url" ] && [ "$url" != "null" ]; do
  response=$(curl -sg "$url" -H "Authorization: Bearer $KEY")
  echo "$response" | jq -c '.data[]'
  url=$(echo "$response" | jq -r '.links.next // empty')
done

Getting started

Concepts

Working with the API

Ship it

Resource guides

Importing your data

Filters

Metadata filters

Sorting

Discovering the model

Response shape

Deleted records

Query cookbook

​Filters

​Metadata filters

​Sorting

​Pagination

​Cursor pagination

​Discovering the model

​Response shape

​Deleted records

​Query cookbook

Filters

Metadata filters

Sorting

Pagination

Cursor pagination

Discovering the model

Response shape

Deleted records

Query cookbook