Skip to main content
The legacy REST API at https://{clinic}.{region}.practicehub.io/api is being retired in favour of the new PracticeHub API — see Why the new API for the reasoning. Resource names, attribute names and the filter syntax are unchanged, so for most integrations the move is: create a v1 key, change the base URL and auth header, and update how you read responses.
Legacy responses now carry Deprecation, Sunset and Link headers with the retirement date and a link to this guide. Until that date both APIs run side by side on every clinic domain, so you can migrate one call at a time.

​
1. Credentials

Legacy keys do not work on the new API. Create an API key under Developers → API Keys and send it as a Bearer token; the x-app-details header is no longer needed (the key itself identifies your integration).

​
2. Requests

Filter operators (eq, ne, gt, gte, lt, lte, like, in, not-in, between, null, not-null) and sort are identical. Two tightenings: a value with no operator prefix is now treated as eq (legacy ignored it), and filtering on an attribute the resource does not expose is a 422 (legacy did not validate it).

​
3. Responses

This is the one mechanical change every client makes: Every record additionally has an id and a metadata object.

​
4. Behaviour differences

New-API writes to patients, appointments, payments, invoices, payment_allocations and files go through the same services as the PracticeHub app, where the legacy API used a generic CRUD layer. In practice:
  • Bookings are validated as in the calendar (active patient / location / practitioner, resource at that location); status changes are real transitions with side effects (cancel, mark missed, arrive, reinstate) rather than a column update.
  • Payments must use a real, active payment method; deleting a payment or invoice voids it rather than removing the row.
  • Confirmation and reminder messaging is triggered by API bookings exactly as by staff bookings.
  • patient_payment_methods is read-only on the new API (stored cards are managed through PracticeHub). line_items is writable one line at a time (POST with invoice_id, PATCH, DELETE); PUT /invoices/{id} replaces the whole set.
  • Reference data other records point at — appointment_types, modalities, payment_methods, referral_sources — can be created and updated but not deleted through the new API (405) because other records point at them; deactivate in PracticeHub instead. practitioners, locations and practitioner_availabilities are read-only for now (the app creates them through flows with side effects a plain column write would not run); numbers and addresses are written through patients.
  • id, created and updated are server-managed on every resource; the legacy API let clients supply them.
  • These resources are not on the new API yet: clinical_notes, care_plans, packages, patient_packages, custom_forms, custom_form_responses — see Resources & roadmap for the status of each. If your integration relies on one of them, or on a legacy endpoint that is not a resource, tell us at support@practicehub.io — that feedback shapes what is added next.

​
5. Checklist

1

Create an API key

Developers → API Keys → API key. Store it server-side.
2

Change base URL and auth header

/api → /v3/api; two headers → one Bearer token.
3

Update response parsing

Read data / meta / links; expect full records back from create and update; expect 204 from delete.
4

Switch updates to PUT/PATCH

POST /{resource}/{id} no longer updates.
5

Handle errors by status

422 with errors for input, 409 for business rules, 405 for unsupported operations.
6

Test against a real account

Compare a day’s traffic side by side; the Developers → API Logs page shows every request with its status.