Centaur Software APIs

The Dental API provides secure, programmatic access to dental practice management data. Built for third-party integrators, healthcare platforms, and custom applications, it lets you integrate with practice data while maintaining strict security and privacy controls.

Connectivity beyond the cloud
-----------------------------

While designed for Dental4Web (cloud) and MediaWeb PACS, this API is not limited to cloud deployments. Practices running **Dental4Windows on-premise** can also connect via secure data pipelines provided by [Halo Connect](https://haloconnect.io). This gives you a unified API experience regardless of whether your practice data resides in the cloud or on local servers.

What you can do
---------------

The API provides read access to core practice data across five resource domains. Write access is available for three core domains.

<Table style="width:100%;min-width:100%" colSizes='["270px","630px"]' isHeaderAdded='true' tableHeader='[{"id":"8063fd5f-a16d-4fa3-99ae-00d682bbe6a3","title":"Resource domain"},{"id":"e564492f-1455-4dbc-8ef2-fc82e46a7548","title":"Description"}]'>
  <table-row>
    <table-cell><p class="slate-p "><strong class="slate-bold">Patient Records</strong></p></table-cell>
    <table-cell><p class="slate-p ">Read demographics, contact details, health fund information, and recall schedules. Create and update patient records.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><strong class="slate-bold">Appointments</strong></p></table-cell>
    <table-cell><p class="slate-p ">Read scheduled, confirmed, cancelled, and attended appointments with full status tracking. Create, update, cancel and reschedule appointments.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><strong class="slate-bold">Financial Transactions</strong></p></table-cell>
    <table-cell><p class="slate-p ">Invoices, payments, discounts, refunds, and health fund rebates</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><strong class="slate-bold">Treatments &amp; Clinical</strong></p></table-cell>
    <table-cell><p class="slate-p ">Read completed treatments, treatment plans, and clinical notes. Create clinical notes.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><strong class="slate-bold">Dental Imaging</strong></p></table-cell>
    <table-cell><p class="slate-p ">DICOM images via MediaWeb PACS integration (online deployments only)</p></table-cell>
  </table-row>
</Table>

Key features
------------

### Multi-organisation access

Access data from multiple dental practices using a single API key. Each request specifies the target organisation via the `org-id` header, which ensures complete data isolation between organisations.

### FHIR R4 support

Selected endpoints support HL7® FHIR® R4 output for healthcare interoperability. Add `/fhir/` to supported endpoint paths to receive data formatted as FHIR resources. See FHIR Capabilities for details.

### Incremental sync

Use the `mode=1` parameter to filter by modification timestamp instead of business date. This enables efficient delta synchronisation: you fetch only records that have changed since your last sync.

### Flexible filtering

All list endpoints support filtering by patient, practitioner, location, and date range. Use the `include` parameter to embed related resources and reduce API calls.

API access
----------

<Table style="width:100%;min-width:100%" colSizes='["270px","630px"]' isHeaderAdded='true' tableHeader='[{"id":"9200ea78-7f87-426e-af59-ba8fd055418b","title":"Title"},{"id":"ef91bc1c-9632-4ce7-b19b-74d161e7b793","title":"Details"}]'>
  <table-row>
    <table-cell><p class="slate-p "><strong class="slate-bold">Base URL</strong></p></table-cell>
    <table-cell><p class="slate-p "><a href="https://api-uat.dental4web.com.au" target="_self">https://api-uat.dental4web.com.au</a></p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><strong class="slate-bold">Protocol</strong></p></table-cell>
    <table-cell><p class="slate-p ">HTTPS only (TLS 1.2+)</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><strong class="slate-bold">Format</strong></p></table-cell>
    <table-cell><p class="slate-p ">JSON (with optional FHIR R4 output)</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><strong class="slate-bold">Authentication</strong></p></table-cell>
    <table-cell><p class="slate-p ">API key + organisation ID headers</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><strong class="slate-bold">Rate Limit</strong></p></table-cell>
    <table-cell><p class="slate-p ">10,000 requests per day per integrator, plus per-minute limits: see <a href="/rate-limits">Rate limits</a>. Contact us if you need a higher daily limit.</p></table-cell>
  </table-row>
</Table>

Current capabilities
--------------------

<Table style="width:100%;min-width:100%" colSizes='["270px","630px"]' isHeaderAdded='true' tableHeader='[{"id":"34fad0e6-67d0-4597-a2d4-772fbbdcbeec","title":"Capability"},{"id":"cefb6b77-1e59-4f1d-a2c9-7450aad057ff","title":"Status"}]'>
  <table-row>
    <table-cell><p class="slate-p ">Read patient demographics &amp; recalls</p></table-cell>
    <table-cell><p class="slate-p ">✅ Available</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p ">Read patient extended (custom fields)</p></table-cell>
    <table-cell><p class="slate-p ">✅ Available</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p ">Write access (patients, appointments and clinical notes)</p></table-cell>
    <table-cell><p class="slate-p ">✅ Available</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p ">Read appointments (incl. cancelled)</p></table-cell>
    <table-cell><p class="slate-p ">✅ Available</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p ">Find available appointment slots</p></table-cell>
    <table-cell><p class="slate-p ">✅ Available</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p ">Read treatments, treatment plans, clinical notes</p></table-cell>
    <table-cell><p class="slate-p ">✅ Available</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p ">Read financial transactions &amp; receipts</p></table-cell>
    <table-cell><p class="slate-p ">✅ Available</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p ">Read reference data (practitioners, locations, books, items, payment types, classes, cancel reasons, slot types, titles, users, recalls)</p></table-cell>
    <table-cell><p class="slate-p ">✅ Available</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p ">Read DICOM images &amp; metadata via MediaWeb PACS</p></table-cell>
    <table-cell><p class="slate-p ">✅ Available</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p ">FHIR R4 reads (Patient, Appointment, Practitioner, Location, Observation, Procedure)</p></table-cell>
    <table-cell><p class="slate-p ">✅ Available</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p ">Create / update Patient</p></table-cell>
    <table-cell><p class="slate-p ">✅ Available</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p ">Create / update Appointment, Cancel, Reschedule</p></table-cell>
    <table-cell><p class="slate-p ">✅ Available</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p ">Create Clinical Note</p></table-cell>
    <table-cell><p class="slate-p ">✅ Available</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p ">OAuth 2.0 authentication and authorisation</p></table-cell>
    <table-cell><p class="slate-p ">🔜 Planned for future releases</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p ">Webhook notifications</p></table-cell>
    <table-cell><p class="slate-p ">🔜 Planned for future releases</p></table-cell>
  </table-row>
</Table>

Prerequisites
-------------

Before integrating with the Dental API, you should have:

*   **Technical knowledge**: Understanding of REST APIs, HTTP methods, and JSON format
    
*   **Healthcare context**: Familiarity with dental practice workflows and healthcare data standards
    
*   **Credentials**: A valid API key and organisation ID(s) from Centaur Software
    

Getting help
------------

*   **Integration support**: Contact [Centaur Software](mailto:dentalapi@centaursoftware.com) for API access and integration assistance
    
*   **Documentation feedback**: Report issues or suggest improvements via [dentalapi@centaursoftware.com](mailto:dentalapi@centaursoftware.com)
    

Quick links
-----------

<Table style="width:100%;min-width:100%" colSizes='["270px","630px"]' isHeaderAdded='true' tableHeader='[{"id":"2cd77fdc-0a8d-4b2f-95da-01f17765f604","title":"I want to..."},{"id":"40b3976a-bded-4476-86b2-cdbbee13fdc6","title":"Go to..."}]'>
  <table-row>
    <table-cell><p class="slate-p ">Set up authentication</p></table-cell>
    <table-cell><p class="slate-p "><a href="/getting-started" target="_self">Getting Started</a></p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p ">Understand the response format</p></table-cell>
    <table-cell><p class="slate-p "><a href="/api-response-formats" target="_self">API Response Formats</a></p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p ">Find the right endpoint for my use case</p></table-cell>
    <table-cell><p class="slate-p "><a href="/find-your-use-case" target="_self">Find Your Use Case</a></p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p ">Learn about FHIR support</p></table-cell>
    <table-cell><p class="slate-p "><a href="/fhir-capabilities" target="_self">FHIR Capabilities</a></p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p ">See all available endpoints</p></table-cell>
    <table-cell><p class="slate-p "><a href="/appointment-resources" target="_self">Appointment Resources</a>, <a href="/patient-resources" target="_self">Patient Resources</a>, <a href="/financial-resources" target="_self">Financial Resources</a>, <a href="/treatment-and-clinical-resources" target="_self">Treatment Resources</a>, <a href="/reference-data-resources" target="_self">Reference Data</a></p></table-cell>
  </table-row>
</Table>

Introduction to Dental API

<Steps attributes='{"style":{"width":"100%","minWidth":"100%"}}'>
<Step stepNumber="1" title="Obtain credentials"><p><span style="background-color:transparent;color:#434343">To gain API access, an integrator must contact </span><a href="mailto:dentalapi@centaursoftware.com" target="_self">Centaur Software</a><span style="background-color:transparent;color:#434343"> to set up an integration account. This request should state the intended use case, the scope of required data, and the organisation(s) for which access is being sought.</span></p><p><span style="background-color:transparent;color:#434343">Once the account is created, the integrator will be provided with an API key and given access to Dental4Web/Dental4Windows organisations. E</span>very request must carry an <code class="slate-code">org-id</code> header identifying the organisation<span style="background-color:transparent;color:#434343">.</span></p></Step><Step stepNumber="2" title="Add authentication"><p><span style="background-color:transparent;color:#434343">All HTTP requests should include the following headers. </span><span style="background-color:transparent;color:#434343"><code class="slate-code">x-api-key</code> and <code class="slate-code">org-id</code> are required; <code class="slate-code">Accept</code> is recommended but not currently enforced:</span></p>*   x-api-key<p><span style="background-color:transparent;color:#434343"><em class="slate-italic">This is the integrator’s API key.</em></span></p>*   org-id<p><span style="background-color:transparent;color:#434343">The organisation ID identifies a specific organisation within Dental4Web/Dental4Windows. Note that an integrator's API key can be used to access multiple organisations, so both the organisation ID and the API key are required for all requests.</span></p><p><span style="background-color:transparent;color:#434343">The API token grants access only to the data of the mapped org-id. Any attempt to retrieve information for an organisation other than the current one will be rejected by the API.</span></p>*   Accept: application/json<p><span style="background-color:transparent;color:#434343"><em class="slate-italic">Recommended, not required. All responses are JSON regardless of this header; sending </em></span><span style="background-color:transparent;color:#434343"><em class="slate-italic"><code class="slate-code">Accept: application/json</code></em></span><span style="background-color:transparent;color:#434343"><em class="slate-italic"> is recommended for forward compatibility, but it is not currently enforced: requests without it, or with a different value, still succeed.</em></span></p></Step><Step stepNumber="3" title="Try it out"><p><span style="background-color:transparent;color:#434343">Once you have all the required details, you can test your connection using the curl example below.</span></p><CodeBlock attributes='{"isFitToPage":true,"style":{},"lang":"plainText","label":"Plain text"}'>
  <CodeLine>curl -X GET "https://api-uat.dental4web.com.au/api/v1/practitioners" \</CodeLine>
  <CodeLine>        -H "org-id: YOUR_ORG_ID" \</CodeLine>
  <CodeLine>        -H "x-api-key: YOUR_API_KEY" \</CodeLine>
  <CodeLine>        -H "Accept: application/json" </CodeLine>
</CodeBlock>
</Step></Steps>

### Troubleshooting your first call

<Table style="width:100%;min-width:100%" colSizes='["180px","135px","585px"]' isHeaderAdded='true' tableHeader='[{"id":"b4ff02d6-c8c5-4302-963d-c80c4e0f5a30","title":"Error"},{"id":"61de544a-d3f1-4097-bcc4-42562b618305","title":"Cause"},{"id":"071a0c42-ff7f-41ba-b29c-4f7ee5ac4323","title":"Fix"}]'>
  <table-row>
    <table-cell><p class="slate-p ">HTTP 403</p></table-cell>
    <table-cell><p class="slate-p ">Missing or invalid <code class="slate-code">x-api-key</code> header</p></table-cell>
    <table-cell><p class="slate-p ">Check the header is present and the key matches Sandbox</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p ">HTTP 400 "Missing Organisation ID"</p></table-cell>
    <table-cell><p class="slate-p ">Missing <code class="slate-code">org-id</code> header</p></table-cell>
    <table-cell><p class="slate-p ">Add <code class="slate-code">org-id: Sandbox</code></p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p ">HTTP 400</p></table-cell>
    <table-cell><p class="slate-p ">API key valid but not authorised for this organisation</p></table-cell>
    <table-cell><p class="slate-p ">Contact <a href="mailto:dentalapi@centaursoftware.com" target="_self">Centaur Software</a> to map your key to the org</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p ">HTTP 429</p></table-cell>
    <table-cell><p class="slate-p ">Rate limit exceeded</p></table-cell>
    <table-cell><p class="slate-p ">Wait the seconds indicated in <code class="slate-code">retry_after_seconds</code> (per-integrator limit, hit first in most cases) or <code class="slate-code">retry_after</code> (per-organisation limit) and try again. Check <code class="slate-code">support_code</code> to tell which layer applied. See <a href="/rate-limits">Rate Limits</a>.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p ">Timeout</p></table-cell>
    <table-cell><p class="slate-p ">Slow connection or a temporary service slowdown</p></table-cell>
    <table-cell><p class="slate-p ">Increase client timeout to 60 s and retry</p></table-cell>
  </table-row>
</Table>

Getting Started

This page tracks customer-facing changes to the Dental API: new endpoints, new parameters, new response fields, and changes to existing behaviour. Entries are grouped by version, newest first. The version number for each entry is the Dental API data model version; use [GET Data Model Version](/admin-resources/get-data-model-version) to check which version an organisation is currently running.

V18
---

### Added

*   **GET Patients Lite**: a lightweight, multi-field patient search returning up to 7 core fields, for when you don't need the full patient record.
    

### Updated

*   **GET Patient Extended By ID**: added a `patient_category` field, the practice-defined category name for the patient. Not the same thing as `patient_status`: a patient can carry any category regardless of active/inactive status.
    
*   **GET Appointment Slots**: `slotmode` now supports two additional modes (all-presets-only, online-presets-only), and slot rows now include a `slot_type_id` field linking back to GET Slot Types.
    

V17
---

### Added

*   **GET Appointments**: new `deleted` parameter to include deleted appointments in results (off by default), with a new `is_deleted` field on each row.
    

### Updated

*   **GET Debtors**: added `has_line_items`, so you can tell upfront whether a debtor row has itemised detail available via GET Invoice Details before calling it.
    

V16
---

### Added

*   **GET Third Parties**: list of configured third-party payer accounts (health funds and other external payers).
    
*   **GET Debtors**: practice-wide outstanding-debtor list.
    
*   **GET Patient Balance**: per-patient outstanding balance summary.
    
*   **GET Invoice Details**: itemised line-item detail for a single invoice.
    

### Updated

*   **GET Financials**: added a `trans_type` filter (invoice, discount, refund, payment) and corrected several edge cases in how deposits and mixed health-fund/patient payments were split.
    
*   **GET Receipts**: added an `is_insurance` flag on each payment line.
    

V15
---

### Fixed

*   **GET Financials**: corrected patient filtering on shared receipts, so payments now return correctly for a given patient regardless of whether the receipt is sole or shared with a family member.
    

### Updated

*   **GET Cancelled Appointments**: added a `cancel_reason_id` field.
    
*   **GET Items** and **GET Users**: minor field-naming corrections for consistency (`ada_code`, `first_name`).
    

V14
---

No public-facing changes. This version optimised internal logic for speed improvements.

V13
---

### Fixed

*   **POST Appointment (update)**: guarded against a data-integrity edge case that could otherwise silently corrupt an appointment record.
    
*   **POST Appointment Cancel**: now correctly rejects cancelling an appointment that's already been marked as attended.
    

### Breaking changes

*   **GET Patients, GET Patients Extended**: the date-of-birth filter parameter was renamed from `dob` to `date_of_birth` for consistency with patient create/update.
    

V12
---

### Added

*   Write access: create, update, cancel and reschedule appointments.
    
*   Create and update patients.
    
*   Find available appointment slots.
    
*   New reference-data endpoints: cancellation reasons, appointment classes, slot types, and patient titles.
    

V11
---

### Fixed

*   **GET Cancelled Appointments**: fixed date-window filtering so it correctly matches on appointment date or cancellation date depending on the `mode` parameter.
    

### Added

*   **GET Patients, GET Patients Extended**: added an exact date-of-birth filter.
    

V10
---

### Updated

*   **GET Locations**: added address, phone and email fields, and improved FHIR compatibility.
    

V9
---

### Fixed

*   **GET Patients, GET Patients Extended**: mobile number search is now space-insensitive (matches regardless of how the number is formatted).
    

V8
---

### Added

*   **GET Patients, GET Patients Extended**: added email and mobile number search filters, and support for delta/incremental sync by modification timestamp.
    

V7
---

### Added

*   **GET Patients Extended**: new endpoint providing extended patient information: family role, ethnicity, work address, communication preferences, and custom fields.
    
*   **GET Appointment Books, GET Users, GET Practitioners**: added a location filter.
    

V1 to V6, initial release
-------------------------

Initial launch of the Dental API's read-only endpoint surface, covering patients, appointments, treatments, and reference data.


Changelog

All requests to Dental API require authentication via API keys. Authentication credentials are provided when your integration account is created by Centaur Software.

Required headers
----------------

Every API request should include these headers. <code class="slate-code">x-api-key</code> and <code class="slate-code">org-id</code> are required; <code class="slate-code">Accept</code> is recommended but not currently enforced:

<Table style="width:100%;min-width:100%" colSizes='["180px","135px","585px"]' isHeaderAdded='true' tableHeader='[{"id":"fc4278ce-8082-4542-ae52-12e51efac4ea","title":"Header"},{"id":"7af9b7b5-b390-43d6-9a99-326bcbc02d4b","title":"Value"},{"id":"cda80c46-25c8-4b40-a9b4-de3868a69caf","title":"Description"}]'>
  <table-row>
    <table-cell><p class="slate-p "><span style="color:#434343"><code class="slate-code">x-api-key</code></span></p></table-cell>
    <table-cell><p class="slate-p ">Your API key</p></table-cell>
    <table-cell><p class="slate-p ">Authenticates the integrator. Provided by Centaur Software during account setup.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><span style="color:#434343"><code class="slate-code">org-id</code></span></p></table-cell>
    <table-cell><p class="slate-p ">Organisation ID</p></table-cell>
    <table-cell><p class="slate-p ">Identifies which Dental4Web/Dental4Windows organisation to access. A single API key can be mapped to multiple organisations.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">Accept</code></p></table-cell>
    <table-cell><p class="slate-p "><code class="slate-code">application/json</code></p></table-cell>
    <table-cell><p class="slate-p ">All responses are JSON regardless of this header. Sending it is recommended for forward compatibility, but it is not currently enforced: requests without it, or with a different value, still succeed.</p></table-cell>
  </table-row>
</Table>

Multi-organisation model
------------------------

Dental API isolates each organisation’s data, so a single API key can be authorised for several organisations without their data ever mixing:

*   **One API key, multiple organisations**: A single integrator API key can be authorised to access data from multiple dental practices.
    
*   **Organisation isolation**: The `org-id` header in each request determines which organisation’s data is returned. The API strictly enforces organisation isolation; you cannot access data for an organisation your key isn’t mapped to.
    
*   **Request scoping**: All data returned is scoped to the specified organisation only.
    

Sandbox environment
-------------------

A sandbox environment is available for development and testing:

*   **Sandbox org-id**: Use `Sandbox` as your `org-id` value to route requests to the sandbox environment
    
*   **Like-for-like**: The sandbox environment mirrors production functionality (endpoints, response shapes, business rules). Rate limiting is the one exception: Sandbox currently runs with an elevated per-organisation override for test traffic, so it does not represent production rate-limit thresholds. See [Rate Limits](/rate-limits) for details
    
*   **Test data**: Contains realistic sample patient, appointment, and treatment records
    
*   **Safe testing**: Ideal for developing and testing integrations before switching to production credentials
    

### Example sandbox request

<CodeBlock attributes='{"isFitToPage":true,"style":{},"lang":"plainText","label":"Plain text"}'>
  <CodeLine>curl -X GET "https://api-uat.dental4web.com.au/api/v1/practitioners" \</CodeLine>
  <CodeLine>        -H "org-id: Sandbox" \</CodeLine>
  <CodeLine>        -H "x-api-key: YOUR_API_KEY" \</CodeLine>
  <CodeLine>        -H "Accept: application/json" </CodeLine>
</CodeBlock>

Security best practices
-----------------------

*   **Keep credentials confidential**: Never embed API keys in client-side code, mobile apps, or public repositories
    
*   **Use HTTPS only**: All API traffic must use HTTPS. HTTP requests will be rejected
    
*   **Rotate keys periodically**: Contact [Centaur Software](mailto:dentalapi@centaursoftware.com) to rotate API keys if you suspect a compromise
    
*   **Minimal scope**: Request access only to the organisations you need
    

API key lifecycle
-----------------

*   Keys do not expire on a fixed schedule. They remain valid until revoked.
    
*   **Rotation**: contact [Centaur Software](mailto:dentalapi@centaursoftware.com) to issue a new key. The old key remains valid for 24 hours after rotation.
    
*   **Revocation**: keys can be revoked immediately on request. Revoked keys return HTTP 403 on the next request (see Authentication errors below).
    
*   **Storage**: store keys in environment variables or a secrets manager. Never commit them to source control.
    

Authentication errors
---------------------

<Table style="width:100%;min-width:100%" colSizes='["270px","630px"]' isHeaderAdded='true' tableHeader='[{"id":"de96ca6a-19eb-4bfd-b03e-228cc577818a","title":"Status code"},{"id":"c1d73d56-c5c6-488b-a6e9-429d85c71242","title":"Meaning"},{"id":"a7150c3d-c816-42f5-a963-c3d6942f4c33","title":"What to check"}]'>
  <table-row>
    <table-cell><p class="slate-p ">403 Forbidden</p></table-cell>
    <table-cell><p class="slate-p ">Your <code class="slate-code">x-api-key</code> is missing or invalid</p></table-cell>
    <table-cell><p class="slate-p ">Confirmed live: the response body is the literal <code class="slate-code">{"message":"Forbidden"}</code>. Unlike other Dental API errors, it does not use the usual <code class="slate-code">status</code>/<code class="slate-code">message</code>/<code class="slate-code">data</code> shape. Verify the API key value is correct and has not been revoked</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p ">400 Bad Request</p></table-cell>
    <table-cell><p class="slate-p ">Your API key does not have access to the specified <code class="slate-code">org-id</code></p></table-cell>
    <table-cell><p class="slate-p ">Confirmed live: <code class="slate-code">{"data":[],"status":false,"message":"Given Organisation &lt;org&gt; is not associated with provided token."}</code>. Confirm your key is mapped to this organisation. Contact <a href="mailto:dentalapi@centaursoftware.com" target="_self">Centaur Software</a> if needed</p></table-cell>
  </table-row>
</Table>

Example request
---------------

<CodeBlock attributes='{"isFitToPage":true,"style":{},"lang":"plainText","label":"Plain text"}'>
  <CodeLine>curl -X GET "https://api-uat.dental4web.com.au/api/v1/patients?patient_id=12345" \</CodeLine>
  <CodeLine>        -H "org-id: YOUR_ORG_ID" \</CodeLine>
  <CodeLine>        -H "x-api-key: YOUR_API_KEY" \</CodeLine>
  <CodeLine>        -H "Accept: application/json" </CodeLine>
</CodeBlock>

Authentication

Choose your primary integration scenario to jump to the most relevant sections.

*   **Patient Data Integration**: synchronise patient demographics, contact info, and medical history into your system. → [Patient Resources](/patient-resources)
    
*   **Appointment Synchronisation**: pull appointment schedules, status updates, and practitioner assignments for calendar apps. → [Appointment Resources](/appointment-resources)
    
*   **Billing & Payment Systems**: extract transaction data, payment records, and financial reports for accounting software. → [Financial Resources](/financial-resources)
    
*   **EHR/EMR Connectivity**: FHIR R4 endpoints for healthcare interoperability and clinical data exchange. → [FHIR Capabilities](/fhir-capabilities)
    
*   **Development & Testing**: quick authentication setup and endpoint testing for proof-of-concept builds. → [Getting Started](/getting-started)
    
*   **Booking Automation**: create appointments via online forms, voice agents, or chatbots. → [POST Appointment](/appointment-resources/post-appointment), [POST Appointment Reschedule](/appointment-resources/post-appointment-reschedule), [POST Appointment Cancel](/appointment-resources/post-appointment-cancel)
    
*   **CRM-to-PMS Patient Sync**: push patient demographics and updates into Dental4Web. → [POST Patient](/patient-resources/post-patient), [PATCH Patient](/patient-resources/patch-patient)
    
*   **Clinical Note Capture**: record notes from dictation, telehealth, or device integrations. → [POST Clinical Notes](/treatment-and-clinical-resources/post-clinical-notes)
    
*   **Imaging Integration**: embed DICOM or JPEG dental imagery in patient portals or AI diagnostic tools. → [MediaWeb PACS Resources](/mediaweb-pacs-resources)

Find Your Use Case

API Response Formats

FHIR Capabilities

To ensure fair usage and system stability, Dental API enforces rate limits on all requests. There are two distinct, independently-enforced layers: a per-integrator gate checked first, and a per-organisation gate checked afterwards. Most callers will hit the per-integrator gate first; understanding both is important for correctly parsing a `429` response.

Sandbox rate limits
--------------------

The Sandbox environment currently runs with an elevated per-organisation rate-limit override for test traffic; you may not see `429`s in Sandbox at the volumes that would trigger them in production. Do not use Sandbox to validate your retry/backoff logic against these exact thresholds. The limits documented below reflect production behaviour.

Layer 1: Per-integrator limits
-------------------------------

Every request is first checked against a flat limit tied to your integrator API key, applied all day with no time-of-day variation.

<Table style="width:100%;min-width:100%" colSizes='["270px","630px"]' isHeaderAdded='true' tableHeader='[{"id":"45190c39-198f-44aa-a6bb-25b64ff7b206","title":"Limit Type"},{"id":"55085103-4f7f-40ee-a5bc-7ab521cc0a57","title":"Threshold"},{"id":"865c545a-1f2f-4596-aa61-0997a0149906","title":"Window"}]'>
  <table-row>
    <table-cell><p class="slate-p ">Per Integrator</p></table-cell>
    <table-cell><p class="slate-p ">60 calls/min</p></table-cell>
    <table-cell><p class="slate-p ">Per minute (rolling)</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p ">Per Integrator</p></table-cell>
    <table-cell><p class="slate-p ">10,000 requests</p></table-cell>
    <table-cell><p class="slate-p ">Per day (24 hours, rolling)</p></table-cell>
  </table-row>
</Table>

If your integration needs a higher limit, contact us to discuss raising it for your account.

Exceeding either threshold returns `429` with `support_code: "D4W-RL-MIN-001"` (per-minute) or `"D4W-RL-DAY-001"` (daily), and a `retry_after_seconds` field. There is no `data` field on this response.

<CodeBlock attributes='{"isFitToPage":true,"style":{},"lang":"json","label":"JSON"}'>
  <CodeLine></CodeLine>
  <CodeLine>    {</CodeLine>
  <CodeLine>      "status": false,</CodeLine>
  <CodeLine>      "message": "Rate limit exceeded. Please retry after the indicated time.",</CodeLine>
  <CodeLine>      "retry_after_seconds": 60,</CodeLine>
  <CodeLine>      "support_code": "D4W-RL-MIN-001"</CodeLine>
  <CodeLine>    }</CodeLine>
</CodeBlock>

Layer 2: Per-organisation limits
----------------------------------

A request that passes the integrator gate is then checked against a separate limit tied to the target organisation, which varies by time of day (Australian Eastern Time).

<Table style="width:100%;min-width:100%" colSizes='["270px","630px"]' isHeaderAdded='true' tableHeader='[{"id":"a45190c3-198f-44aa-a6bb-25b64ff7b2a1","title":"Limit Type"},{"id":"b55085103-4f7f-40ee-a5bc-7ab521cca2","title":"Threshold"},{"id":"c865c545-1f2f-4596-aa61-0997a01493"}]'>
  <table-row>
    <table-cell><p class="slate-p ">Per Organisation</p></table-cell>
    <table-cell><p class="slate-p ">60 calls/min</p></table-cell>
    <table-cell><p class="slate-p ">Peak: 8:00 AM - 8:00 PM AEST (rolling)</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p ">Per Organisation</p></table-cell>
    <table-cell><p class="slate-p ">120 calls/min</p></table-cell>
    <table-cell><p class="slate-p ">Off-peak: 8:00 PM - 8:00 AM AEST (rolling)</p></table-cell>
  </table-row>
</Table>

Exceeding this limit returns `429` with `support_code: "RL-001"` and a `retry_after` field. As with the integrator-level response, there is no `data` field.

<CodeBlock attributes='{"isFitToPage":true,"style":{},"lang":"json","label":"JSON"}'>
  <CodeLine></CodeLine>
  <CodeLine>    {</CodeLine>
  <CodeLine>      "status": false,</CodeLine>
  <CodeLine>      "message": "Rate limit exceeded. Please retry after the indicated time.",</CodeLine>
  <CodeLine>      "retry_after": 60,</CodeLine>
  <CodeLine>      "support_code": "RL-001"</CodeLine>
  <CodeLine>    }</CodeLine>
</CodeBlock>

Rate limit behaviour
--------------------

When you exceed either layer's limit:

1.  The API returns a `429 Too Many Requests` response
    
2.  The response body includes the layer-specific retry field described above (`retry_after_seconds` for the integrator layer, `retry_after` for the organisation layer), indicating seconds to wait
    
3.  Requests resume normally after the relevant rate limit window resets
    

What counts as a request
------------------------

*   Every successful (2xx) response counts as one request.
    
*   HTTP 4xx responses (including validation errors and rate-limit rejections) count as one request; they consume quota.
    
*   HTTP 5xx responses do NOT count toward your quota.
    
*   Retries triggered by 429 responses count as separate requests; back off with exponential delay.
    

Daylight savings
----------------

The organisation-level peak / off-peak windows shift with Australian Eastern Time daylight savings. During AEDT (October to April), the peak window runs 8:00 AM to 8:00 PM AEDT; during AEST (April to October) it runs 8:00 AM to 8:00 PM AEST. Configure clients to interpret times in Australia/Sydney rather than fixed UTC offsets. The integrator-level limits are not time-of-day dependent and are unaffected by daylight savings.

Best practices to avoid rate limits
-----------------------------------

### Cache reference data

Reference data (practitioners, locations, procedure codes, appointment books, payment types) changes infrequently. Cache these locally and refresh periodically (e.g., daily) rather than fetching on every request.

### Use pagination wisely

*   Default `per_page` is 10, maximum is 500
    
*   For large data sets, use reasonable page sizes (10-50 records)
    
*   Avoid repeatedly fetching the same pages
    

### Implement exponential backoff

When receiving a `429` response, implement exponential backoff:

<CodeBlock attributes='{"isFitToPage":true,"style":{},"lang":"plainText","label":"Plain text"}'>
  <CodeLine>  Wait 1 second, retry</CodeLine>
  <CodeLine>      If still 429, wait 2 seconds, retry</CodeLine>
  <CodeLine>      If still 429, wait 4 seconds, retry</CodeLine>
  <CodeLine>      ...continue doubling up to 32 seconds  </CodeLine>
</CodeBlock>

### Use date range filters

Always specify `from_date` and `to_date` to limit result sets. Smaller, targeted queries are more efficient than fetching all data.

### Leverage the `mode` parameter for sync operations

Use `mode=1` with date filters to fetch only records modified since your last sync, rather than fetching all records repeatedly.


Rate Limits

Validation, Limits & Character Handling

Filtering & Date Ranges

Practices running Dental4Windows on-premise connect to the Dental API through a different path than cloud-hosted (Dental4Web) organisations. This page explains what's actually happening and what it means for your integration.

How on-premise requests are routed
-----------------------------------

Cloud-hosted organisations are read directly from a hosted database. On-premise organisations don't have a database the API can reach directly; instead, the API routes the request to [Halo Connect](https://haloconnect.io), which relays it to an agent running at the practice and relays the result back.

What determines on-premise latency
-----------------------------------

An on-premise request has to round-trip out to the practice's own internet connection, reach their local server, and query their local database before it can return, in a way a cloud-hosted request never does. How long that round trip takes, and how consistent it is from call to call, depends on:

*   The practice's local server hardware and configuration.
    
*   The size of the practice's database.
    
*   The local database engine's own performance.
    

None of this is something Centaur or the Dental API controls or can speed up from our side. On-premise requests will never be as fast or as consistent as cloud-hosted ones; that's a property of the deployment model, not a fault condition.

On-premise requests also have a hard outer limit: Halo Connect enforces a fixed maximum execution time on the on-premise path (on the order of several minutes), after which a query is terminated regardless of local conditions. This isn't a number the Dental API chooses, and it can't be extended for individual integrators; it's a platform-level ceiling. A request that's still running as that ceiling approaches will end in a timeout no matter how the client is configured.

### The overnight backup window

There's one specific, identifiable pattern behind a large share of on-premise slowness and failures, though not all of it (see "Not every on-premise practice behaves the same way" below).

Day to day, the practice's local database runs via a network database server process that runs continuously, servicing both the practice's own D4W software and API calls. This server is configured to stop for a window overnight, commonly from around 11:45pm to 6:00am, so the practice's nightly Dental4Windows backup gets clean, exclusive access to the database file, then restart it afterwards for the day's business. This is standard for the large majority of on-premise D4W practices.

An API call that lands while that server process is stopped forces the local database to fall back to starting a lightweight, single-connection engine just to open the database and service that one query, then shut down again once it's done. That startup-and-shutdown cycle, not the query itself, is what drives the majority of on-premise delays and failures during that window. Depending on exactly when in the window a call lands, it can add anywhere from a few seconds to several minutes on top of the already-variable on-premise round trip.

Beyond the slowdown, there's a data-safety consideration: a call landing during the window risks contending with a backup process that expects exclusive, uncontended access to the database file. In the worst case this can affect the integrity of that backup, which is a materially more serious outcome than a slow response. Avoid sending non-critical or bulk traffic to on-premise organisations during this window, for both reasons.

### Not every on-premise practice behaves the same way

The backup-window pattern above explains most on-premise slowness and failures, but not all of it. Two practices running the identical platform, identical endpoints, and comparable or higher request volume can behave very differently: one may be reliable outside the backup window while another shows a persistently elevated failure rate spread across most or all hours of the day, including well into normal business hours, with no clear relationship to any schedule.

That second pattern is a site-specific connectivity or local-server availability issue, not a variant of the backup-window mechanism, and it isn't something a client-side change (batching, timeout tuning, avoiding the backup window) can fully resolve. If you're seeing it, the practice's own internet connection or on-premise server is the place to investigate, not your integration.

**Telling the two apart:**

*   Failures clustering tightly in the practice's overnight backup window (commonly 11:45pm to 6:00am local time), and otherwise rare, point to the backup-window pattern above.
    
*   Failures spread broadly across the day, including normal business hours, with no clear time-of-day boundary, point to a site-specific issue instead.
    
*   If you operate against multiple on-premise practices, comparing failure rates across them at the same time of day is one of the fastest ways to tell which pattern you're looking at: a shared, uniform effect across practices suggests something in the request pattern itself; an effect isolated to one practice points at that site.
    

Design implication
-------------------

Use `GET /admin/deployment-type` (see Admin Resources) to determine whether you're dealing with a cloud-hosted or on-premise organisation, since the guidance on this page only applies to the latter. Knowing an organisation is on-premise tells you to expect the latency and failure characteristics on this page; it doesn't by itself tell you which pattern (backup window vs. site-specific) you're dealing with.

Practical guidance
--------------------

### Batch instead of looping per record

If you need data for many patients, use date-range or bulk list parameters (`from_date`/`to_date`, `mode` for incremental sync) instead of looping through individual `patient_id` calls. Each request to an on-premise organisation carries meaningful round-trip and local-processing overhead regardless of how much data it returns, so one date-windowed call is typically far cheaper than many single-record calls.

### Avoid the overnight backup window for bulk work

Schedule bulk syncs and other non-critical traffic outside the overnight backup window (commonly 11:45pm to 6:00am). Calls landing in that window are both slower and carry the data-safety consideration described above.

### Cache reference data

Reference data such as practitioners, locations and payment types rarely changes. Fetch it once per run and cache it locally instead of re-fetching it inside a per-record loop; see Rate Limits for the same guidance applied more broadly.

### Retry with backoff

On-premise failures are frequently transient: a request that fails once, especially during or near the overnight backup window, often succeeds on a retry a short time later. Retrying with backoff, rather than surfacing the failure immediately, resolves a meaningful share of on-premise failures without any other change.

### Size your client timeout generously

Successful on-premise responses can legitimately take much longer than a typical cloud-hosted call, well over a minute in some cases, particularly for calls landing near the overnight backup window. A client timeout set too aggressively will cut off requests that were on track to succeed, producing a "failure" that the API itself never actually returned. Size on-premise timeouts well above your cloud-hosted defaults, and treat a timeout as inconclusive rather than a confirmed error where possible.

Summary
--------

On-premise latency is a property of the deployment model: the request has to reach a practice's own internet connection, server, and database, none of which the API controls, and it can be materially worse if a call lands during the overnight backup window. Not every on-premise practice behaves the same way; a failure pattern spread broadly across the day points to a site-specific issue rather than the backup window. Design for it: batch by date range instead of by record, avoid sending non-critical or bulk traffic during the backup window, retry transient failures with backoff, and size client timeouts generously above your cloud-hosted defaults.


On-Premise Connectivity

The Appointment endpoints expose scheduled, confirmed, attended, and cancelled appointments from the practice’s appointment book. Read endpoints support filtering by patient, practitioner, location, date range, and book. Write endpoints support creating, updating (limited fields), cancelling, and rescheduling appointments. <span style="color:rgb(67, 67, 67);background-color:transparent">The API supports FHIR-compliant Appointment resources, ensuring compatibility with healthcare industry standards.</span> FHIR R4 output is available via the dedicated `/api/v1/fhir/<resource>` endpoint variants, see [FHIR Capabilities](/fhir-capabilities).

Appointment Resources

Retrieves a paginated list of appointments from the practice management system. Filter by patient, practitioner, location, date range, or appointment book to find specific appointments.

Use cases
---------

*   Display a practitioner’s upcoming appointments for the day or week.
    
*   Sync appointment schedules to external calendar applications.
    
*   Build patient-facing portals showing upcoming and past appointments.
    
*   Generate attendance reports for practice analytics.
    

Parameters
----------

<Table style="width:100%;min-width:100%" colSizes='["180px","135px","585px"]' isHeaderAdded='true' tableHeader='[{"id":"b1b2c3d4-0001-4bbb-8001-000000000001","title":"Parameter"},{"id":"b1b2c3d4-0001-4bbb-8001-000000000002","title":"Type"},{"id":"b1b2c3d4-0001-4bbb-8001-000000000003","title":"Description"}]'>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">patient_id</code></p></table-cell>
    <table-cell><p class="slate-p ">integer</p></table-cell>
    <table-cell><p class="slate-p ">Filter by patient. At least one of <code class="slate-code">patient_id</code>, <code class="slate-code">appointment_id</code>, <code class="slate-code">appt_book_id</code>, <code class="slate-code">practitioner_id</code>, <code class="slate-code">location_id</code>, <code class="slate-code">from_date</code>, or <code class="slate-code">to_date</code> is required.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">appointment_id</code></p></table-cell>
    <table-cell><p class="slate-p ">integer</p></table-cell>
    <table-cell><p class="slate-p ">Filter to a specific appointment.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">appt_book_id</code></p></table-cell>
    <table-cell><p class="slate-p ">integer</p></table-cell>
    <table-cell><p class="slate-p ">Filter by appointment book.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">practitioner_id</code></p></table-cell>
    <table-cell><p class="slate-p ">integer</p></table-cell>
    <table-cell><p class="slate-p ">Filter by practitioner. Use <code class="slate-code">-1</code> for all practitioners.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">location_id</code></p></table-cell>
    <table-cell><p class="slate-p ">integer</p></table-cell>
    <table-cell><p class="slate-p ">Filter by location. Use <code class="slate-code">-1</code> for all locations.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">from_date</code></p></table-cell>
    <table-cell><p class="slate-p ">date</p></table-cell>
    <table-cell><p class="slate-p ">Start of the date range. See <code class="slate-code">mode</code> below for which date this filters on.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">to_date</code></p></table-cell>
    <table-cell><p class="slate-p ">date</p></table-cell>
    <table-cell><p class="slate-p ">End of the date range.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">mode</code></p></table-cell>
    <table-cell><p class="slate-p ">integer</p></table-cell>
    <table-cell><p class="slate-p ">Date-filtering mode. Confirmed live: <code class="slate-code">mode=0</code> filters on appointment date; <code class="slate-code">mode=1</code> filters on last-modified date (for sync/delta operations), not appointment date. See <a href="/filtering-and-date-ranges">Filtering &amp; date ranges</a>.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">include</code></p></table-cell>
    <table-cell><p class="slate-p ">string</p></table-cell>
    <table-cell><p class="slate-p ">Comma-separated list of relations to embed: <code class="slate-code">patients</code>, <code class="slate-code">practitioners</code>, <code class="slate-code">locations</code>, <code class="slate-code">appt_books</code>, <code class="slate-code">items</code>, <code class="slate-code">payment_types</code>. An invalid value returns an error listing the valid set.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">include_deleted</code></p></table-cell>
    <table-cell><p class="slate-p ">boolean</p></table-cell>
    <table-cell><p class="slate-p ">Include soft-deleted appointments in the result set. Default <code class="slate-code">false</code>.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">per_page</code></p></table-cell>
    <table-cell><p class="slate-p ">integer</p></table-cell>
    <table-cell><p class="slate-p ">Results per page: see <a href="/api-response-formats">API response formats</a>.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">page</code></p></table-cell>
    <table-cell><p class="slate-p ">integer</p></table-cell>
    <table-cell><p class="slate-p ">Page number.</p></table-cell>
  </table-row>
</Table>

Response fields
---------------

<Table style="width:100%;min-width:100%" colSizes='["180px","135px","585px"]' isHeaderAdded='true' tableHeader='[{"id":"0b871661-cd1a-445e-b271-f5d2b6d91d1e","title":"Field"},{"id":"27022d1d-f967-418a-ae7d-ab39df4c5968","title":"Type"},{"id":"c6f96bd3-decf-41a9-9800-6a25abe0fa99","title":"Description"}]'>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">appointment_id</code></p></table-cell>
    <table-cell><p class="slate-p ">integer</p></table-cell>
    <table-cell><p class="slate-p ">Primary identifier.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">appointment_status</code></p></table-cell>
    <table-cell><p class="slate-p ">string</p></table-cell>
    <table-cell><p class="slate-p ">Status description (for example <code class="slate-code">Attended</code>, <code class="slate-code">Confirmed</code>).</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">appointment_status_codes</code></p></table-cell>
    <table-cell><p class="slate-p ">string</p></table-cell>
    <table-cell><p class="slate-p ">Status code abbreviation (for example <code class="slate-code">A</code>).</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">cancelled</code></p></table-cell>
    <table-cell><p class="slate-p ">boolean</p></table-cell>
    <table-cell><p class="slate-p ">True if the appointment was cancelled.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">failed</code></p></table-cell>
    <table-cell><p class="slate-p ">boolean</p></table-cell>
    <table-cell><p class="slate-p ">True if the patient failed to attend.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">attended</code></p></table-cell>
    <table-cell><p class="slate-p ">boolean</p></table-cell>
    <table-cell><p class="slate-p ">True if the patient attended.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">online</code></p></table-cell>
    <table-cell><p class="slate-p ">boolean</p></table-cell>
    <table-cell><p class="slate-p ">True if booked online.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">confirmed</code></p></table-cell>
    <table-cell><p class="slate-p ">boolean</p></table-cell>
    <table-cell><p class="slate-p ">True if the appointment is confirmed.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">is_deleted</code></p></table-cell>
    <table-cell><p class="slate-p ">boolean</p></table-cell>
    <table-cell><p class="slate-p ">True if the appointment record has been soft-deleted. Always present. Set <code class="slate-code">include_deleted=true</code> to return soft-deleted rows.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">appointment_type</code></p></table-cell>
    <table-cell><p class="slate-p ">string</p></table-cell>
    <table-cell><p class="slate-p ">Type or reason for the appointment.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">appointment_date</code></p></table-cell>
    <table-cell><p class="slate-p ">date</p></table-cell>
    <table-cell><p class="slate-p ">Scheduled date (YYYY-MM-DD).</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">start_time</code></p></table-cell>
    <table-cell><p class="slate-p ">datetime</p></table-cell>
    <table-cell><p class="slate-p ">Scheduled start time.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">end_time</code></p></table-cell>
    <table-cell><p class="slate-p ">datetime</p></table-cell>
    <table-cell><p class="slate-p ">Scheduled end time.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">appointment_arrival_time</code></p></table-cell>
    <table-cell><p class="slate-p ">datetime | null</p></table-cell>
    <table-cell><p class="slate-p ">Actual arrival time.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">actual_start_time</code></p></table-cell>
    <table-cell><p class="slate-p ">time | null</p></table-cell>
    <table-cell><p class="slate-p ">Actual treatment start.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">actual_end_time</code></p></table-cell>
    <table-cell><p class="slate-p ">time | null</p></table-cell>
    <table-cell><p class="slate-p ">Actual treatment end.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">duration</code></p></table-cell>
    <table-cell><p class="slate-p ">integer</p></table-cell>
    <table-cell><p class="slate-p ">Duration in minutes.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">recall_set_linked</code></p></table-cell>
    <table-cell><p class="slate-p ">integer</p></table-cell>
    <table-cell><p class="slate-p ">1 if linked to a recall, 0 otherwise.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">patient_id</code></p></table-cell>
    <table-cell><p class="slate-p ">integer</p></table-cell>
    <table-cell><p class="slate-p ">Patient identifier.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">practitioner_id</code></p></table-cell>
    <table-cell><p class="slate-p ">integer</p></table-cell>
    <table-cell><p class="slate-p ">Practitioner identifier.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">location_id</code></p></table-cell>
    <table-cell><p class="slate-p ">integer</p></table-cell>
    <table-cell><p class="slate-p ">Location identifier.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">appt_book_id</code></p></table-cell>
    <table-cell><p class="slate-p ">integer</p></table-cell>
    <table-cell><p class="slate-p ">Appointment book identifier.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">created_date</code></p></table-cell>
    <table-cell><p class="slate-p ">datetime</p></table-cell>
    <table-cell><p class="slate-p ">Record creation timestamp.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">created_user_id</code></p></table-cell>
    <table-cell><p class="slate-p ">integer</p></table-cell>
    <table-cell><p class="slate-p ">User who created the appointment.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">updated_date</code></p></table-cell>
    <table-cell><p class="slate-p ">datetime</p></table-cell>
    <table-cell><p class="slate-p ">Record last-modified timestamp.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">metadata</code></p></table-cell>
    <table-cell><p class="slate-p ">object</p></table-cell>
    <table-cell><p class="slate-p ">Informational fields describing capping, fallback, and default-window behaviour applied to this request. See <a href="/api-response-formats">API Response Formats</a> for the full field list.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">pagination</code></p></table-cell>
    <table-cell><p class="slate-p ">object</p></table-cell>
    <table-cell><p class="slate-p ">Paging details for this result set: <code class="slate-code">page</code>, <code class="slate-code">per_page</code>, <code class="slate-code">total_rows</code>, <code class="slate-code">total_pages</code>. See <a href="/api-response-formats">API Response Formats</a> for the full field list.</p></table-cell>
  </table-row>
</Table>

Important notes
---------------

*   **Date filtering:** supports the `mode` parameter: see [Filtering & Date Ranges](/filtering-and-date-ranges).
    
*   **Default date window when dates are omitted:** a call with none of the parameters above is rejected `400`. A call scoped by `patient_id` runs unwindowed and returns full history. Any other call without explicit `from_date`/`to_date` receives a default window of 30 days in the past and 60 days in the future. See [Filtering & Date Ranges](/filtering-and-date-ranges) for the full table.
    
*   **No filter supplied:** a call with none of the parameters above returns 400. Confirmed live: the response carries no `support_code` (message only).
    
*   **Include relations:** `include=patients` is a supported value. The embedded object uses the singular key `patient` (not `patients`) and contains `patient_id`, `title`, `first_name`, `surname`, `date_of_birth`, `email`, `mobile`. If `patient_id` isn't supplied on a broad call, the `patient` object is silently omitted from the affected rows; no warning, no error.
    
*   **Soft-deleted vs cancelled:** `include_deleted`/`is_deleted` track soft-deletion, which is a different concept from cancellation. For cancelled appointments, see [Get cancelled appointments](/appointment-resources/get-cancelled-appointments); this endpoint's `include_deleted` parameter has no effect on cancellation status.
    
*   **Cancelled appointments are excluded, including in sync queries:** cancelled appointments never appear in a response from this endpoint, in either `mode=0` or `mode=1`. This exclusion is silent: no warning, no error. Cancelled appointments are only available via [Get cancelled appointments](/appointment-resources/get-cancelled-appointments).
    

Quick example
-------------

<CodeBlock attributes='{"isFitToPage":true,"style":{},"lang":"plainText","label":"Plain text"}'>
  <CodeLine>curl "https://api-uat.dental4web.com.au/api/v1/appointments?from_date=2026-06-01&amp;to_date=2026-06-10&amp;per_page=10" \</CodeLine>
  <CodeLine>    -H "x-api-key: $API_KEY" \</CodeLine>
  <CodeLine>    -H "org-id: $ORG_ID" \</CodeLine>
  <CodeLine>    -H "Accept: application/json" </CodeLine>
</CodeBlock>

GET Appointments

Retrieves the complete details of a single appointment by its unique identifier. Use this when you need full appointment information after receiving a notification or webhook, or when displaying appointment details in a patient portal.

Use cases
---------

*   Look up specific appointment details from a notification reference.
    
*   Display comprehensive appointment information in patient-facing applications.
    
*   Verify appointment data before sending automated reminders.
    
*   Retrieve appointment context for clinical workflow integration.
    

Parameters
----------

<Table style="width:100%;min-width:100%" colSizes='["180px","135px","585px"]' isHeaderAdded='true' tableHeader='[{"id":"36fad627-46c3-48d2-ab2e-46bbd76e3a8e","title":"Parameter"},{"id":"0b8076fa-21c3-4988-84f1-af46c063950d","title":"Type"},{"id":"534e8082-f3c6-45bc-b2c5-1652c5649496","title":"Description"}]'>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">appointment_id</code></p></table-cell>
    <table-cell><p class="slate-p ">integer</p></table-cell>
    <table-cell><p class="slate-p ">Required. Path parameter: the unique identifier of the appointment to retrieve.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">include</code></p></table-cell>
    <table-cell><p class="slate-p ">string</p></table-cell>
    <table-cell><p class="slate-p ">Comma-separated list of relations to embed: <code class="slate-code">practitioners</code>, <code class="slate-code">locations</code>, <code class="slate-code">appt_books</code>, or a combination of these (for example <code class="slate-code">practitioners,locations</code>). <code class="slate-code">include=patients</code> is accepted but no longer supported: confirmed live, it does not return an error, but no patient data is embedded in the response. Use <a href="/patient-resources/get-patients">GET /patients</a> with the <code class="slate-code">patient_id</code> from this response instead. An invalid value returns an error listing the valid set.</p></table-cell>
  </table-row>
</Table>

Response fields
---------------

<Table style="width:100%;min-width:100%" colSizes='["180px","135px","585px"]' isHeaderAdded='true' tableHeader='[{"id":"c07c6ff2-b2f5-4e53-992f-f1c56a751990","title":"Field"},{"id":"168533ce-b676-4479-8a5b-07599df88173","title":"Type"},{"id":"c85bc476-af31-4d0a-8523-a628fe1405ce","title":"Description"}]'>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">appointment_id</code></p></table-cell>
    <table-cell><p class="slate-p ">integer</p></table-cell>
    <table-cell><p class="slate-p ">Primary identifier.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">appointment_status</code></p></table-cell>
    <table-cell><p class="slate-p ">string</p></table-cell>
    <table-cell><p class="slate-p ">Status description (for example <code class="slate-code">Confirmed</code>, <code class="slate-code">Unconfirmed</code>).</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">appointment_status_codes</code></p></table-cell>
    <table-cell><p class="slate-p ">string</p></table-cell>
    <table-cell><p class="slate-p ">Status code abbreviation.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">cancelled</code></p></table-cell>
    <table-cell><p class="slate-p ">boolean</p></table-cell>
    <table-cell><p class="slate-p ">True if the appointment was cancelled.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">failed</code></p></table-cell>
    <table-cell><p class="slate-p ">boolean</p></table-cell>
    <table-cell><p class="slate-p ">True if the patient failed to attend.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">attended</code></p></table-cell>
    <table-cell><p class="slate-p ">boolean</p></table-cell>
    <table-cell><p class="slate-p ">True if the patient attended.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">online</code></p></table-cell>
    <table-cell><p class="slate-p ">boolean</p></table-cell>
    <table-cell><p class="slate-p ">True if booked online.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">confirmed</code></p></table-cell>
    <table-cell><p class="slate-p ">boolean</p></table-cell>
    <table-cell><p class="slate-p ">True if the appointment is confirmed.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">appointment_type</code></p></table-cell>
    <table-cell><p class="slate-p ">string</p></table-cell>
    <table-cell><p class="slate-p ">Type or reason for the appointment.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">appointment_date</code></p></table-cell>
    <table-cell><p class="slate-p ">date</p></table-cell>
    <table-cell><p class="slate-p ">Scheduled date (YYYY-MM-DD).</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">start_time</code></p></table-cell>
    <table-cell><p class="slate-p ">datetime</p></table-cell>
    <table-cell><p class="slate-p ">Scheduled start time.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">end_time</code></p></table-cell>
    <table-cell><p class="slate-p ">datetime</p></table-cell>
    <table-cell><p class="slate-p ">Scheduled end time.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">appointment_arrival_time</code></p></table-cell>
    <table-cell><p class="slate-p ">time</p></table-cell>
    <table-cell><p class="slate-p ">Actual arrival time, if recorded.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">actual_start_time</code></p></table-cell>
    <table-cell><p class="slate-p ">time</p></table-cell>
    <table-cell><p class="slate-p ">Actual treatment start, if recorded.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">actual_end_time</code></p></table-cell>
    <table-cell><p class="slate-p ">time</p></table-cell>
    <table-cell><p class="slate-p ">Actual treatment end, if recorded.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">duration</code></p></table-cell>
    <table-cell><p class="slate-p ">integer</p></table-cell>
    <table-cell><p class="slate-p ">Duration in minutes.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">recall_set_linked</code></p></table-cell>
    <table-cell><p class="slate-p ">boolean</p></table-cell>
    <table-cell><p class="slate-p ">True if linked to a recall.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">patient_id</code></p></table-cell>
    <table-cell><p class="slate-p ">integer</p></table-cell>
    <table-cell><p class="slate-p ">Patient identifier.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">practitioner_id</code></p></table-cell>
    <table-cell><p class="slate-p ">integer</p></table-cell>
    <table-cell><p class="slate-p ">Practitioner identifier.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">location_id</code></p></table-cell>
    <table-cell><p class="slate-p ">integer</p></table-cell>
    <table-cell><p class="slate-p ">Location identifier.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">appt_book_id</code></p></table-cell>
    <table-cell><p class="slate-p ">integer</p></table-cell>
    <table-cell><p class="slate-p ">Appointment book identifier.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">created_date</code></p></table-cell>
    <table-cell><p class="slate-p ">datetime</p></table-cell>
    <table-cell><p class="slate-p ">Record creation timestamp.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">created_user_id</code></p></table-cell>
    <table-cell><p class="slate-p ">integer</p></table-cell>
    <table-cell><p class="slate-p ">User who created the appointment.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">updated_date</code></p></table-cell>
    <table-cell><p class="slate-p ">datetime</p></table-cell>
    <table-cell><p class="slate-p ">Record last-modified timestamp.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">metadata</code></p></table-cell>
    <table-cell><p class="slate-p ">object</p></table-cell>
    <table-cell><p class="slate-p ">Informational fields describing capping, fallback, and default-window behaviour applied to this request. See <a href="/api-response-formats">API Response Formats</a> for the full field list.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">pagination</code></p></table-cell>
    <table-cell><p class="slate-p ">object</p></table-cell>
    <table-cell><p class="slate-p ">Paging details for this result set: <code class="slate-code">page</code>, <code class="slate-code">per_page</code>, <code class="slate-code">total_rows</code>, <code class="slate-code">total_pages</code>. See <a href="/api-response-formats">API Response Formats</a> for the full field list.</p></table-cell>
  </table-row>
</Table>

Important notes
---------------

*   **Path parameter:** `appointment_id` is required.
    
*   **Not found:** returns 404 if the appointment does not exist.
    

Quick example
-------------

<CodeBlock attributes='{"isFitToPage":true,"style":{},"lang":"plainText","label":"Plain text"}'>
  <CodeLine>curl "https://api-uat.dental4web.com.au/api/v1/appointments/77116" \</CodeLine>
  <CodeLine>    -H "x-api-key: $API_KEY" \</CodeLine>
  <CodeLine>    -H "org-id: $ORG_ID" \</CodeLine>
  <CodeLine>    -H "Accept: application/json" </CodeLine>
</CodeBlock>

GET Appointment By Id

Retrieves appointments that have been cancelled or where the patient failed to attend. This endpoint helps practices track cancellation patterns, identify patients who frequently cancel, and manage rebooking workflows.

Use cases
---------

*   Identify patients with frequent cancellations for targeted outreach.
    
*   Generate cancellation reports by practitioner or location.
    
*   Monitor no-show trends to optimise scheduling.
    
*   Trigger automated rebooking workflows.
    

Parameters
----------

<Table style="width:100%;min-width:100%" colSizes='["180px","135px","585px"]' isHeaderAdded='true' tableHeader='[{"id":"b1b2c3d4-0002-4bbb-8002-000000000001","title":"Parameter"},{"id":"b1b2c3d4-0002-4bbb-8002-000000000002","title":"Type"},{"id":"b1b2c3d4-0002-4bbb-8002-000000000003","title":"Description"}]'>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">practitioner_id</code></p></table-cell>
    <table-cell><p class="slate-p ">integer</p></table-cell>
    <table-cell><p class="slate-p ">Filter by practitioner. Use <code class="slate-code">-1</code> for all practitioners.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">location_id</code></p></table-cell>
    <table-cell><p class="slate-p ">integer</p></table-cell>
    <table-cell><p class="slate-p ">Filter by location. Use <code class="slate-code">-1</code> for all locations.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">from_date</code></p></table-cell>
    <table-cell><p class="slate-p ">date</p></table-cell>
    <table-cell><p class="slate-p ">Start of the date range. See <code class="slate-code">mode</code> below for which date this filters on.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">to_date</code></p></table-cell>
    <table-cell><p class="slate-p ">date</p></table-cell>
    <table-cell><p class="slate-p ">End of the date range. Defaults to the last 60 days, applied to the appointment date when <code class="slate-code">mode=0</code> or the cancellation date when <code class="slate-code">mode=1</code>, when omitted along with <code class="slate-code">from_date</code>.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">mode</code></p></table-cell>
    <table-cell><p class="slate-p ">integer</p></table-cell>
    <table-cell><p class="slate-p ">Accepts <code class="slate-code">0</code> to <code class="slate-code">10</code>, default <code class="slate-code">0</code>. Only <code class="slate-code">0</code> (filters by original appointment date) and <code class="slate-code">1</code> (filters by cancellation date) are distinct; see Important notes.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">include</code></p></table-cell>
    <table-cell><p class="slate-p ">string</p></table-cell>
    <table-cell><p class="slate-p ">Comma-separated list of relations to embed: <code class="slate-code">patients</code>, <code class="slate-code">practitioners</code>, <code class="slate-code">locations</code>, <code class="slate-code">appt_books</code>, <code class="slate-code">items</code>, <code class="slate-code">payment_types</code>. An invalid value returns an error listing the valid set.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">per_page</code></p></table-cell>
    <table-cell><p class="slate-p ">integer</p></table-cell>
    <table-cell><p class="slate-p ">Results per page: see <a href="/api-response-formats">API response formats</a>.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">page</code></p></table-cell>
    <table-cell><p class="slate-p ">integer</p></table-cell>
    <table-cell><p class="slate-p ">Page number.</p></table-cell>
  </table-row>
</Table>

Response fields
---------------

<Table style="width:100%;min-width:100%" colSizes='["180px","135px","585px"]' isHeaderAdded='true' tableHeader='[{"id":"cb6c1dbf-1791-4990-8c12-87be162dc4fb","title":"Field"},{"id":"9c0a96f5-a699-4165-81b1-f5e86a1686ad","title":"Type"},{"id":"8568c3ea-2c6e-486c-829c-37af426783ac","title":"Description"}]'>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">appointment_id</code></p></table-cell>
    <table-cell><p class="slate-p ">integer</p></table-cell>
    <table-cell><p class="slate-p ">Original appointment identifier.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">appointment_date</code></p></table-cell>
    <table-cell><p class="slate-p ">date</p></table-cell>
    <table-cell><p class="slate-p ">Original scheduled date.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">appointment_time</code></p></table-cell>
    <table-cell><p class="slate-p ">time</p></table-cell>
    <table-cell><p class="slate-p ">Original scheduled time.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">appointment_duration</code></p></table-cell>
    <table-cell><p class="slate-p ">integer</p></table-cell>
    <table-cell><p class="slate-p ">Duration in minutes.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">patient_id</code></p></table-cell>
    <table-cell><p class="slate-p ">integer</p></table-cell>
    <table-cell><p class="slate-p ">Patient identifier.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">practitioner_id</code></p></table-cell>
    <table-cell><p class="slate-p ">integer</p></table-cell>
    <table-cell><p class="slate-p ">Practitioner identifier.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">location_id</code></p></table-cell>
    <table-cell><p class="slate-p ">integer</p></table-cell>
    <table-cell><p class="slate-p ">Location identifier.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">appt_book_id</code></p></table-cell>
    <table-cell><p class="slate-p ">integer</p></table-cell>
    <table-cell><p class="slate-p ">Appointment book identifier.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">cancel_date</code></p></table-cell>
    <table-cell><p class="slate-p ">date</p></table-cell>
    <table-cell><p class="slate-p ">Date of cancellation.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">cancel_type</code></p></table-cell>
    <table-cell><p class="slate-p ">string</p></table-cell>
    <table-cell><p class="slate-p "><code class="slate-code">Cancelled</code> (cancelled by the practice) or <code class="slate-code">Failed</code> (no-show / failed-to-attend).</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">cancel_reason_id</code></p></table-cell>
    <table-cell><p class="slate-p ">integer | null</p></table-cell>
    <table-cell><p class="slate-p ">Reason identifier; correlate against the <code class="slate-code">/cancel-reasons</code> reference list.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">metadata</code></p></table-cell>
    <table-cell><p class="slate-p ">object</p></table-cell>
    <table-cell><p class="slate-p ">Informational fields describing capping, fallback, and default-window behaviour applied to this request. See <a href="/api-response-formats">API Response Formats</a> for the full field list.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">pagination</code></p></table-cell>
    <table-cell><p class="slate-p ">object</p></table-cell>
    <table-cell><p class="slate-p ">Paging details for this result set: <code class="slate-code">page</code>, <code class="slate-code">per_page</code>, <code class="slate-code">total_rows</code>, <code class="slate-code">total_pages</code>. See <a href="/api-response-formats">API Response Formats</a> for the full field list.</p></table-cell>
  </table-row>
</Table>

Important notes
---------------

*   **Mode behaviour:** `mode` accepts any integer from 0 to 10. Only `mode=0` (filters by original appointment date) and `mode=1` (filters by cancellation date) are meaningfully distinct; confirmed live, every other value in that range returns the same result set as `mode=0`.
    
*   **Cancel type:** returns both `Cancelled` and `Failed` appointments. `cancel_type` is an enum: `Cancelled` means cancelled by the practice; `Failed` means a no-show / failed-to-attend.
    
*   **Default range:** defaults to the last 60 days, applied to the appointment date when `mode=0` or the cancellation date when `mode=1`, when no `from_date`/`to_date` is supplied.
    
*   **Required parameters:** at least one query parameter is required. Confirmed live: a call with zero query parameters returns 400 (the same requirement as [Get appointments](/appointment-resources/get-appointments)).
    
*   **Include relations:** `include=patients` is a supported value. The embedded object uses the singular key `patient` (not `patients`) and contains `patient_id`, `title`, `first_name`, `surname`, `date_of_birth`, `email`, `mobile`.
    

Quick example
-------------

<CodeBlock attributes='{"isFitToPage":true,"style":{},"lang":"plainText","label":"Plain text"}'>
  <CodeLine>curl "https://api-uat.dental4web.com.au/api/v1/appointments/cancelled?from_date=2025-01-01&amp;to_date=2026-06-09&amp;per_page=10" \</CodeLine>
  <CodeLine>    -H "x-api-key: $API_KEY" \</CodeLine>
  <CodeLine>    -H "org-id: $ORG_ID" \</CodeLine>
  <CodeLine>    -H "Accept: application/json" </CodeLine>
</CodeBlock>

GET Cancelled Appointments

Returns available appointment slots across appointment books, filtered by duration, book(s), date range, day of week, and time window. Use this endpoint to drive a booking-time picker.

Use cases
---------

*   Power a “next available appointment” widget.
    
*   Discover free slots when proposing a reschedule.
    
*   Audit calendar availability across the practice.
    

Parameters
----------

<Table style="width:100%;min-width:100%" colSizes='["180px","135px","585px"]' isHeaderAdded='true' tableHeader='[{"id":"b1b2c3d4-0004-4bbb-8004-000000000001","title":"Parameter"},{"id":"b1b2c3d4-0004-4bbb-8004-000000000002","title":"Type"},{"id":"b1b2c3d4-0004-4bbb-8004-000000000003","title":"Description"}]'>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">appt_book_ids</code></p></table-cell>
    <table-cell><p class="slate-p ">string</p></table-cell>
    <table-cell><p class="slate-p ">Optional. Omit or pass <code class="slate-code">-1</code> for all active books. Comma-separated appointment book IDs to search. A single book allows up to 90 days in the date range; all books (<code class="slate-code">-1</code>) allow up to 14 days. Exceeding the cap no longer errors: the range is silently clamped and the response returns <code class="slate-code">200</code> with a <code class="slate-code">warnings[]</code> entry explaining the adjustment; see the clamped-range example below.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">from_date</code></p></table-cell>
    <table-cell><p class="slate-p ">date</p></table-cell>
    <table-cell><p class="slate-p ">Start of the date range.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">to_date</code></p></table-cell>
    <table-cell><p class="slate-p ">date</p></table-cell>
    <table-cell><p class="slate-p ">End of the date range. Must not be in the past.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">duration</code></p></table-cell>
    <table-cell><p class="slate-p ">integer</p></table-cell>
    <table-cell><p class="slate-p ">Minimum slot duration in minutes.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">start_time</code></p></table-cell>
    <table-cell><p class="slate-p ">time</p></table-cell>
    <table-cell><p class="slate-p ">Start of the daily time window. Must be before <code class="slate-code">end_time</code>.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">end_time</code></p></table-cell>
    <table-cell><p class="slate-p ">time</p></table-cell>
    <table-cell><p class="slate-p ">End of the daily time window.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">slotmode</code></p></table-cell>
    <table-cell><p class="slate-p ">integer</p></table-cell>
    <table-cell><p class="slate-p ">Which slots to return: <code class="slate-code">0</code> = vacant slots only (default); <code class="slate-code">1</code> = vacant slots plus all presets; <code class="slate-code">2</code> = vacant slots plus online-bookable presets; <code class="slate-code">3</code> = all presets only, no vacant slots; <code class="slate-code">4</code> = online-bookable presets only, no vacant slots.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">per_page</code></p></table-cell>
    <table-cell><p class="slate-p ">integer</p></table-cell>
    <table-cell><p class="slate-p ">Results per page. Capped at 500.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">page</code></p></table-cell>
    <table-cell><p class="slate-p ">integer</p></table-cell>
    <table-cell><p class="slate-p ">Page number.</p></table-cell>
  </table-row>
</Table>

Response fields
---------------

<Table style="width:100%;min-width:100%" colSizes='["180px","135px","585px"]' isHeaderAdded='true' tableHeader='[{"id":"59c63166-c048-46ef-b758-233c4e01e3dd","title":"Field"},{"id":"4f0d05a1-375e-430a-a801-d5063c65592b","title":"Type"},{"id":"c9deb6ed-22c7-463e-b933-74f727d9e39e","title":"Description"}]'>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">location_id</code></p></table-cell>
    <table-cell><p class="slate-p ">integer</p></table-cell>
    <table-cell><p class="slate-p ">Location identifier.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">appt_book_id</code></p></table-cell>
    <table-cell><p class="slate-p ">integer</p></table-cell>
    <table-cell><p class="slate-p ">Appointment book identifier.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">appt_book_name</code></p></table-cell>
    <table-cell><p class="slate-p ">string</p></table-cell>
    <table-cell><p class="slate-p ">Appointment book name.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">slot_type_id</code></p></table-cell>
    <table-cell><p class="slate-p ">integer</p></table-cell>
    <table-cell><p class="slate-p ">Slot type identifier: cross-reference against <a href="/reference-data-resources/get-slot-types">Get slot types</a> for the human-readable name.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">slot_date</code></p></table-cell>
    <table-cell><p class="slate-p ">date</p></table-cell>
    <table-cell><p class="slate-p ">Date of the available slot.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">slot_start</code></p></table-cell>
    <table-cell><p class="slate-p ">time</p></table-cell>
    <table-cell><p class="slate-p ">Slot start time.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">slot_end</code></p></table-cell>
    <table-cell><p class="slate-p ">time</p></table-cell>
    <table-cell><p class="slate-p ">Slot end time.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">duration_available</code></p></table-cell>
    <table-cell><p class="slate-p ">integer</p></table-cell>
    <table-cell><p class="slate-p ">Minutes available in the slot.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">day_of_week</code></p></table-cell>
    <table-cell><p class="slate-p ">integer</p></table-cell>
    <table-cell><p class="slate-p ">Day of week (Monday = 1).</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">metadata</code></p></table-cell>
    <table-cell><p class="slate-p ">object</p></table-cell>
    <table-cell><p class="slate-p ">Informational fields describing capping, fallback, and default-window behaviour applied to this request. See <a href="/api-response-formats">API Response Formats</a> for the full field list.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">pagination</code></p></table-cell>
    <table-cell><p class="slate-p ">object</p></table-cell>
    <table-cell><p class="slate-p ">Paging details for this result set: <code class="slate-code">page</code>, <code class="slate-code">per_page</code>, <code class="slate-code">total_rows</code>, <code class="slate-code">total_pages</code>. See <a href="/api-response-formats">API Response Formats</a> for the full field list.</p></table-cell>
  </table-row>
</Table>

Important notes
---------------

*   Returns one record per available slot, per book, per day.
    
*   **Slot type:** every row includes `slot_type_id`: cross-reference against [Get slot types](/reference-data-resources/get-slot-types) for the human-readable name.
    
*   Pagination is required for large practices; `per_page` is capped at 500.
    
*   **Continuing after a clamp:** the `warnings[]` text for a clamped range names a `next_from` date to continue from. This is informational text only, not a separate response field.
    
*   **Elapsed slots are not filtered:** for the current day, slots earlier than the current time are still returned. `to_date` validation only rejects whole days in the past; it does not filter partially-elapsed time within today. Callers displaying today's availability should filter out already-elapsed slots client-side.
    
*   Only the parameters listed above are accepted. An unsupported query parameter returns `400` with the message `Unexpected parameters: , Please try again.`
    

Error responses
---------------

<Table style="width:100%;min-width:100%" colSizes='["135px","180px","585px"]' isHeaderAdded='true' tableHeader='[{"id":"bb564717-82b3-41bb-9d9c-bb7bec94afa1","title":"Status"},{"id":"5ccf5c45-8a10-4491-af57-c5f08d53c165","title":"support_code"},{"id":"ffdec1fe-b4dc-43e3-a4e5-0fbbde133f65","title":"Meaning"}]'>
  <table-row>
    <table-cell><p class="slate-p ">400</p></table-cell>
    <table-cell><p class="slate-p "><code class="slate-code">SLT-002</code></p></table-cell>
    <table-cell><p class="slate-p "><code class="slate-code">to_date</code> is in the past.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p ">400</p></table-cell>
    <table-cell><p class="slate-p "><code class="slate-code">SLT-003</code></p></table-cell>
    <table-cell><p class="slate-p "><code class="slate-code">start_time</code> at or after <code class="slate-code">end_time</code>.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p ">400</p></table-cell>
    <table-cell><p class="slate-p ">(none)</p></table-cell>
    <table-cell><p class="slate-p ">An unsupported query parameter was supplied.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p ">404</p></table-cell>
    <table-cell><p class="slate-p ">(none)</p></table-cell>
    <table-cell><p class="slate-p ">No slots match the search criteria.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p ">422</p></table-cell>
    <table-cell><p class="slate-p ">(none)</p></table-cell>
    <table-cell><p class="slate-p ">Query parameter out of range (for example <code class="slate-code">duration</code> below 1, <code class="slate-code">per_page</code> above 500, <code class="slate-code">page</code> below 1, <code class="slate-code">slotmode</code> above 4).</p></table-cell>
  </table-row>
</Table>

### Example responses

Date span exceeds the cap; the range is clamped and returned with a warning (`200`):

<CodeBlock attributes='{"isFitToPage":true,"style":{},"lang":"json","label":"JSON"}'>
  <CodeLine></CodeLine>
  <CodeLine>    { "data": [ { "location_id": 1, "appt_book_id": 42, "appt_book_name": "Dr Chen: General", "slot_date": "2026-09-01", "slot_start": "09:00", "slot_end": "09:30", "duration_available": 30, "day_of_week": 2, "slot_type_id": 3 } ], "status": true, "warnings": [ "All-books slot search is capped at 14 days; returned 2026-09-01..2026-09-15 (requested 30 days). Continue from next_from (2026-09-16); pass appt_book_ids to search up to 90 days." ] }</CodeLine>
</CodeBlock>

The same clamping applies when a single book is queried beyond its larger 90-day cap: the `warnings[]` text names the range actually returned (not the book itself).

`to_date` in the past (`400`):

<CodeBlock attributes='{"isFitToPage":true,"style":{},"lang":"json","label":"JSON"}'>
  <CodeLine></CodeLine>
  <CodeLine>    { "data": [], "status": false, "message": "to_date must not be in the past (got 2026-05-24).", "support_code": "SLT-002" }</CodeLine>
</CodeBlock>

`start_time` at or after `end_time` (`400`):

<CodeBlock attributes='{"isFitToPage":true,"style":{},"lang":"json","label":"JSON"}'>
  <CodeLine></CodeLine>
  <CodeLine>    { "data": [], "status": false, "message": "start_time must be before end_time (got start='17:00', end='08:00').", "support_code": "SLT-003" }</CodeLine>
</CodeBlock>

Unsupported parameter (`400`):

<CodeBlock attributes='{"isFitToPage":true,"style":{},"lang":"json","label":"JSON"}'>
  <CodeLine></CodeLine>
  <CodeLine>    { "data": [], "status": false, "message": "Unexpected parameters: appt_book_id, Please try again." }</CodeLine>
</CodeBlock>

No matching slots (`404`):

<CodeBlock attributes='{"isFitToPage":true,"style":{},"lang":"json","label":"JSON"}'>
  <CodeLine></CodeLine>
  <CodeLine>    { "data": [], "status": false, "message": "No records found." }</CodeLine>
</CodeBlock>

Parameter out of range (`422`):

<CodeBlock attributes='{"isFitToPage":true,"style":{},"lang":"json","label":"JSON"}'>
  <CodeLine></CodeLine>
  <CodeLine>    { "data": [], "status": false, "message": "'query -&gt; per_page': ensure this value is less than or equal to 500" }</CodeLine>
</CodeBlock>

Quick example
-------------

<CodeBlock attributes='{"isFitToPage":true,"style":{},"lang":"plainText","label":"Plain text"}'>
  <CodeLine>curl "https://api-uat.dental4web.com.au/api/v1/appointment-slots?appt_book_ids=1&amp;from_date=2026-06-10&amp;to_date=2026-06-20&amp;duration=30" \</CodeLine>
  <CodeLine>    -H "x-api-key: $API_KEY" \</CodeLine>
  <CodeLine>    -H "org-id: $ORG_ID" \</CodeLine>
  <CodeLine>    -H "Accept: application/json" </CodeLine>
</CodeBlock>

GET Appointment Slots

Books a new appointment for a patient in a specific appointment book and time slot.

Use cases
---------

*   An online booking system pushes a new appointment into the practice.
    
*   Book appointments from a Customer Resource Management (CRM) system.
    
*   Create a booking via a voice AI agent.
    

Request body
------------

<Table style="width:100%;min-width:100%" colSizes='["180px","135px","585px"]' isHeaderAdded='true' tableHeader='[{"id":"d89d7412-d384-4684-a803-be5c08b58d52","title":"Field"},{"id":"9e52c447-c6dd-4cbd-851f-735594894b2a","title":"Type"},{"id":"891b7aaa-b5db-4b1a-9d39-c772ead0e379","title":"Description"}]'>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">appt_book_id</code></p></table-cell>
    <table-cell><p class="slate-p ">integer</p></table-cell>
    <table-cell><p class="slate-p ">Required. 1 or greater. Use GET /api/v1/appointment-slots to discover bookable IDs.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">appointment_date</code></p></table-cell>
    <table-cell><p class="slate-p ">string</p></table-cell>
    <table-cell><p class="slate-p ">Required. YYYY-MM-DD.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">patient_id</code></p></table-cell>
    <table-cell><p class="slate-p ">string</p></table-cell>
    <table-cell><p class="slate-p ">Required. The unique identifier for a patient in the database.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">start_time</code></p></table-cell>
    <table-cell><p class="slate-p ">string</p></table-cell>
    <table-cell><p class="slate-p ">Required. HH:MM (24-hour).</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">finish_time</code></p></table-cell>
    <table-cell><p class="slate-p ">string</p></table-cell>
    <table-cell><p class="slate-p ">Required. HH:MM, strictly after <code class="slate-code">start_time</code>.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">practitioner_id</code></p></table-cell>
    <table-cell><p class="slate-p ">integer</p></table-cell>
    <table-cell><p class="slate-p "><code class="slate-code">practitioner_id</code> from /api/v1/practitioners. Confirmed live: must be 1 or greater, not 0.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">class_id</code></p></table-cell>
    <table-cell><p class="slate-p ">integer</p></table-cell>
    <table-cell><p class="slate-p ">From /api/v1/appointment-classes. Default 1.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">notes</code></p></table-cell>
    <table-cell><p class="slate-p ">string</p></table-cell>
    <table-cell><p class="slate-p ">Up to 450 characters.</p></table-cell>
  </table-row>
</Table>

Returns
-------

A `200` returns the created appointment object in `data`, with the same fields as [Get appointment by ID](/appointment-resources/get-appointment-by-id). The `notes` value is stored but is not echoed back in the appointment response.

Error responses
---------------

<Table style="width:100%;min-width:100%" colSizes='["180px","135px","585px"]' isHeaderAdded='true' tableHeader='[{"id":"6ed3b516-d90f-4619-9afc-1c348bf07459","title":"Status"},{"id":"64b513d4-b404-4e9b-ab02-6e0a85bccba4","title":"support_code"},{"id":"8a27cfc7-af9e-4ddf-b41a-b5552586db96","title":"Meaning"}]'>
  <table-row>
    <table-cell><p class="slate-p ">400</p></table-cell>
    <table-cell><p class="slate-p "><code class="slate-code">AW-6042</code></p></table-cell>
    <table-cell><p class="slate-p ">Duration not greater than zero (<code class="slate-code">finish_time</code> at or before <code class="slate-code">start_time</code>).</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p ">404</p></table-cell>
    <table-cell><p class="slate-p "><code class="slate-code">AW-6010</code></p></table-cell>
    <table-cell><p class="slate-p "><code class="slate-code">appt_book_id</code> not found.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p ">404</p></table-cell>
    <table-cell><p class="slate-p "><code class="slate-code">AW-6011</code></p></table-cell>
    <table-cell><p class="slate-p "><code class="slate-code">practitioner_id</code> not found.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p ">404</p></table-cell>
    <table-cell><p class="slate-p "><code class="slate-code">AW-6012</code></p></table-cell>
    <table-cell><p class="slate-p "><code class="slate-code">patient_id</code> not found.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p ">404</p></table-cell>
    <table-cell><p class="slate-p "><code class="slate-code">AW-6051</code></p></table-cell>
    <table-cell><p class="slate-p "><code class="slate-code">class_id</code> not found.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p ">409</p></table-cell>
    <table-cell><p class="slate-p "><code class="slate-code">AW-6020</code></p></table-cell>
    <table-cell><p class="slate-p ">Day or source is locked.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p ">409</p></table-cell>
    <table-cell><p class="slate-p "><code class="slate-code">AW-6021</code></p></table-cell>
    <table-cell><p class="slate-p ">Selected time slot is no longer available.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p ">422</p></table-cell>
    <table-cell><p class="slate-p "><code class="slate-code">AW-6005</code></p></table-cell>
    <table-cell><p class="slate-p ">Outside practice operating hours.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p ">422</p></table-cell>
    <table-cell><p class="slate-p "><code class="slate-code">AW-6040</code></p></table-cell>
    <table-cell><p class="slate-p "><code class="slate-code">appointment_date</code> in the past or more than 3650 days in the future.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p ">400</p></table-cell>
    <table-cell><p class="slate-p "><code class="slate-code">AW-6023</code></p></table-cell>
    <table-cell><p class="slate-p "><code class="slate-code">notes</code> contains a disallowed HTML markup pattern (rejected outright, not saved). See Notes content validation below.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p ">422</p></table-cell>
    <table-cell><p class="slate-p ">(none)</p></table-cell>
    <table-cell><p class="slate-p ">Required field missing, or <code class="slate-code">appt_book_id</code> below 1, or invalid format (schema validation).</p></table-cell>
  </table-row>
</Table>

`notes` containing characters with no ASCII equivalent, or exceeding the column width after conversion, return `400` with `AW-6025` / `AW-6026` (same shape as the patient `PW-6025` / `PW-6026` examples).

For the canonical list of error codes, see [Validation, Limits & Character Handling](/validation-limits-and-character-handling).

### Example error responses

Required fields missing (`422`):

<CodeBlock attributes='{"isFitToPage":true,"style":{},"lang":"json","label":"JSON"}'>
  <CodeLine></CodeLine>
  <CodeLine>    { "data": [], "status": false, "message": "'appointment_date': field required; 'patient_id': field required; 'start_time': field required; 'finish_time': field required" }</CodeLine>
</CodeBlock>

`appt_book_id` below 1 (`422`):

<CodeBlock attributes='{"isFitToPage":true,"style":{},"lang":"json","label":"JSON"}'>
  <CodeLine></CodeLine>
  <CodeLine>    { "data": [], "status": false, "message": "'appt_book_id': ensure this value is greater than or equal to 1" }</CodeLine>
</CodeBlock>

Duration not positive (`400`):

<CodeBlock attributes='{"isFitToPage":true,"style":{},"lang":"json","label":"JSON"}'>
  <CodeLine></CodeLine>
  <CodeLine>    { "data": [], "status": false, "message": "appointment duration must be greater than zero (start_time='10:00:00', finish_time='09:30:00').", "support_code": "AW-6042" }</CodeLine>
</CodeBlock>

Date in the past (`422`):

<CodeBlock attributes='{"isFitToPage":true,"style":{},"lang":"json","label":"JSON"}'>
  <CodeLine></CodeLine>
  <CodeLine>    { "data": [], "status": false, "message": "appointment_date must not be in the past (got 2026-05-24).", "support_code": "AW-6040" }</CodeLine>
</CodeBlock>

Date too far in the future (`422`):

<CodeBlock attributes='{"isFitToPage":true,"style":{},"lang":"json","label":"JSON"}'>
  <CodeLine></CodeLine>
  <CodeLine>    { "data": [], "status": false, "message": "appointment_date must not be more than 3650 days in the future (got 2037-05-08).", "support_code": "AW-6040" }</CodeLine>
</CodeBlock>

Outside operating hours (`422`):

<CodeBlock attributes='{"isFitToPage":true,"style":{},"lang":"json","label":"JSON"}'>
  <CodeLine></CodeLine>
  <CodeLine>    { "data": [], "status": false, "message": "Selected time falls outside the practice's operating hours.", "support_code": "AW-6005" }</CodeLine>
</CodeBlock>

Appointment book not found (`404`):

<CodeBlock attributes='{"isFitToPage":true,"style":{},"lang":"json","label":"JSON"}'>
  <CodeLine></CodeLine>
  <CodeLine>    { "data": [], "status": false, "message": "Appointment book not found.", "support_code": "AW-6010" }</CodeLine>
</CodeBlock>

Patient not found (`404`):

<CodeBlock attributes='{"isFitToPage":true,"style":{},"lang":"json","label":"JSON"}'>
  <CodeLine></CodeLine>
  <CodeLine>    { "data": [], "status": false, "message": "Patient not found.", "support_code": "AW-6012" }</CodeLine>
</CodeBlock>

Appointment class not found (`404`):

<CodeBlock attributes='{"isFitToPage":true,"style":{},"lang":"json","label":"JSON"}'>
  <CodeLine></CodeLine>
  <CodeLine>    { "data": [], "status": false, "message": "Appointment class 99999 not found.", "support_code": "AW-6051" }</CodeLine>
</CodeBlock>

Practitioner not found (`404`):

<CodeBlock attributes='{"isFitToPage":true,"style":{},"lang":"json","label":"JSON"}'>
  <CodeLine></CodeLine>
  <CodeLine>    { "data": [], "status": false, "message": "Practitioner 99999 not found.", "support_code": "AW-6011" }</CodeLine>
</CodeBlock>

Slot no longer available (`409`):

<CodeBlock attributes='{"isFitToPage":true,"style":{},"lang":"json","label":"JSON"}'>
  <CodeLine></CodeLine>
  <CodeLine>    { "data": [], "status": false, "message": "The selected time slot is no longer available. Please choose a different time.", "support_code": "AW-6021" }</CodeLine>
</CodeBlock>

Notes contain unsupported characters (`400`):

<CodeBlock attributes='{"isFitToPage":true,"style":{},"lang":"json","label":"JSON"}'>
  <CodeLine></CodeLine>
  <CodeLine>    { "data": [], "status": false, "message": "One or more fields contain characters the practice management system cannot store and that have no accepted ASCII equivalent (fields: notes). Re-submit using Latin characters only. [AW-6025]", "support_code": "AW-6025" }</CodeLine>
</CodeBlock>

`AW-6020` (day or source locked) and `AW-6026` (notes exceed the column width after conversion) return the standard envelope with their `support_code`.

Important notes
---------------

*   Required fields are `appt_book_id`, `appointment_date`, `patient_id`, `start_time`, and `finish_time`.
    
*   The time slot must be available in the target appointment book; conflicts return `409` with `AW-6021`.
    
*   `appointment_date` must be no more than 3650 days (about 10 years) in the future and not in the past.
    
*   Duration must be greater than zero (`finish_time` strictly after `start_time`).
    
*   Operating hours are enforced (`AW-6005`); outside-hours bookings are rejected.
    
*   An active practitioner is required if `practitioner_id` is supplied.
    
*   `notes` are capped at 450 characters; accented characters are converted to their plain-letter equivalent; content that looks like HTML or script is rejected outright with a `400`; nothing is saved, nothing is sanitised. See Notes content validation below. The `notes` value, when accepted, is stored but is not echoed back in the appointment response.
    

### Notes content validation

Content in `notes` that looks like HTML or script is rejected outright with a `400`; nothing is saved, and no `warnings[]` entry is produced. Two response shapes are possible depending on what's submitted:

*   Bare HTML-style markup (for example angle brackets around ordinary text) returns `AW-6023`:

<CodeBlock attributes='{"isFitToPage":true,"style":{},"lang":"json","label":"JSON"}'>
  <CodeLine></CodeLine>
  <CodeLine>    { "data": [], "status": false, "message": "notes contains a disallowed HTML markup pattern and was rejected. Strip HTML tags / script / iframe / event-handler markup from this field and retry.", "support_code": "AW-6023" }</CodeLine>
</CodeBlock>

*   Script-shaped or executable content (`<script>` tags, event-handler attributes, `javascript:` URIs, and similar) is caught earlier and returns a `400` with no `support_code`:

<CodeBlock attributes='{"isFitToPage":true,"style":{},"lang":"json","label":"JSON"}'>
  <CodeLine></CodeLine>
  <CodeLine>    { "data": [], "status": false, "message": "Request rejected by security policy. Check your input does not contain HTML or script content." }</CodeLine>
</CodeBlock>

Confirmed live 2026-08-29: multiple independent validation layers apply this check, so a request can be caught before it reaches application logic at all. Treat both response shapes as equally final: there is no sanitise-and-save fallback for HTML/script content, unlike the ASCII-folding behaviour described above.

Quick example
-------------

<CodeBlock attributes='{"isFitToPage":true,"style":{},"lang":"plainText","label":"Plain text"}'>
  <CodeLine>curl -X POST "https://api-uat.dental4web.com.au/api/v1/appointments" \</CodeLine>
  <CodeLine>    -H "x-api-key: $API_KEY" \</CodeLine>
  <CodeLine>    -H "org-id: $ORG_ID" \</CodeLine>
  <CodeLine>    -H "Accept: application/json" \</CodeLine>
  <CodeLine>    -H "Content-Type: application/json" \</CodeLine>
  <CodeLine>    -d '{"appt_book_id": 5, "appointment_date": "2026-06-01", "patient_id": 12345, "start_time": "14:00", "finish_time": "14:30"}' </CodeLine>
</CodeBlock>

POST Appointment

Updates a small set of mutable fields on an existing, non-cancelled appointment. The PATCH surface is intentionally narrow. To move the appointment in time or change its book, use [Reschedule appointment](/appointment-resources/post-appointment-reschedule) instead.

Use cases
---------

*   Adjust the appointment finish time after the patient arrives (for example a shorter procedure).
    
*   Update the `notes` field after the practitioner records additional context.
    
*   Reassign the appointment to a different practitioner without changing time or book.
    

Request body
------------

<Table style="width:100%;min-width:100%" colSizes='["180px","135px","585px"]' isHeaderAdded='true' tableHeader='[{"id":"91e0d3b7-bb26-4877-a3e4-16139d47a0a7","title":"Field"},{"id":"c5360932-4e97-43f3-aa99-f9095b0fba61","title":"Type"},{"id":"7a464bdf-dcce-4c22-b021-dce2201413a4","title":"Description"}]'>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">finish_time</code></p></table-cell>
    <table-cell><p class="slate-p ">string</p></table-cell>
    <table-cell><p class="slate-p ">Optional. HH:MM, must remain inside the book's operating hours.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">practitioner_id</code></p></table-cell>
    <table-cell><p class="slate-p ">integer</p></table-cell>
    <table-cell><p class="slate-p ">Optional. <code class="slate-code">practitioner_id</code> from /api/v1/practitioners. Confirmed live: must be 1 or greater, not 0.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">notes</code></p></table-cell>
    <table-cell><p class="slate-p ">string</p></table-cell>
    <table-cell><p class="slate-p ">Optional. Up to 450 characters.</p></table-cell>
  </table-row>
</Table>

At least one of `finish_time`, `notes`, or `practitioner_id` must be supplied.

Returns
-------

A `200` returns the updated appointment object in `data`, with the same fields as [Get appointment by ID](/appointment-resources/get-appointment-by-id).

Error responses
---------------

<Table style="width:100%;min-width:100%" colSizes='["180px","135px","585px"]' isHeaderAdded='true' tableHeader='[{"id":"b41b22dc-bbc4-4677-b626-43f964ab7d70","title":"Status"},{"id":"cb86b220-ad36-43fc-a26a-bdac4ff19b4f","title":"support_code"},{"id":"fcc7e490-6c66-43e5-81fa-95f4d3c7dc40","title":"Meaning"}]'>
  <table-row>
    <table-cell><p class="slate-p ">400</p></table-cell>
    <table-cell><p class="slate-p "><code class="slate-code">AW-6054</code></p></table-cell>
    <table-cell><p class="slate-p ">New <code class="slate-code">finish_time</code> is invalid (at or before <code class="slate-code">start_time</code>).</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p ">400</p></table-cell>
    <table-cell><p class="slate-p "><code class="slate-code">AW-6053</code></p></table-cell>
    <table-cell><p class="slate-p ">No update fields provided / no effective change.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p ">404</p></table-cell>
    <table-cell><p class="slate-p "><code class="slate-code">AW-6013</code></p></table-cell>
    <table-cell><p class="slate-p ">Source appointment not found or is cancelled.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p ">404</p></table-cell>
    <table-cell><p class="slate-p "><code class="slate-code">AW-6052</code></p></table-cell>
    <table-cell><p class="slate-p ">New <code class="slate-code">practitioner_id</code> not found.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p ">400</p></table-cell>
    <table-cell><p class="slate-p "><code class="slate-code">AW-6023</code></p></table-cell>
    <table-cell><p class="slate-p "><code class="slate-code">notes</code> contains a disallowed HTML markup pattern (rejected outright, not saved). See Notes content validation on [Create appointment](/appointment-resources/post-appointment); the same check applies here.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p ">400</p></table-cell>
    <table-cell><p class="slate-p ">(none)</p></table-cell>
    <table-cell><p class="slate-p "><code class="slate-code">notes</code> contains script or event-handler-shaped content (rejected outright, not saved).</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p ">409</p></table-cell>
    <table-cell><p class="slate-p "><code class="slate-code">AW-6057</code></p></table-cell>
    <table-cell><p class="slate-p ">Update failed partway through and was rolled back to the original appointment.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p ">500</p></table-cell>
    <table-cell><p class="slate-p "><code class="slate-code">AW-6097</code></p></table-cell>
    <table-cell><p class="slate-p ">Critical: update failed partway through and could not be rolled back. Contact support immediately.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p ">422</p></table-cell>
    <table-cell><p class="slate-p ">(none)</p></table-cell>
    <table-cell><p class="slate-p ">Body has none of <code class="slate-code">finish_time</code> / <code class="slate-code">notes</code> / <code class="slate-code">practitioner_id</code>, or an invalid field type.</p></table-cell>
  </table-row>
</Table>

`notes` containing characters with no ASCII equivalent, or exceeding the column width after conversion, return `400` with `AW-6025` / `AW-6026`.

`notes` content that looks like HTML or script is rejected outright with `400` (`AW-6023` for markup-shaped content, no `support_code` for script/event-handler-shaped content); nothing is saved, nothing is sanitised. This is the same validation layer as [Create appointment](/appointment-resources/post-appointment).

For the canonical list of error codes, see [Validation, Limits & Character Handling](/validation-limits-and-character-handling).

### Example error responses

Source appointment not found (`404`):

<CodeBlock attributes='{"isFitToPage":true,"style":{},"lang":"json","label":"JSON"}'>
  <CodeLine></CodeLine>
  <CodeLine>    { "data": [], "status": false, "message": "Source appointment not found.", "support_code": "AW-6013" }</CodeLine>
</CodeBlock>

No updatable fields supplied (`422`):

<CodeBlock attributes='{"isFitToPage":true,"style":{},"lang":"json","label":"JSON"}'>
  <CodeLine></CodeLine>
  <CodeLine>    { "data": [], "status": false, "message": "At least one of finish_time / notes / practitioner_id must be supplied" }</CodeLine>
</CodeBlock>

No effective change (`400`):

<CodeBlock attributes='{"isFitToPage":true,"style":{},"lang":"json","label":"JSON"}'>
  <CodeLine></CodeLine>
  <CodeLine>    { "data": [], "status": false, "message": "No update fields provided. Specify at least one field to change.", "support_code": "AW-6053" }</CodeLine>
</CodeBlock>

Invalid finish time (`400`):

<CodeBlock attributes='{"isFitToPage":true,"style":{},"lang":"json","label":"JSON"}'>
  <CodeLine></CodeLine>
  <CodeLine>    { "data": [], "status": false, "message": "Finish time is invalid.", "support_code": "AW-6054" }</CodeLine>
</CodeBlock>

Practitioner not found (`404`):

<CodeBlock attributes='{"isFitToPage":true,"style":{},"lang":"json","label":"JSON"}'>
  <CodeLine></CodeLine>
  <CodeLine>    { "data": [], "status": false, "message": "Practitioner 99999 not found.", "support_code": "AW-6052" }</CodeLine>
</CodeBlock>

Notes contain disallowed HTML markup (`400`):

<CodeBlock attributes='{"isFitToPage":true,"style":{},"lang":"json","label":"JSON"}'>
  <CodeLine></CodeLine>
  <CodeLine>    { "data": [], "status": false, "message": "notes contains a disallowed HTML markup pattern and was rejected. Strip HTML tags / script / iframe / event-handler markup from this field and retry.", "support_code": "AW-6023" }</CodeLine>
</CodeBlock>

Notes contain script-shaped content (`400`):

<CodeBlock attributes='{"isFitToPage":true,"style":{},"lang":"json","label":"JSON"}'>
  <CodeLine></CodeLine>
  <CodeLine>    { "data": [], "status": false, "message": "Request rejected by security policy. Check your input does not contain HTML or script content." }</CodeLine>
</CodeBlock>

Important notes
---------------

*   Only three fields are mutable via PATCH: `finish_time`, `notes`, and `practitioner_id`.
    
*   At least one of these must be supplied. An empty body, or a body with no effective change, is rejected.
    
*   Cancelled appointments are not visible to PATCH and return `404 AW-6013 "Source appointment not found"` by design.
    
*   Certain mutations (for example a practitioner reassignment) are implemented internally as a delete-then-recreate against the underlying record. `AW-6052` is the clean pre-mutation rejection when the new `practitioner_id` is invalid; if the recreate step itself fails after the delete, `AW-6057` (rolled back) or, rarely, `AW-6097` (could not be rolled back, contact support) may be returned instead.
    
*   To change `appointment_date`, `start_time`, `appt_book_id`, `patient_id`, or `class_id`, use `POST /api/v1/appointments/{id}/reschedule`.
    

Quick example
-------------

<CodeBlock attributes='{"isFitToPage":true,"style":{},"lang":"plainText","label":"Plain text"}'>
  <CodeLine>curl -X PATCH "https://api-uat.dental4web.com.au/api/v1/appointments/85799" \</CodeLine>
  <CodeLine>    -H "x-api-key: $API_KEY" \</CodeLine>
  <CodeLine>    -H "org-id: $ORG_ID" \</CodeLine>
  <CodeLine>    -H "Accept: application/json" \</CodeLine>
  <CodeLine>    -H "Content-Type: application/json" \</CodeLine>
  <CodeLine>    -d '{"finish_time": "14:45", "notes": "Extended for additional treatment"}' </CodeLine>
</CodeBlock>

PATCH Appointment

Marks an appointment as cancelled. Cancelled appointments are no longer visible to PATCH or reschedule operations.

Use cases
---------

*   A patient phones to cancel.
    
*   The practice cancels due to clinician availability.
    
*   An external booking system propagates a cancellation.
    

Request body
------------

<Table style="width:100%;min-width:100%" colSizes='["180px","135px","585px"]' isHeaderAdded='true' tableHeader='[{"id":"62b8df99-1e64-40e5-9cd1-fcedf997c736","title":"Field"},{"id":"85b6dd08-c0a4-40d2-8ac0-16ced74ea382","title":"Type"},{"id":"2784e6c2-8905-494a-b566-4662a0bf3bfa","title":"Description"}]'>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">cancel_reason_id</code></p></table-cell>
    <table-cell><p class="slate-p ">integer</p></table-cell>
    <table-cell><p class="slate-p ">Optional. 1 or greater. Use a value from /api/v1/cancel-reasons.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">notes</code></p></table-cell>
    <table-cell><p class="slate-p ">string</p></table-cell>
    <table-cell><p class="slate-p ">Optional. Up to 256 characters.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">is_copy</code></p></table-cell>
    <table-cell><p class="slate-p ">integer</p></table-cell>
    <table-cell><p class="slate-p ">Optional. 0 (default) or 1.</p></table-cell>
  </table-row>
</Table>

`appointment_id` is supplied as a path parameter on `POST /api/v1/appointments/{appointment_id}/cancel`.

Returns
-------

A `200` confirms the cancellation. Note: the response field name is `appt_id` (not `appointment_id` as used elsewhere). This is a known API-side inconsistency.

Error responses
---------------


<Table style="width:100%;min-width:100%" colSizes='["180px","135px","585px"]' isHeaderAdded='true' tableHeader='[{"id":"c6b75630-2a50-4dfa-87b3-d9948d4a897b","title":"Status"},{"id":"961e2c8c-6d5c-4edd-818e-f80e8f494809","title":"support_code"},{"id":"358e50e0-9ed0-4556-b365-50e8fbde1764","title":"Meaning"}]'>
  <table-row>
    <table-cell><p class="slate-p ">422</p></table-cell>
    <table-cell><p class="slate-p ">(none)</p></table-cell>
    <table-cell><p class="slate-p "><code class="slate-code">notes</code> exceeds 256 characters (schema validation, checked before any business-logic rules run).</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p ">404</p></table-cell>
    <table-cell><p class="slate-p "><code class="slate-code">AW-6050</code></p></table-cell>
    <table-cell><p class="slate-p ">Appointment not found (does not exist or already cancelled).</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p ">422</p></table-cell>
    <table-cell><p class="slate-p ">(none)</p></table-cell>
    <table-cell><p class="slate-p "><code class="slate-code">cancel_reason_id</code> below 1, or <code class="slate-code">is_copy</code> not 0/1 (schema validation).</p></table-cell>
  </table-row>
</Table>

For the canonical list of error codes, see [Validation, Limits & Character Handling](/validation-limits-and-character-handling).

### Example error responses

`notes` over 256 characters (`422`):

<CodeBlock attributes='{"isFitToPage":true,"style":{},"lang":"json","label":"JSON"}'>
  <CodeLine></CodeLine>
  <CodeLine>    { "data": [], "status": false, "message": "'notes': ensure this value has at most 256 characters" }</CodeLine>
</CodeBlock>

Appointment not found or already cancelled (`404`):

<CodeBlock attributes='{"isFitToPage":true,"style":{},"lang":"json","label":"JSON"}'>
  <CodeLine></CodeLine>
  <CodeLine>    { "data": [], "status": false, "message": "Appointment not found.", "support_code": "AW-6050" }</CodeLine>
</CodeBlock>

`cancel_reason_id` below 1 (`422`):

<CodeBlock attributes='{"isFitToPage":true,"style":{},"lang":"json","label":"JSON"}'>
  <CodeLine></CodeLine>
  <CodeLine>    { "data": [], "status": false, "message": "'cancel_reason_id': ensure this value is greater than or equal to 1" }</CodeLine>
</CodeBlock>

`is_copy` not 0 or 1 (`422`):

<CodeBlock attributes='{"isFitToPage":true,"style":{},"lang":"json","label":"JSON"}'>
  <CodeLine></CodeLine>
  <CodeLine>    { "data": [], "status": false, "message": "'is_copy': ensure this value is less than or equal to 1" }</CodeLine>
</CodeBlock>

Important notes
---------------

*   By design, once cancelled the appointment is no longer visible to subsequent write operations. Re-cancelling returns `404 AW-6050`.
    
*   `cancel_reason_id` is optional. To record a specific reason, supply a valid ID from `GET /api/v1/cancel-reasons`. Omitting it does not prevent cancellation.
    
*   When supplied, `cancel_reason_id` must be 1 or greater; a value below 1 is rejected with `422`.

*   A `cancel_reason_id` of 1 or greater that doesn't match a currently active reason for the practice is not rejected: the cancellation still succeeds, but the reason is silently dropped, and the response's `warnings[]` discloses this.
    
*   `is_copy` controls whether a copy of the original is created as part of the cancel flow (useful for audit trails). It defaults to 0 (no copy) and accepts only 0 or 1.
    
*   `notes` are capped at 256 characters (a much smaller column than Create/Update Appointment's `notes` field); a value over the limit is rejected with `422` and no `support_code`, a schema-validation message naming the field and the limit (not `AW-6026`: that code is used elsewhere for over-length fields, but not for this schema-level check).
    
*   Note: the response field name is `appt_id` (not `appointment_id` as used elsewhere). This is a known API-side inconsistency.
    

Quick example
-------------

<CodeBlock attributes='{"isFitToPage":true,"style":{},"lang":"plainText","label":"Plain text"}'>
  <CodeLine>curl -X POST "https://api-uat.dental4web.com.au/api/v1/appointments/85799/cancel" \</CodeLine>
  <CodeLine>    -H "x-api-key: $API_KEY" \</CodeLine>
  <CodeLine>    -H "org-id: $ORG_ID" \</CodeLine>
  <CodeLine>    -H "Accept: application/json" \</CodeLine>
  <CodeLine>    -H "Content-Type: application/json" \</CodeLine>
  <CodeLine>    -d '{"cancel_reason_id": 3, "is_copy": 0}' </CodeLine>
</CodeBlock>

POST Appointment Cancel

Moves an existing appointment to a new time slot, optionally as a copy.

Use cases
---------

*   A patient requests a different time.
    
*   The practice consolidates appointments after a cancellation.
    
*   Copy an existing appointment to a follow-up slot (`is_copy: 1`).
    

Request body
------------

<Table style="width:100%;min-width:100%" colSizes='["180px","135px","585px"]' isHeaderAdded='true' tableHeader='[{"id":"4809bace-041c-433f-8b4b-7fa9ff280344","title":"Field"},{"id":"0c42b57d-47f4-43ba-9c69-9042b3044e54","title":"Type"},{"id":"b2148ef0-12c4-45b0-814e-35720f66d982","title":"Description"}]'>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">to_appt_book_id</code></p></table-cell>
    <table-cell><p class="slate-p ">integer</p></table-cell>
    <table-cell><p class="slate-p ">Required. 1 or greater. Use GET /api/v1/appointment-slots to discover bookable IDs.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">to_appointment_date</code></p></table-cell>
    <table-cell><p class="slate-p ">string</p></table-cell>
    <table-cell><p class="slate-p ">Required. YYYY-MM-DD.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">to_start_time</code></p></table-cell>
    <table-cell><p class="slate-p ">string</p></table-cell>
    <table-cell><p class="slate-p ">Required. HH:MM (24-hour).</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">is_copy</code></p></table-cell>
    <table-cell><p class="slate-p ">integer</p></table-cell>
    <table-cell><p class="slate-p ">Optional. 0 moves (default), 1 copies.</p></table-cell>
  </table-row>
</Table>

`appointment_id` is supplied as a path parameter on `POST /api/v1/appointments/{appointment_id}/reschedule`.

Returns
-------

A `200` returns the rescheduled appointment object in `data`, with the same fields as [Get appointment by ID](/appointment-resources/get-appointment-by-id). With `is_copy: 1`, a new appointment is created at the destination and the original is left in place.

Error responses
---------------

<Table style="width:100%;min-width:100%" colSizes='["180px","135px","585px"]' isHeaderAdded='true' tableHeader='[{"id":"39b99835-1ab2-4ab4-ab61-94cc9ae60166","title":"Status"},{"id":"69147c6d-0573-499f-90f2-2448c4645cca","title":"support_code"},{"id":"7842fcdb-3067-4ea0-a08c-f85a6427441a","title":"Meaning"}]'>
  <table-row>
    <table-cell><p class="slate-p ">404</p></table-cell>
    <table-cell><p class="slate-p "><code class="slate-code">AW-6013</code></p></table-cell>
    <table-cell><p class="slate-p ">Source appointment not found or is cancelled.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p ">404</p></table-cell>
    <table-cell><p class="slate-p "><code class="slate-code">AW-6014</code></p></table-cell>
    <table-cell><p class="slate-p ">Destination <code class="slate-code">to_appt_book_id</code> not found.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p ">409</p></table-cell>
    <table-cell><p class="slate-p "><code class="slate-code">AW-6020</code></p></table-cell>
    <table-cell><p class="slate-p ">Destination day or source is locked.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p ">409</p></table-cell>
    <table-cell><p class="slate-p "><code class="slate-code">AW-6021</code></p></table-cell>
    <table-cell><p class="slate-p ">Destination time slot not available.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p ">422</p></table-cell>
    <table-cell><p class="slate-p "><code class="slate-code">AW-6005</code></p></table-cell>
    <table-cell><p class="slate-p ">Destination time outside book operating hours.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p ">422</p></table-cell>
    <table-cell><p class="slate-p "><code class="slate-code">AW-6040</code></p></table-cell>
    <table-cell><p class="slate-p "><code class="slate-code">to_appointment_date</code> in the past or more than 3650 days in the future.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p ">422</p></table-cell>
    <table-cell><p class="slate-p ">(none)</p></table-cell>
    <table-cell><p class="slate-p ">Required field missing, <code class="slate-code">to_appt_book_id</code> below 1, or <code class="slate-code">is_copy</code> not 0/1 (schema validation).</p></table-cell>
  </table-row>
</Table>

For the canonical list of error codes, see [Validation, Limits & Character Handling](/validation-limits-and-character-handling).

### Example error responses

Source appointment not found (`404`):

<CodeBlock attributes='{"isFitToPage":true,"style":{},"lang":"json","label":"JSON"}'>
  <CodeLine></CodeLine>
  <CodeLine>    { "data": [], "status": false, "message": "Source appointment not found.", "support_code": "AW-6013" }</CodeLine>
</CodeBlock>

Destination book not found (`404`):

<CodeBlock attributes='{"isFitToPage":true,"style":{},"lang":"json","label":"JSON"}'>
  <CodeLine></CodeLine>
  <CodeLine>    { "data": [], "status": false, "message": "Destination appointment book not found.", "support_code": "AW-6014" }</CodeLine>
</CodeBlock>

`to_appointment_date` in the past (`422`):

<CodeBlock attributes='{"isFitToPage":true,"style":{},"lang":"json","label":"JSON"}'>
  <CodeLine></CodeLine>
  <CodeLine>    { "data": [], "status": false, "message": "to_appointment_date must not be in the past (got 2026-05-24).", "support_code": "AW-6040" }</CodeLine>
</CodeBlock>

`to_appt_book_id` below 1 (`422`):

<CodeBlock attributes='{"isFitToPage":true,"style":{},"lang":"json","label":"JSON"}'>
  <CodeLine></CodeLine>
  <CodeLine>    { "data": [], "status": false, "message": "'to_appt_book_id': ensure this value is greater than or equal to 1" }</CodeLine>
</CodeBlock>

`is_copy` not 0 or 1 (`422`):

<CodeBlock attributes='{"isFitToPage":true,"style":{},"lang":"json","label":"JSON"}'>
  <CodeLine></CodeLine>
  <CodeLine>    { "data": [], "status": false, "message": "'is_copy': ensure this value is less than or equal to 1" }</CodeLine>
</CodeBlock>

Destination time outside operating hours (`422`):

<CodeBlock attributes='{"isFitToPage":true,"style":{},"lang":"json","label":"JSON"}'>
  <CodeLine></CodeLine>
  <CodeLine>    { "data": [], "status": false, "message": "Selected time falls outside the practice's operating hours.", "support_code": "AW-6005" }</CodeLine>
</CodeBlock>

Destination slot no longer available (`409`):

<CodeBlock attributes='{"isFitToPage":true,"style":{},"lang":"json","label":"JSON"}'>
  <CodeLine></CodeLine>
  <CodeLine>    { "data": [], "status": false, "message": "The selected time slot is no longer available. Please choose a different time.", "support_code": "AW-6021" }</CodeLine>
</CodeBlock>

Important notes
---------------

*   Only non-cancelled appointments can be rescheduled. A cancelled source returns `404 AW-6013`.
    
*   `is_copy: 1` creates a new appointment at the destination without moving the original. It defaults to 0 (move) and accepts only 0 or 1.
    
*   Destination slot validation applies the same operating-hours, future-date cap, and slot-availability checks as Create appointment. `AW-6020` (destination day or source locked) returns the standard envelope with that `support_code`.
    

Quick example
-------------

<CodeBlock attributes='{"isFitToPage":true,"style":{},"lang":"plainText","label":"Plain text"}'>
  <CodeLine>curl -X POST "https://api-uat.dental4web.com.au/api/v1/appointments/85799/reschedule" \</CodeLine>
  <CodeLine>    -H "x-api-key: $API_KEY" \</CodeLine>
  <CodeLine>    -H "org-id: $ORG_ID" \</CodeLine>
  <CodeLine>    -H "Accept: application/json" \</CodeLine>
  <CodeLine>    -H "Content-Type: application/json" \</CodeLine>
  <CodeLine>    -d '{"to_appt_book_id": 5, "to_appointment_date": "2026-06-15", "to_start_time": "10:00", "is_copy": 0}' </CodeLine>
</CodeBlock>

POST Appointment Reschedule

The Financial endpoints expose invoice, payment, discount, and refund transactions, plus per-receipt detail. `GET /api/v1/financials` requires `from_date` (HTTP 422 if omitted). Records returned are raw transactions; clients are responsible for any aggregation (e.g. running balance per patient).

Financial Resources

Retrieves financial transaction records including invoices, payments, discounts, and refunds. Each record represents a single transaction with its type, amount, and associated patient, practitioner, and location.

Use cases
---------

*   Generate monthly revenue reports filtered by practitioner or location.
    
*   Reconcile practice income with accounting systems.
    
*   Track outstanding invoices for patient follow-up.
    
*   Analyse payment patterns and health fund rebate ratios.
    

Parameters
----------

<Table style="width:100%;min-width:100%" colSizes='["180px","135px","585px"]' isHeaderAdded='true' tableHeader='[{"id":"b1b2c3d4-0005-4bbb-8005-000000000001","title":"Parameter"},{"id":"b1b2c3d4-0005-4bbb-8005-000000000002","title":"Type"},{"id":"b1b2c3d4-0005-4bbb-8005-000000000003","title":"Description"}]'>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">from_date</code></p></table-cell>
    <table-cell><p class="slate-p ">date</p></table-cell>
    <table-cell><p class="slate-p ">Start of the date range. Required.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">to_date</code></p></table-cell>
    <table-cell><p class="slate-p ">date</p></table-cell>
    <table-cell><p class="slate-p ">End of the date range. Optional. Confirmed live: <code class="slate-code">from_date</code> is required on every call (a 422 if it's missing, with or without <code class="slate-code">to_date</code>); <code class="slate-code">to_date</code> alone may be omitted.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">patient_id</code></p></table-cell>
    <table-cell><p class="slate-p ">integer</p></table-cell>
    <table-cell><p class="slate-p ">Filter by patient.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">practitioner_id</code></p></table-cell>
    <table-cell><p class="slate-p ">integer</p></table-cell>
    <table-cell><p class="slate-p ">Filter by practitioner. Use <code class="slate-code">-1</code> for all practitioners.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">location_id</code></p></table-cell>
    <table-cell><p class="slate-p ">integer</p></table-cell>
    <table-cell><p class="slate-p ">Filter by location. Use <code class="slate-code">-1</code> for all locations.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">trans_type</code></p></table-cell>
    <table-cell><p class="slate-p ">integer</p></table-cell>
    <table-cell><p class="slate-p ">Filter by transaction type: <code class="slate-code">1</code> = Invoice, <code class="slate-code">2</code> = Discount, <code class="slate-code">3</code> = Refund, <code class="slate-code">4</code> = Payment. Confirmed live: an out-of-range numeric value is silently coerced to <code class="slate-code">0</code> rather than rejected; a non-numeric value is hard-rejected.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">scope</code></p></table-cell>
    <table-cell><p class="slate-p ">integer</p></table-cell>
    <table-cell><p class="slate-p ">Filter by scope: <code class="slate-code">0</code> = patient, the responsible party's own transactions (default), <code class="slate-code">1</code> = family, members resolved via <code class="slate-code">family_head_id</code>. Confirmed live: an out-of-range numeric value is silently coerced to <code class="slate-code">0</code> rather than rejected; a non-numeric value is hard-rejected.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">include</code></p></table-cell>
    <table-cell><p class="slate-p ">string</p></table-cell>
    <table-cell><p class="slate-p ">Comma-separated list of related resources to embed: <code class="slate-code">practitioners</code>, <code class="slate-code">locations</code>, <code class="slate-code">payment_types</code>. Confirmed live: each embeds the full related object under the corresponding key.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">per_page</code></p></table-cell>
    <table-cell><p class="slate-p ">integer</p></table-cell>
    <table-cell><p class="slate-p ">Results per page: see <a href="/api-response-formats">API response formats</a>.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">page</code></p></table-cell>
    <table-cell><p class="slate-p ">integer</p></table-cell>
    <table-cell><p class="slate-p ">Page number.</p></table-cell>
  </table-row>
</Table>

Response fields
---------------

<Table style="width:100%;min-width:100%" colSizes='["180px","135px","585px"]' isHeaderAdded='true' tableHeader='[{"id":"89de2c2a-df27-4c3e-a5bf-d846508275bd","title":"Field"},{"id":"11dd9220-a8bf-41ca-b425-065b9f5f83d7","title":"Type"},{"id":"7bcd97b3-997c-4f6b-ad0a-e325ca04861c","title":"Description"}]'>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">location_id</code></p></table-cell>
    <table-cell><p class="slate-p ">integer</p></table-cell>
    <table-cell><p class="slate-p ">Location identifier.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">practitioner_id</code></p></table-cell>
    <table-cell><p class="slate-p ">integer</p></table-cell>
    <table-cell><p class="slate-p ">Practitioner identifier.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">patient_id</code></p></table-cell>
    <table-cell><p class="slate-p ">integer</p></table-cell>
    <table-cell><p class="slate-p ">Patient identifier.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">date</code></p></table-cell>
    <table-cell><p class="slate-p ">date</p></table-cell>
    <table-cell><p class="slate-p ">Transaction date.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">trans_type</code></p></table-cell>
    <table-cell><p class="slate-p ">integer</p></table-cell>
    <table-cell><p class="slate-p ">Transaction type (1 = Invoice, 2 = Discount, 3 = Refund, 4 = Payment).</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">invoice_id</code></p></table-cell>
    <table-cell><p class="slate-p ">integer | null</p></table-cell>
    <table-cell><p class="slate-p ">Invoice identifier.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">receipt_id</code></p></table-cell>
    <table-cell><p class="slate-p ">integer | null</p></table-cell>
    <table-cell><p class="slate-p ">Receipt identifier.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">invoice</code></p></table-cell>
    <table-cell><p class="slate-p ">decimal</p></table-cell>
    <table-cell><p class="slate-p ">Invoice amount.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">discount</code></p></table-cell>
    <table-cell><p class="slate-p ">decimal</p></table-cell>
    <table-cell><p class="slate-p ">Discount amount.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">refund</code></p></table-cell>
    <table-cell><p class="slate-p ">decimal</p></table-cell>
    <table-cell><p class="slate-p ">Refund amount.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">receipt</code></p></table-cell>
    <table-cell><p class="slate-p ">decimal</p></table-cell>
    <table-cell><p class="slate-p ">Receipt / payment amount.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">health_fund_rebate</code></p></table-cell>
    <table-cell><p class="slate-p ">boolean</p></table-cell>
    <table-cell><p class="slate-p ">Health fund rebate flag.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">payment_type_id</code></p></table-cell>
    <table-cell><p class="slate-p ">integer | null</p></table-cell>
    <table-cell><p class="slate-p ">Payment type identifier.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">family_head_id</code></p></table-cell>
    <table-cell><p class="slate-p ">integer | null</p></table-cell>
    <table-cell><p class="slate-p ">Family head patient identifier, if the patient is linked to a family group.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">scope</code></p></table-cell>
    <table-cell><p class="slate-p ">integer</p></table-cell>
    <table-cell><p class="slate-p ">Scope value recorded against this transaction: see the <code class="slate-code">scope</code> parameter above.</p></table-cell>
  </table-row>
</Table>

Important notes
---------------

*   **Date filtering:** filters by transaction date, not the record’s last-modified timestamp.
    
*   **No** `**mode**` **parameter:** this endpoint does not support the `mode` parameter; all calls filter by transaction date.
    
*   `trans_type` and `scope` are more lenient than most numeric filters elsewhere in the API, which reject out-of-range values outright: see the Parameters table above.
    

Quick example
-------------

<CodeBlock attributes='{"isFitToPage":true,"style":{},"lang":"plainText","label":"Plain text"}'>
  <CodeLine>curl "https://api-uat.dental4web.com.au/api/v1/financials?from_date=2026-06-01&amp;to_date=2026-06-09&amp;per_page=10" \</CodeLine>
  <CodeLine>    -H "x-api-key: $API_KEY" \</CodeLine>
  <CodeLine>    -H "org-id: $ORG_ID" \</CodeLine>
  <CodeLine>    -H "Accept: application/json" </CodeLine>
</CodeBlock>

GET Financials

Retrieves detailed payment information for a specific receipt, including payment methods, banking details, and deposit status. Use this for payment reconciliation, auditing, and investigating transaction discrepancies.

Use cases
---------

*   Verify payment methods for specific transactions.
    
*   Audit banking details for reconciliation accuracy.
    
*   Investigate discrepancies between payment records and bank deposits.
    
*   Generate detailed payment reports for accounting.
    

Parameters
----------

<Table style="width:100%;min-width:100%" colSizes='["180px","135px","585px"]' isHeaderAdded='true' tableHeader='[{"id":"b1b2c3d4-0006-4bbb-8006-000000000001","title":"Parameter"},{"id":"b1b2c3d4-0006-4bbb-8006-000000000002","title":"Type"},{"id":"b1b2c3d4-0006-4bbb-8006-000000000003","title":"Description"}]'>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">receipt_id</code></p></table-cell>
    <table-cell><p class="slate-p ">integer</p></table-cell>
    <table-cell><p class="slate-p ">Path parameter. Required.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">include</code></p></table-cell>
    <table-cell><p class="slate-p ">string</p></table-cell>
    <table-cell><p class="slate-p ">Accepts six values: <code class="slate-code">patients</code>, <code class="slate-code">practitioners</code>, <code class="slate-code">locations</code>, <code class="slate-code">appt_books</code>, <code class="slate-code">items</code>, <code class="slate-code">payment_types</code>. Confirmed live: only <code class="slate-code">payment_types</code> actually embeds data (the full <code class="slate-code">payment_type</code> object). The other five are accepted without error but do not populate anything: <code class="slate-code">patients</code> is a no-op with no key added, while <code class="slate-code">practitioners</code>, <code class="slate-code">locations</code>, <code class="slate-code">appt_books</code> and <code class="slate-code">items</code> each add a stub key with a <code class="slate-code">null</code> value. An unrecognised value returns 400 with the full accepted list.</p></table-cell>
  </table-row>
</Table>

Response fields
---------------

<Table style="width:100%;min-width:100%" colSizes='["180px","135px","585px"]' isHeaderAdded='true' tableHeader='[{"id":"f8ea706d-04c4-42ef-b046-c51bce577b5d","title":"Field"},{"id":"f779f01f-45b8-407c-8c58-1783ff3d18ae","title":"Type"},{"id":"5d95a3ec-f6a9-4f0d-a3e4-db0ac12930d9","title":"Description"}]'>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">receipt_id</code></p></table-cell>
    <table-cell><p class="slate-p ">integer</p></table-cell>
    <table-cell><p class="slate-p ">Receipt identifier.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">detail_id</code></p></table-cell>
    <table-cell><p class="slate-p ">integer</p></table-cell>
    <table-cell><p class="slate-p ">Line item identifier.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">payment_type_id</code></p></table-cell>
    <table-cell><p class="slate-p ">integer</p></table-cell>
    <table-cell><p class="slate-p ">Payment method identifier.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">receipt_date</code></p></table-cell>
    <table-cell><p class="slate-p ">date</p></table-cell>
    <table-cell><p class="slate-p ">Date of receipt.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">cheque_name</code></p></table-cell>
    <table-cell><p class="slate-p ">string | null</p></table-cell>
    <table-cell><p class="slate-p ">Cheque payee name, if cheque.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">bank_name</code></p></table-cell>
    <table-cell><p class="slate-p ">string | null</p></table-cell>
    <table-cell><p class="slate-p ">Bank name, if applicable.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">banked</code></p></table-cell>
    <table-cell><p class="slate-p ">boolean</p></table-cell>
    <table-cell><p class="slate-p ">True if deposited.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">receipt_amount</code></p></table-cell>
    <table-cell><p class="slate-p ">decimal</p></table-cell>
    <table-cell><p class="slate-p ">Payment amount.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">bank_branch</code></p></table-cell>
    <table-cell><p class="slate-p ">string | null</p></table-cell>
    <table-cell><p class="slate-p ">Bank branch, if applicable.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">is_insurance</code></p></table-cell>
    <table-cell><p class="slate-p ">boolean</p></table-cell>
    <table-cell><p class="slate-p ">True if the payment includes a health fund rebate portion. Correlates with the matching <a href="/financial-resources/get-financials">financials</a> row's <code class="slate-code">health_fund_rebate</code> flag.</p></table-cell>
  </table-row>
</Table>

Important notes
---------------

*   **Not found:** returns HTTP 404 with an empty `data` array and a message indicating no matching record was found.
    
*   **Multiple records:** may return multiple detail records for split payments.
    

Quick example
-------------

<CodeBlock attributes='{"isFitToPage":true,"style":{},"lang":"plainText","label":"Plain text"}'>
  <CodeLine>curl "https://api-uat.dental4web.com.au/api/v1/receipts/12345" \</CodeLine>
  <CodeLine>    -H "x-api-key: $API_KEY" \</CodeLine>
  <CodeLine>    -H "org-id: $ORG_ID" \</CodeLine>
  <CodeLine>    -H "Accept: application/json" </CodeLine>
</CodeBlock>

GET Receipts

Retrieves the list of third-party payer accounts configured in the practice, such as health funds and other external payers used for invoicing and payment allocation.

Use cases
---------

*   Look up third-party payer accounts for invoice allocation.
    
*   Populate payer selection lists in third-party billing integrations.
    
*   Cross-reference third-party identifiers against payment and debtor records.
    

Parameters
----------

<Table style="width:100%;min-width:100%" colSizes='["180px","135px","585px"]' isHeaderAdded='true' tableHeader='[{"id":"b2c3d4e5-0007-4ccc-8007-000000000001","title":"Parameter"},{"id":"b2c3d4e5-0007-4ccc-8007-000000000002","title":"Type"},{"id":"b2c3d4e5-0007-4ccc-8007-000000000003","title":"Description"}]'>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">page</code></p></table-cell>
    <table-cell><p class="slate-p ">integer</p></table-cell>
    <table-cell><p class="slate-p ">Page number. Default: <code class="slate-code">1</code>.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">per_page</code></p></table-cell>
    <table-cell><p class="slate-p ">integer</p></table-cell>
    <table-cell><p class="slate-p ">Results per page: see <a href="/api-response-formats">API response formats</a>. Default: <code class="slate-code">10</code>.</p></table-cell>
  </table-row>
</Table>

Response fields
---------------

<Table style="width:100%;min-width:100%" colSizes='["180px","135px","585px"]' isHeaderAdded='true' tableHeader='[{"id":"b2c3d4e5-0007-4aaa-8007-000000000001","title":"Field"},{"id":"b2c3d4e5-0007-4aaa-8007-000000000002","title":"Type"},{"id":"b2c3d4e5-0007-4aaa-8007-000000000003","title":"Description"}]'>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">third_party_id</code></p></table-cell>
    <table-cell><p class="slate-p ">integer</p></table-cell>
    <table-cell><p class="slate-p ">Third-party payer identifier.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">third_party_name</code></p></table-cell>
    <table-cell><p class="slate-p ">string</p></table-cell>
    <table-cell><p class="slate-p ">Third-party payer name.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">third_party_type</code></p></table-cell>
    <table-cell><p class="slate-p ">string</p></table-cell>
    <table-cell><p class="slate-p ">Third-party payer type (e.g. health fund).</p></table-cell>
  </table-row>
</Table>

Important notes
---------------

*   **Paginated:** returns the practice's full list of configured third-party payers, paginated like other list endpoints (confirmed live: a Sandbox org returning 217 rows correctly paged with `page`/`per_page`).
    

Quick example
-------------

<CodeBlock attributes='{"isFitToPage":true,"style":{},"lang":"plainText","label":"Plain text"}'>
  <CodeLine>curl "https://api-uat.dental4web.com.au/api/v1/third-parties?per_page=10" \</CodeLine>
  <CodeLine>    -H "x-api-key: $API_KEY" \</CodeLine>
  <CodeLine>    -H "org-id: $ORG_ID" \</CodeLine>
  <CodeLine>    -H "Accept: application/json" </CodeLine>
</CodeBlock>


GET Third Parties

Retrieves outstanding debtor instalments across the practice, including balances, due dates, and third-party or bad-debt flags. Use this for accounts receivable reporting and debt collection workflows.

Use cases
---------

*   Generate accounts receivable ageing reports.
    
*   Identify overdue instalments for debt collection follow-up.
    
*   Distinguish third-party and bad-debt balances from standard patient debt.
    

Parameters
----------

<Table style="width:100%;min-width:100%" colSizes='["180px","135px","585px"]' isHeaderAdded='true' tableHeader='[{"id":"b2c3d4e5-0008-4aaa-8008-000000000001","title":"Parameter"},{"id":"b2c3d4e5-0008-4aaa-8008-000000000002","title":"Type"},{"id":"b2c3d4e5-0008-4aaa-8008-000000000003","title":"Description"}]'>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">location_id</code></p></table-cell>
    <table-cell><p class="slate-p ">integer</p></table-cell>
    <table-cell><p class="slate-p ">Filter by location.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">per_page</code></p></table-cell>
    <table-cell><p class="slate-p ">integer</p></table-cell>
    <table-cell><p class="slate-p ">Results per page: see <a href="/api-response-formats">API response formats</a>.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">page</code></p></table-cell>
    <table-cell><p class="slate-p ">integer</p></table-cell>
    <table-cell><p class="slate-p ">Page number.</p></table-cell>
  </table-row>
</Table>

Response fields
---------------

<Table style="width:100%;min-width:100%" colSizes='["180px","135px","585px"]' isHeaderAdded='true' tableHeader='[{"id":"b2c3d4e5-0008-4bbb-8008-000000000001","title":"Field"},{"id":"b2c3d4e5-0008-4bbb-8008-000000000002","title":"Type"},{"id":"b2c3d4e5-0008-4bbb-8008-000000000003","title":"Description"}]'>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">responsible_party_id</code></p></table-cell>
    <table-cell><p class="slate-p ">integer</p></table-cell>
    <table-cell><p class="slate-p ">Identifier of the party responsible for the instalment.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">invoice_id</code></p></table-cell>
    <table-cell><p class="slate-p ">integer</p></table-cell>
    <table-cell><p class="slate-p ">Invoice identifier. Use with <a href="/financial-resources/get-invoice-details">Get invoice details</a> to retrieve line items.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">instalment_number</code></p></table-cell>
    <table-cell><p class="slate-p ">integer</p></table-cell>
    <table-cell><p class="slate-p ">Instalment sequence number for the invoice.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">date_due</code></p></table-cell>
    <table-cell><p class="slate-p ">date</p></table-cell>
    <table-cell><p class="slate-p ">Date the instalment falls due.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">days_due</code></p></table-cell>
    <table-cell><p class="slate-p ">integer</p></table-cell>
    <table-cell><p class="slate-p ">Days since <code class="slate-code">date_due</code>. Negative when not yet due.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">instalment</code></p></table-cell>
    <table-cell><p class="slate-p ">decimal</p></table-cell>
    <table-cell><p class="slate-p ">Instalment amount.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">balance</code></p></table-cell>
    <table-cell><p class="slate-p ">decimal</p></table-cell>
    <table-cell><p class="slate-p ">Outstanding balance on the instalment.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">is_third_party</code></p></table-cell>
    <table-cell><p class="slate-p ">integer (0 or 1)</p></table-cell>
    <table-cell><p class="slate-p ">1 if the debt is held against a third-party payer rather than the patient, 0 otherwise. Returned as an integer, not a JSON boolean. Confirmed live.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">is_bad_debt</code></p></table-cell>
    <table-cell><p class="slate-p ">integer (0 or 1)</p></table-cell>
    <table-cell><p class="slate-p ">1 if the instalment has been written off as bad debt, 0 otherwise. Returned as an integer, not a JSON boolean. Confirmed live.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">location_id</code></p></table-cell>
    <table-cell><p class="slate-p ">integer</p></table-cell>
    <table-cell><p class="slate-p ">Location identifier.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">has_line_items</code></p></table-cell>
    <table-cell><p class="slate-p ">integer (0 or 1)</p></table-cell>
    <table-cell><p class="slate-p ">1 if <a href="/financial-resources/get-invoice-details">Get invoice details</a> has retrievable line item data for the invoice, 0 otherwise. A value of <code class="slate-code">0</code> means a details lookup for that invoice returns HTTP 404 as expected, not as an error condition. Returned as an integer, not a JSON boolean. Confirmed live.</p></table-cell>
  </table-row>
</Table>

Important notes
---------------

*   **`is_third_party`, `is_bad_debt`, `has_line_items` are integers, not booleans:** the API returns these as `0`/`1` on the wire, not JSON `true`/`false`. Code defensively if your client strictly types JSON booleans.
    
*   **No** `patient_id` **filter:** this endpoint does not accept a `patient_id` query parameter. Passing one returns HTTP 400: `"Unexpected parameters: patient_id, Please try again."`
    

Quick example
-------------

<CodeBlock attributes='{"isFitToPage":true,"style":{},"lang":"plainText","label":"Plain text"}'>
  <CodeLine>curl "https://api-uat.dental4web.com.au/api/v1/debtors?per_page=10" \</CodeLine>
  <CodeLine>    -H "x-api-key: $API_KEY" \</CodeLine>
  <CodeLine>    -H "org-id: $ORG_ID" \</CodeLine>
  <CodeLine>    -H "Accept: application/json" </CodeLine>
</CodeBlock>


GET Debtors

Retrieves a summary of a single patient's outstanding balance, including overdue and current amounts, bad debt, and open invoice counts. Use this for a quick account-standing check without retrieving individual transactions.

Use cases
---------

*   Display account balance summaries in patient-facing portals.
    
*   Flag overdue accounts before booking further appointments.
    
*   Reconcile a patient's balance without paging through individual financial transactions.
    

Parameters
----------

<Table style="width:100%;min-width:100%" colSizes='["180px","135px","585px"]' isHeaderAdded='true' tableHeader='[{"id":"b2c3d4e5-0009-4aaa-8009-000000000001","title":"Parameter"},{"id":"b2c3d4e5-0009-4aaa-8009-000000000002","title":"Type"},{"id":"b2c3d4e5-0009-4aaa-8009-000000000003","title":"Description"}]'>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">patient_id</code></p></table-cell>
    <table-cell><p class="slate-p ">integer</p></table-cell>
    <table-cell><p class="slate-p ">Path parameter. Required.</p></table-cell>
  </table-row>
</Table>

Response fields
---------------

<Table style="width:100%;min-width:100%" colSizes='["180px","135px","585px"]' isHeaderAdded='true' tableHeader='[{"id":"b2c3d4e5-0009-4bbb-8009-000000000001","title":"Field"},{"id":"b2c3d4e5-0009-4bbb-8009-000000000002","title":"Type"},{"id":"b2c3d4e5-0009-4bbb-8009-000000000003","title":"Description"}]'>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">patient_id</code></p></table-cell>
    <table-cell><p class="slate-p ">integer</p></table-cell>
    <table-cell><p class="slate-p ">Patient identifier.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">family_head_id</code></p></table-cell>
    <table-cell><p class="slate-p ">integer | null</p></table-cell>
    <table-cell><p class="slate-p ">Family head patient identifier, if the patient is linked to a family group. <code class="slate-code">null</code> is also the signal that the requested <code class="slate-code">patient_id</code> does not exist: a real patient with zero debt always has a populated <code class="slate-code">family_head_id</code>; the rest of the response otherwise looks like a normal all-zero balance.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">scope</code></p></table-cell>
    <table-cell><p class="slate-p ">integer</p></table-cell>
    <table-cell><p class="slate-p ">Scope value recorded against the balance (<code class="slate-code">0</code> = patient, <code class="slate-code">1</code> = family). This endpoint does not accept a <code class="slate-code">scope</code> query parameter to filter by it, unlike <a href="/financial-resources/get-financials">Get financials</a>: see Important notes for the exact rejection behaviour.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">total_outstanding</code></p></table-cell>
    <table-cell><p class="slate-p ">decimal</p></table-cell>
    <table-cell><p class="slate-p ">Total outstanding balance across all open invoices.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">overdue_amount</code></p></table-cell>
    <table-cell><p class="slate-p ">decimal</p></table-cell>
    <table-cell><p class="slate-p ">Portion of the balance past due, after allowing for <code class="slate-code">overdue_grace_days</code>.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">current_amount</code></p></table-cell>
    <table-cell><p class="slate-p ">decimal</p></table-cell>
    <table-cell><p class="slate-p ">Portion of the balance not yet due.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">bad_debt_amount</code></p></table-cell>
    <table-cell><p class="slate-p ">decimal</p></table-cell>
    <table-cell><p class="slate-p ">Portion of the balance written off as bad debt.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">open_invoice_count</code></p></table-cell>
    <table-cell><p class="slate-p ">integer</p></table-cell>
    <table-cell><p class="slate-p ">Number of invoices contributing to the outstanding balance.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">oldest_due_date</code></p></table-cell>
    <table-cell><p class="slate-p ">date | null</p></table-cell>
    <table-cell><p class="slate-p ">Due date of the oldest outstanding instalment.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">days_overdue</code></p></table-cell>
    <table-cell><p class="slate-p ">integer</p></table-cell>
    <table-cell><p class="slate-p ">Days since the oldest overdue instalment fell due.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">overdue_grace_days</code></p></table-cell>
    <table-cell><p class="slate-p ">integer</p></table-cell>
    <table-cell><p class="slate-p ">Number of days after an instalment's due date before it is counted as overdue.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">as_at_date</code></p></table-cell>
    <table-cell><p class="slate-p ">date</p></table-cell>
    <table-cell><p class="slate-p ">Date the balance was calculated as at.</p></table-cell>
  </table-row>
</Table>

Important notes
---------------

*   **`data` is a single-element array, not a bare object:** confirmed live: the balance summary is wrapped the same way as other list endpoints (`"data": [{ ... }]`, with a `pagination` block alongside it), not returned as a bare `"data": { ... }` object. Read `data[0]`, not `data`, directly.
    
*   **No** `scope` **filter:** this endpoint does not accept a `scope` query parameter (nor any pagination parameter: `page`/`per_page` are also rejected). Passing one returns HTTP 400: `"Unexpected parameters: scope, Please try again."`; even though the underlying data supports scoping. Do not assume parity with the `scope` parameter on <a href="/financial-resources/get-financials">Get financials</a>.
    
*   **`overdue_grace_days`:** the number of days after `date_due` before an instalment is counted as overdue in `overdue_amount` and `days_overdue`. This is a practice-configurable setting, not a fixed value; do not hard-code it.
    

Quick example
-------------

<CodeBlock attributes='{"isFitToPage":true,"style":{},"lang":"plainText","label":"Plain text"}'>
  <CodeLine>curl "https://api-uat.dental4web.com.au/api/v1/patients/12345/balance" \</CodeLine>
  <CodeLine>    -H "x-api-key: $API_KEY" \</CodeLine>
  <CodeLine>    -H "org-id: $ORG_ID" \</CodeLine>
  <CodeLine>    -H "Accept: application/json" </CodeLine>
</CodeBlock>


GET Patient Balance

Retrieves line item detail for a single invoice, including procedure codes, quantities, and per-item amounts. Use this to break down an invoice total into its constituent treatment items.

Use cases
---------

*   Display itemised invoice breakdowns to patients or third-party payers.
    
*   Reconcile invoice totals against individual treatment items.
    
*   Support insurance claim preparation with per-item insurance and VAT amounts.
    

Parameters
----------

<Table style="width:100%;min-width:100%" colSizes='["180px","135px","585px"]' isHeaderAdded='true' tableHeader='[{"id":"b2c3d4e5-0010-4aaa-8010-000000000001","title":"Parameter"},{"id":"b2c3d4e5-0010-4aaa-8010-000000000002","title":"Type"},{"id":"b2c3d4e5-0010-4aaa-8010-000000000003","title":"Description"}]'>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">invoice_id</code></p></table-cell>
    <table-cell><p class="slate-p ">integer</p></table-cell>
    <table-cell><p class="slate-p ">Path parameter. Required.</p></table-cell>
  </table-row>
</Table>

Response fields
---------------

<Table style="width:100%;min-width:100%" colSizes='["180px","135px","585px"]' isHeaderAdded='true' tableHeader='[{"id":"b2c3d4e5-0010-4bbb-8010-000000000001","title":"Field"},{"id":"b2c3d4e5-0010-4bbb-8010-000000000002","title":"Type"},{"id":"b2c3d4e5-0010-4bbb-8010-000000000003","title":"Description"}]'>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">invoice_id</code></p></table-cell>
    <table-cell><p class="slate-p ">integer</p></table-cell>
    <table-cell><p class="slate-p ">Invoice identifier.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">treat_id</code></p></table-cell>
    <table-cell><p class="slate-p ">integer | null</p></table-cell>
    <table-cell><p class="slate-p ">Associated treatment identifier.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">item_date</code></p></table-cell>
    <table-cell><p class="slate-p ">date</p></table-cell>
    <table-cell><p class="slate-p ">Date the line item was performed.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">item_code</code></p></table-cell>
    <table-cell><p class="slate-p ">string</p></table-cell>
    <table-cell><p class="slate-p ">Procedure code for the line item.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">tooth</code></p></table-cell>
    <table-cell><p class="slate-p ">string | null</p></table-cell>
    <table-cell><p class="slate-p ">Tooth reference, where applicable.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">description</code></p></table-cell>
    <table-cell><p class="slate-p ">string</p></table-cell>
    <table-cell><p class="slate-p ">Line item description.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">quantity</code></p></table-cell>
    <table-cell><p class="slate-p ">integer</p></table-cell>
    <table-cell><p class="slate-p ">Quantity of the item billed.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">unit_price</code></p></table-cell>
    <table-cell><p class="slate-p ">decimal</p></table-cell>
    <table-cell><p class="slate-p ">Price per unit before discount.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">discount</code></p></table-cell>
    <table-cell><p class="slate-p ">decimal</p></table-cell>
    <table-cell><p class="slate-p ">Discount applied to the line item.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">amount</code></p></table-cell>
    <table-cell><p class="slate-p ">decimal</p></table-cell>
    <table-cell><p class="slate-p ">Net line item amount.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">vat_amount</code></p></table-cell>
    <table-cell><p class="slate-p ">decimal</p></table-cell>
    <table-cell><p class="slate-p ">VAT/GST amount included in the line item.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">insurance_part</code></p></table-cell>
    <table-cell><p class="slate-p ">decimal</p></table-cell>
    <table-cell><p class="slate-p ">Portion of the line item covered by insurance.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">provider_code</code></p></table-cell>
    <table-cell><p class="slate-p ">string | null</p></table-cell>
    <table-cell><p class="slate-p ">Provider code associated with the line item.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">patient_id</code></p></table-cell>
    <table-cell><p class="slate-p ">integer</p></table-cell>
    <table-cell><p class="slate-p ">Patient identifier.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">date_due</code></p></table-cell>
    <table-cell><p class="slate-p ">date | null</p></table-cell>
    <table-cell><p class="slate-p ">Due date of the instalment associated with this line item. Confirmed live: can be <code class="slate-code">null</code>.</p></table-cell>
  </table-row>
</Table>

Important notes
---------------

*   **Expected 404s:** a 404 response is expected and normal for invoices whose matching <a href="/financial-resources/get-debtors">Get debtors</a> row has `has_line_items` set to `0` (an integer, not a JSON boolean, see Get debtors). It does not indicate an error condition, only that no line item detail is available for that invoice.
    

Quick example
-------------

<CodeBlock attributes='{"isFitToPage":true,"style":{},"lang":"plainText","label":"Plain text"}'>
  <CodeLine>curl "https://api-uat.dental4web.com.au/api/v1/invoices/24050/details" \</CodeLine>
  <CodeLine>    -H "x-api-key: $API_KEY" \</CodeLine>
  <CodeLine>    -H "org-id: $ORG_ID" \</CodeLine>
  <CodeLine>    -H "Accept: application/json" </CodeLine>
</CodeBlock>


GET Invoice Details

The Patient endpoints expose patient demographics, recall schedules, and a separate extended-fields variant containing practice-specific custom attributes. Note the underscore in `patients_extended` (not `patients-extended`)

<span style="color:#434343">This resource is designed to align with the FHIR standard, making it easier to integrate with healthcare systems and ensure interoperability.</span> FHIR R4 output is available via the dedicated `/api/v1/fhir/<resource>` endpoint variants, see [FHIR Capabilities](/fhir-capabilities).

Patient Resources

Retrieves patient demographic records, with optional filtering by name, practitioner, location, or contact details. Email and mobile prefix searching is supported for flexible patient lookup.

Use cases
---------

*   Search for patients by name before booking appointments.
    
*   Sync patient demographics to an external CRM or practice management system.
    
*   Build patient directories for reception dashboards.
    
*   Perform incremental data synchronisation using date-range filters.
    

Parameters
----------

<Table style="width:100%;min-width:100%" colSizes='["180px","135px","585px"]' isHeaderAdded='true' tableHeader='[{"id":"f55a4ab4-3601-4102-8b28-8cc61c929ce9","title":"Parameter"},{"id":"25a54e62-7b66-44d5-b1c4-2d61e16440e6","title":"Type"},{"id":"e045d4ce-fd41-4518-9849-48338cc48b59","title":"Description"}]'>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">patient_id</code></p></table-cell>
    <table-cell><p class="slate-p ">integer</p></table-cell>
    <table-cell><p class="slate-p ">Filter to a specific patient. Counts as a narrowing filter: bypasses the default recency window and the broad-fanout cap.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">patient_card</code></p></table-cell>
    <table-cell><p class="slate-p ">string</p></table-cell>
    <table-cell><p class="slate-p ">Filter by patient card number. Counts as a narrowing filter: bypasses the default recency window and the broad-fanout cap.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">first_name</code></p></table-cell>
    <table-cell><p class="slate-p ">string</p></table-cell>
    <table-cell><p class="slate-p ">Filter by first name. Exact match.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">surname</code></p></table-cell>
    <table-cell><p class="slate-p ">string</p></table-cell>
    <table-cell><p class="slate-p ">Filter by surname. Exact match.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">date_of_birth</code></p></table-cell>
    <table-cell><p class="slate-p ">string</p></table-cell>
    <table-cell><p class="slate-p ">Filter by patient date of birth (<code class="slate-code">YYYY-MM-DD</code>). Counts as a narrowing filter: bypasses the default recency window and the broad-fanout cap, the same as <code class="slate-code">patient_id</code> / <code class="slate-code">patient_card</code>.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">practitioner_id</code></p></table-cell>
    <table-cell><p class="slate-p ">integer</p></table-cell>
    <table-cell><p class="slate-p ">Filter by preferred practitioner. Use <code class="slate-code">-1</code> for all practitioners.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">location_id</code></p></table-cell>
    <table-cell><p class="slate-p ">integer</p></table-cell>
    <table-cell><p class="slate-p ">Filter by preferred location. Use <code class="slate-code">-1</code> for all locations.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">include</code></p></table-cell>
    <table-cell><p class="slate-p ">string</p></table-cell>
    <table-cell><p class="slate-p ">Comma-separated list of related resources to embed: <code class="slate-code">practitioners</code>, <code class="slate-code">locations</code>, or both (<code class="slate-code">practitioners,locations</code>). Confirmed live: each embeds the related object under a singular key (<code class="slate-code">practitioner</code>, <code class="slate-code">location</code>) on every returned row. See Important notes for the embedded field list.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">email</code></p></table-cell>
    <table-cell><p class="slate-p ">string</p></table-cell>
    <table-cell><p class="slate-p ">Filter by patient email address. See Important notes for matching behaviour.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">mobile</code></p></table-cell>
    <table-cell><p class="slate-p ">string</p></table-cell>
    <table-cell><p class="slate-p ">Filter by patient mobile number. See Important notes for matching behaviour.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">from_date</code></p></table-cell>
    <table-cell><p class="slate-p ">string</p></table-cell>
    <table-cell><p class="slate-p ">Start of the date range filter (<code class="slate-code">YYYY-MM-DD</code>). See Important notes for default behaviour.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">to_date</code></p></table-cell>
    <table-cell><p class="slate-p ">string</p></table-cell>
    <table-cell><p class="slate-p ">End of the date range filter (<code class="slate-code">YYYY-MM-DD</code>). See Important notes for default behaviour.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">per_page</code></p></table-cell>
    <table-cell><p class="slate-p ">integer</p></table-cell>
    <table-cell><p class="slate-p ">Results per page (default 10, maximum 500): see <a href="/api-response-formats">API response formats</a>.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">page</code></p></table-cell>
    <table-cell><p class="slate-p ">integer</p></table-cell>
    <table-cell><p class="slate-p ">Page number.</p></table-cell>
  </table-row>
</Table>

Response fields
---------------

<Table style="width:100%;min-width:100%" colSizes='["180px","135px","585px"]' isHeaderAdded='true' tableHeader='[{"id":"f9dc9842-ee01-41a4-bd8b-3fb1d4cd62ba","title":"Field"},{"id":"cb1e3669-91fd-488c-be76-23c90fe978a3","title":"Type"},{"id":"e08c146e-b641-4c54-8278-5e7240462545","title":"Description"}]'>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">patient_id</code></p></table-cell>
    <table-cell><p class="slate-p ">integer</p></table-cell>
    <table-cell><p class="slate-p ">Patient identifier.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">family_head_id</code></p></table-cell>
    <table-cell><p class="slate-p ">integer</p></table-cell>
    <table-cell><p class="slate-p ">Family group head identifier.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">patient_card</code></p></table-cell>
    <table-cell><p class="slate-p ">string</p></table-cell>
    <table-cell><p class="slate-p ">Patient card number.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">patient_status</code></p></table-cell>
    <table-cell><p class="slate-p ">string</p></table-cell>
    <table-cell><p class="slate-p ">Status (Active/Inactive/Deceased).</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">title</code></p></table-cell>
    <table-cell><p class="slate-p ">string</p></table-cell>
    <table-cell><p class="slate-p ">Title (Mr/Mrs/Ms/Dr).</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">first_name</code></p></table-cell>
    <table-cell><p class="slate-p ">string</p></table-cell>
    <table-cell><p class="slate-p ">First name.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">middle_name</code></p></table-cell>
    <table-cell><p class="slate-p ">string | null</p></table-cell>
    <table-cell><p class="slate-p ">Middle name.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">surname</code></p></table-cell>
    <table-cell><p class="slate-p ">string</p></table-cell>
    <table-cell><p class="slate-p ">Surname.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">preferred_name</code></p></table-cell>
    <table-cell><p class="slate-p ">string | null</p></table-cell>
    <table-cell><p class="slate-p ">Preferred name or nickname.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">address1</code></p></table-cell>
    <table-cell><p class="slate-p ">string</p></table-cell>
    <table-cell><p class="slate-p ">Address line 1.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">address2</code></p></table-cell>
    <table-cell><p class="slate-p ">string | null</p></table-cell>
    <table-cell><p class="slate-p ">Address line 2.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">postcode</code></p></table-cell>
    <table-cell><p class="slate-p ">string</p></table-cell>
    <table-cell><p class="slate-p ">Postal code.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">suburb</code></p></table-cell>
    <table-cell><p class="slate-p ">string</p></table-cell>
    <table-cell><p class="slate-p ">Suburb or city.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">state</code></p></table-cell>
    <table-cell><p class="slate-p ">string</p></table-cell>
    <table-cell><p class="slate-p ">State or territory.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">gender</code></p></table-cell>
    <table-cell><p class="slate-p ">string</p></table-cell>
    <table-cell><p class="slate-p ">Gender.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">birthdate</code></p></table-cell>
    <table-cell><p class="slate-p ">date</p></table-cell>
    <table-cell><p class="slate-p ">Date of birth.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">email</code></p></table-cell>
    <table-cell><p class="slate-p ">string | null</p></table-cell>
    <table-cell><p class="slate-p ">Email address.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">phone</code></p></table-cell>
    <table-cell><p class="slate-p ">string | null</p></table-cell>
    <table-cell><p class="slate-p ">Home phone.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">mobile</code></p></table-cell>
    <table-cell><p class="slate-p ">string | null</p></table-cell>
    <table-cell><p class="slate-p ">Mobile phone.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">new_patient_date</code></p></table-cell>
    <table-cell><p class="slate-p ">date</p></table-cell>
    <table-cell><p class="slate-p ">First visit date.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">latest_seen_date</code></p></table-cell>
    <table-cell><p class="slate-p ">date | null</p></table-cell>
    <table-cell><p class="slate-p ">Most recent visit.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">practitioner_id</code></p></table-cell>
    <table-cell><p class="slate-p ">integer</p></table-cell>
    <table-cell><p class="slate-p ">Preferred practitioner.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">location_id</code></p></table-cell>
    <table-cell><p class="slate-p ">integer</p></table-cell>
    <table-cell><p class="slate-p ">Preferred location.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">health_fund_name</code></p></table-cell>
    <table-cell><p class="slate-p ">string | null</p></table-cell>
    <table-cell><p class="slate-p ">Health fund name.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">insurance_fee_level</code></p></table-cell>
    <table-cell><p class="slate-p ">string | null</p></table-cell>
    <table-cell><p class="slate-p ">Fee level.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">med_hist_last_updated</code></p></table-cell>
    <table-cell><p class="slate-p ">date | null</p></table-cell>
    <table-cell><p class="slate-p ">Medical history update date.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">referring_patient_id</code></p></table-cell>
    <table-cell><p class="slate-p ">integer | null</p></table-cell>
    <table-cell><p class="slate-p ">Referring patient.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">referral_source</code></p></table-cell>
    <table-cell><p class="slate-p ">string | null</p></table-cell>
    <table-cell><p class="slate-p ">Referral source.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">referral_date</code></p></table-cell>
    <table-cell><p class="slate-p ">date | null</p></table-cell>
    <table-cell><p class="slate-p ">Referral date.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">created_date</code></p></table-cell>
    <table-cell><p class="slate-p ">datetime</p></table-cell>
    <table-cell><p class="slate-p ">Record creation timestamp.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">updated_date</code></p></table-cell>
    <table-cell><p class="slate-p ">datetime</p></table-cell>
    <table-cell><p class="slate-p ">Record last-modified timestamp.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">metadata</code></p></table-cell>
    <table-cell><p class="slate-p ">object</p></table-cell>
    <table-cell><p class="slate-p ">Informational fields describing capping, fallback, and default-window behaviour applied to this request. See <a href="/api-response-formats">API Response Formats</a> for the full field list.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">pagination</code></p></table-cell>
    <table-cell><p class="slate-p ">object</p></table-cell>
    <table-cell><p class="slate-p ">Paging details for this result set: <code class="slate-code">page</code>, <code class="slate-code">per_page</code>, <code class="slate-code">total_rows</code>, <code class="slate-code">total_pages</code>. See <a href="/api-response-formats">API Response Formats</a> for the full field list.</p></table-cell>
  </table-row>
</Table>

Important notes
---------------

*   **Check `metadata.patients_default_window_injected` and `metadata.patient_fanout_cap_applied` on this endpoint:** if either is `true`, this response is not the complete result set. Confirmed live on a broad, unfiltered call: both flags returned `true`, with `metadata.patient_fanout_cap_value: 10000` and a matching `warnings[]` entry. See [API Response Formats](/api-response-formats).
    
*   **Auto-injected recency window:** when called without `patient_id`, `patient_card`, `date_of_birth`, or a complete `from_date`/`to_date` window, this endpoint auto-injects a 90-day recency window and applies the 10,000-row broad-fanout cap. At least one query parameter must still be supplied to reach this endpoint at all; a genuinely empty `GET /patients` (zero query parameters) returns `400` before this injection logic runs.
    
*   To bypass the cap, supply `patient_id`, `patient_card`, or `date_of_birth`, or both `from_date` and `to_date` spanning 370 days or fewer (the sync-window path).
    
*   **Date filtering:** see [Filtering & Date Ranges](/filtering-and-date-ranges).
    
*   **Wildcard values:** use `practitioner_id=-1` for all practitioners and `location_id=-1` for all locations.
    
*   **Include relations:** `include=practitioners` and `include=locations` are supported, individually or combined (`include=practitioners,locations`). Confirmed live: the embedded objects use the singular keys `practitioner` and `location`. `practitioner` contains `practitioner_id`, `is_active`, `practitioner_code`, `full_name`, `first_name`, `surname`, `title`, `role`, `location_id`, `provider_number`, `qualifications`, `appt_book_id`, `updated_date`. `location` contains `location_id`, `location_name`, `address`, `phone`, `email`, `is_active`, `updated_date`.
    
*   **Email/mobile search:** prefix matching is supported (for example, `email=john@` matches all emails starting with “john@”).
    
*   **Extended detail:** to retrieve extended patient detail (custom fields, communication preferences, and so on), use `GET /patients/{patient_id}` for the standard surface or `GET /patients_extended/{patient_id}` for the extended surface. The list-form `/patients_extended` endpoint is not available; it is detail-fetch only by `patient_id` in the path.
    

Quick example
-------------

<CodeBlock attributes='{"isFitToPage":true,"style":{},"lang":"plainText","label":"Plain text"}'>
  <CodeLine>curl "https://api-uat.dental4web.com.au/api/v1/patients?from_date=2026-05-09&amp;to_date=2026-06-09&amp;per_page=10" \</CodeLine>
  <CodeLine>    -H "x-api-key: $API_KEY" \</CodeLine>
  <CodeLine>    -H "org-id: $ORG_ID" \</CodeLine>
  <CodeLine>    -H "Accept: application/json" </CodeLine>
</CodeBlock>

GET Patients

Retrieves the complete demographic profile for a single patient by their unique identifier. Use this when you need full patient details for clinical workflows or after receiving a patient reference from another endpoint.

Use cases
---------

*   Look up patient details from a notification or webhook reference.
    
*   Display comprehensive patient information in clinical applications.
    
*   Verify patient data before sending automated communications.
    
*   Retrieve patient context for appointment booking flows.
    

Response fields
---------------

<Table style="width:100%;min-width:100%" colSizes='["180px","135px","585px"]' isHeaderAdded='true' tableHeader='[{"id":"f319e70a-3a60-4d0d-b4fd-a76572a67727","title":"Field"},{"id":"a37af39e-d213-4fb2-9f47-2d923b219c88","title":"Type"},{"id":"a79f31c1-0b83-4b4b-ace9-b9ac5ce1d53e","title":"Description"}]'>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">patient_id</code></p></table-cell>
    <table-cell><p class="slate-p ">integer</p></table-cell>
    <table-cell><p class="slate-p ">Patient identifier.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">family_head_id</code></p></table-cell>
    <table-cell><p class="slate-p ">integer</p></table-cell>
    <table-cell><p class="slate-p ">Family group head identifier.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">patient_card</code></p></table-cell>
    <table-cell><p class="slate-p ">string</p></table-cell>
    <table-cell><p class="slate-p ">Patient card number.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">patient_status</code></p></table-cell>
    <table-cell><p class="slate-p ">string</p></table-cell>
    <table-cell><p class="slate-p ">Status (Active/Inactive/Deceased).</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">title</code></p></table-cell>
    <table-cell><p class="slate-p ">string</p></table-cell>
    <table-cell><p class="slate-p ">Title (Mr/Mrs/Ms/Dr).</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">first_name</code></p></table-cell>
    <table-cell><p class="slate-p ">string</p></table-cell>
    <table-cell><p class="slate-p ">First name.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">middle_name</code></p></table-cell>
    <table-cell><p class="slate-p ">string | null</p></table-cell>
    <table-cell><p class="slate-p ">Middle name.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">surname</code></p></table-cell>
    <table-cell><p class="slate-p ">string</p></table-cell>
    <table-cell><p class="slate-p ">Surname.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">preferred_name</code></p></table-cell>
    <table-cell><p class="slate-p ">string | null</p></table-cell>
    <table-cell><p class="slate-p ">Preferred name or nickname.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">address1</code></p></table-cell>
    <table-cell><p class="slate-p ">string</p></table-cell>
    <table-cell><p class="slate-p ">Address line 1.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">address2</code></p></table-cell>
    <table-cell><p class="slate-p ">string | null</p></table-cell>
    <table-cell><p class="slate-p ">Address line 2.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">postcode</code></p></table-cell>
    <table-cell><p class="slate-p ">string</p></table-cell>
    <table-cell><p class="slate-p ">Postal code.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">suburb</code></p></table-cell>
    <table-cell><p class="slate-p ">string</p></table-cell>
    <table-cell><p class="slate-p ">Suburb or city.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">state</code></p></table-cell>
    <table-cell><p class="slate-p ">string</p></table-cell>
    <table-cell><p class="slate-p ">State or territory.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">gender</code></p></table-cell>
    <table-cell><p class="slate-p ">string</p></table-cell>
    <table-cell><p class="slate-p ">Gender.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">birthdate</code></p></table-cell>
    <table-cell><p class="slate-p ">date</p></table-cell>
    <table-cell><p class="slate-p ">Date of birth.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">email</code></p></table-cell>
    <table-cell><p class="slate-p ">string | null</p></table-cell>
    <table-cell><p class="slate-p ">Email address.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">phone</code></p></table-cell>
    <table-cell><p class="slate-p ">string | null</p></table-cell>
    <table-cell><p class="slate-p ">Home phone.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">mobile</code></p></table-cell>
    <table-cell><p class="slate-p ">string | null</p></table-cell>
    <table-cell><p class="slate-p ">Mobile phone.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">new_patient_date</code></p></table-cell>
    <table-cell><p class="slate-p ">date</p></table-cell>
    <table-cell><p class="slate-p ">First visit date.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">latest_seen_date</code></p></table-cell>
    <table-cell><p class="slate-p ">date | null</p></table-cell>
    <table-cell><p class="slate-p ">Most recent visit.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">practitioner_id</code></p></table-cell>
    <table-cell><p class="slate-p ">integer</p></table-cell>
    <table-cell><p class="slate-p ">Preferred practitioner.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">location_id</code></p></table-cell>
    <table-cell><p class="slate-p ">integer</p></table-cell>
    <table-cell><p class="slate-p ">Preferred location.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">health_fund_name</code></p></table-cell>
    <table-cell><p class="slate-p ">string | null</p></table-cell>
    <table-cell><p class="slate-p ">Health fund name.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">insurance_fee_level</code></p></table-cell>
    <table-cell><p class="slate-p ">string | null</p></table-cell>
    <table-cell><p class="slate-p ">Fee level.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">med_hist_last_updated</code></p></table-cell>
    <table-cell><p class="slate-p ">date | null</p></table-cell>
    <table-cell><p class="slate-p ">Medical history update date.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">referring_patient_id</code></p></table-cell>
    <table-cell><p class="slate-p ">integer | null</p></table-cell>
    <table-cell><p class="slate-p ">Referring patient.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">referral_source</code></p></table-cell>
    <table-cell><p class="slate-p ">string | null</p></table-cell>
    <table-cell><p class="slate-p ">Referral source.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">referral_date</code></p></table-cell>
    <table-cell><p class="slate-p ">date | null</p></table-cell>
    <table-cell><p class="slate-p ">Referral date.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">created_date</code></p></table-cell>
    <table-cell><p class="slate-p ">datetime</p></table-cell>
    <table-cell><p class="slate-p ">Record creation timestamp.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">updated_date</code></p></table-cell>
    <table-cell><p class="slate-p ">datetime</p></table-cell>
    <table-cell><p class="slate-p ">Record last-modified timestamp.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">metadata</code></p></table-cell>
    <table-cell><p class="slate-p ">object</p></table-cell>
    <table-cell><p class="slate-p ">Informational fields describing capping, fallback, and default-window behaviour applied to this request. See <a href="/api-response-formats">API Response Formats</a> for the full field list.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">pagination</code></p></table-cell>
    <table-cell><p class="slate-p ">object</p></table-cell>
    <table-cell><p class="slate-p ">Paging details for this result set: <code class="slate-code">page</code>, <code class="slate-code">per_page</code>, <code class="slate-code">total_rows</code>, <code class="slate-code">total_pages</code>. See <a href="/api-response-formats">API Response Formats</a> for the full field list.</p></table-cell>
  </table-row>
</Table>

Important notes
---------------

*   **Path parameter:** `patient_id` is required and must be a valid integer.
    
*   **Not found:** returns 404 if the patient does not exist.
    

Quick example
-------------

<CodeBlock attributes='{"isFitToPage":true,"style":{},"lang":"plainText","label":"Plain text"}'>
  <CodeLine>curl "https://api-uat.dental4web.com.au/api/v1/patients/72" \</CodeLine>
  <CodeLine>    -H "x-api-key: $API_KEY" \</CodeLine>
  <CodeLine>    -H "org-id: $ORG_ID" \</CodeLine>
  <CodeLine>    -H "Accept: application/json" </CodeLine>
</CodeBlock>

GET Patient By ID

Retrieves recall (reminder) records for a specific patient. Recalls represent scheduled follow-up appointments such as 6-month check-ups, hygiene appointments, or treatment follow-ups.

Use cases
---------

*   Display upcoming recalls in patient portals.
    
*   Integrate recall dates with appointment booking systems.
    
*   Generate recall history reports for patient communication workflows.
    
*   Build automated recall reminder integrations.
    

Parameters
----------

<Table style="width:100%;min-width:100%" colSizes='["180px","135px","585px"]' isHeaderAdded='true' tableHeader='[{"id":"de63dd3d-d2aa-4157-997b-de8147665195","title":"Parameter"},{"id":"f199e333-bbb1-4bbd-b183-e9d37226e1f9","title":"Type"},{"id":"9499cec8-83fa-4e4d-b464-b5139c35d8aa","title":"Description"}]'>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">patient_id</code></p></table-cell>
    <table-cell><p class="slate-p ">integer</p></table-cell>
    <table-cell><p class="slate-p ">Required. Path parameter: the unique identifier of the patient whose recalls to retrieve.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">from_date</code></p></table-cell>
    <table-cell><p class="slate-p ">string</p></table-cell>
    <table-cell><p class="slate-p ">Start of the date range filter (<code class="slate-code">YYYY-MM-DD</code>).</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">to_date</code></p></table-cell>
    <table-cell><p class="slate-p ">string</p></table-cell>
    <table-cell><p class="slate-p ">End of the date range filter (<code class="slate-code">YYYY-MM-DD</code>).</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">mode</code></p></table-cell>
    <table-cell><p class="slate-p ">integer</p></table-cell>
    <table-cell><p class="slate-p ">Controls date filtering behaviour: <code class="slate-code">0</code> (default) filters by business date, <code class="slate-code">1</code> filters by modification timestamp for sync/delta operations. See <a href="/filtering-and-date-ranges">Filtering &amp; Date Ranges</a>.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">include</code></p></table-cell>
    <table-cell><p class="slate-p ">string</p></table-cell>
    <table-cell><p class="slate-p ">Comma-separated list of related resources to embed: <code class="slate-code">practitioners</code>, <code class="slate-code">locations</code>, or both (<code class="slate-code">practitioners,locations</code>). Confirmed live: each embeds the related object under a singular key (<code class="slate-code">practitioner</code>, <code class="slate-code">location</code>) on every returned row. See Important notes for the embedded field list.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">per_page</code></p></table-cell>
    <table-cell><p class="slate-p ">integer</p></table-cell>
    <table-cell><p class="slate-p ">Results per page (default 10, maximum 500): see <a href="/api-response-formats">API response formats</a>.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">page</code></p></table-cell>
    <table-cell><p class="slate-p ">integer</p></table-cell>
    <table-cell><p class="slate-p ">Page number.</p></table-cell>
  </table-row>
</Table>

Response fields
---------------

<Table style="width:100%;min-width:100%" colSizes='["180px","135px","585px"]' isHeaderAdded='true' tableHeader='[{"id":"099ceaea-2d4b-4d12-8beb-b12268460886","title":"Field"},{"id":"74e88401-9fb2-4ec0-baaa-012eda11874f","title":"Type"},{"id":"8abd932b-725d-4abc-bad3-019b6239db9d","title":"Description"}]'>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">recall_type_id</code></p></table-cell>
    <table-cell><p class="slate-p ">integer</p></table-cell>
    <table-cell><p class="slate-p ">Recall type identifier.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">patient_id</code></p></table-cell>
    <table-cell><p class="slate-p ">integer</p></table-cell>
    <table-cell><p class="slate-p ">Patient identifier.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">recall_date</code></p></table-cell>
    <table-cell><p class="slate-p ">date</p></table-cell>
    <table-cell><p class="slate-p ">Scheduled recall date.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">reminder_date</code></p></table-cell>
    <table-cell><p class="slate-p ">date</p></table-cell>
    <table-cell><p class="slate-p ">Reminder sent or due date.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">reminder_type</code></p></table-cell>
    <table-cell><p class="slate-p ">string</p></table-cell>
    <table-cell><p class="slate-p ">Reminder method (SMS, Email, Letter).</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">reminder_no</code></p></table-cell>
    <table-cell><p class="slate-p ">integer</p></table-cell>
    <table-cell><p class="slate-p ">Reminder sequence number.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">practitioner_id</code></p></table-cell>
    <table-cell><p class="slate-p ">integer</p></table-cell>
    <table-cell><p class="slate-p ">Associated practitioner.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">location_id</code></p></table-cell>
    <table-cell><p class="slate-p ">integer</p></table-cell>
    <table-cell><p class="slate-p ">Associated location.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">created_date</code></p></table-cell>
    <table-cell><p class="slate-p ">datetime</p></table-cell>
    <table-cell><p class="slate-p ">Record creation timestamp.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">updated_date</code></p></table-cell>
    <table-cell><p class="slate-p ">datetime</p></table-cell>
    <table-cell><p class="slate-p ">Record last-modified timestamp.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">metadata</code></p></table-cell>
    <table-cell><p class="slate-p ">object</p></table-cell>
    <table-cell><p class="slate-p ">Informational fields describing capping, fallback, and default-window behaviour applied to this request. See <a href="/api-response-formats">API Response Formats</a> for the full field list.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">pagination</code></p></table-cell>
    <table-cell><p class="slate-p ">object</p></table-cell>
    <table-cell><p class="slate-p ">Paging details for this result set: <code class="slate-code">page</code>, <code class="slate-code">per_page</code>, <code class="slate-code">total_rows</code>, <code class="slate-code">total_pages</code>. See <a href="/api-response-formats">API Response Formats</a> for the full field list.</p></table-cell>
  </table-row>
</Table>

Important notes
---------------

*   **Date filtering:** supports the `mode` parameter: see [Filtering & Date Ranges](/filtering-and-date-ranges).
    
*   **Patient scope:** only returns recalls for the specified patient.
    
*   **Include relations:** `include=practitioners` and `include=locations` are supported, individually or combined (`include=practitioners,locations`). Confirmed live: the embedded objects use the singular keys `practitioner` and `location`, with the same shape as [GET Patients](/patient-resources/get-patients).
    

Quick example
-------------

<CodeBlock attributes='{"isFitToPage":true,"style":{},"lang":"plainText","label":"Plain text"}'>
  <CodeLine>curl "https://api-uat.dental4web.com.au/api/v1/patients/72/recalls" \</CodeLine>
  <CodeLine>    -H "x-api-key: $API_KEY" \</CodeLine>
  <CodeLine>    -H "org-id: $ORG_ID" \</CodeLine>
  <CodeLine>    -H "Accept: application/json" </CodeLine>
</CodeBlock>

GET Patient Recalls

Retrieves extended data for a single patient by their unique identifier, including all standard fields plus practice-specific custom attributes. This is a PID-only detail-fetch: other parameters are not accepted at this endpoint. Use `GET /patients` for broad search.

Use cases
---------

*   Retrieve a complete patient profile, including custom fields, for clinical display.
    
*   Access practice-specific metadata for a known patient.
    
*   Build patient detail views with extended information.
    

Response fields
---------------

<Table style="width:100%;min-width:100%" colSizes='["180px","135px","585px"]' isHeaderAdded='true' tableHeader='[{"id":"990fd87d-951c-4a87-868d-9eedd844e77c","title":"Field"},{"id":"1060c32b-adea-4f89-b440-76e4bfcbaac6","title":"Type"},{"id":"e3b9d0fa-9b11-42ae-8803-98ddfefd3089","title":"Description"}]'>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">patient_id</code></p></table-cell>
    <table-cell><p class="slate-p ">integer</p></table-cell>
    <table-cell><p class="slate-p ">Primary identifier.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">family_head_id</code></p></table-cell>
    <table-cell><p class="slate-p ">integer</p></table-cell>
    <table-cell><p class="slate-p ">Head of household patient ID.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">patient_card</code></p></table-cell>
    <table-cell><p class="slate-p ">string</p></table-cell>
    <table-cell><p class="slate-p ">Patient card number.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">family_role</code></p></table-cell>
    <table-cell><p class="slate-p ">string</p></table-cell>
    <table-cell><p class="slate-p ">Role in family (for example, 'Family Head').</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">patient_status</code></p></table-cell>
    <table-cell><p class="slate-p ">string</p></table-cell>
    <table-cell><p class="slate-p ">'Active' or 'Inactive'.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">patient_category</code></p></table-cell>
    <table-cell><p class="slate-p ">string | null</p></table-cell>
    <table-cell><p class="slate-p ">Practice-defined patient category name (set in the practice's category list). Not the same field as <code class="slate-code">patient_status</code>: a patient can have any category regardless of active/inactive status.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">title</code></p></table-cell>
    <table-cell><p class="slate-p ">string</p></table-cell>
    <table-cell><p class="slate-p ">Title (Mr, Mrs, Dr, etc.).</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">first_name</code></p></table-cell>
    <table-cell><p class="slate-p ">string</p></table-cell>
    <table-cell><p class="slate-p ">Given name.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">middle_name</code></p></table-cell>
    <table-cell><p class="slate-p ">string</p></table-cell>
    <table-cell><p class="slate-p ">Middle name.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">surname</code></p></table-cell>
    <table-cell><p class="slate-p ">string</p></table-cell>
    <table-cell><p class="slate-p ">Family or last name.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">preferred_name</code></p></table-cell>
    <table-cell><p class="slate-p ">string</p></table-cell>
    <table-cell><p class="slate-p ">Nickname.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">gender</code></p></table-cell>
    <table-cell><p class="slate-p ">string</p></table-cell>
    <table-cell><p class="slate-p ">'male', 'female', or null.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">ethnicity</code></p></table-cell>
    <table-cell><p class="slate-p ">string | null</p></table-cell>
    <table-cell><p class="slate-p ">Ethnicity.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">birthdate</code></p></table-cell>
    <table-cell><p class="slate-p ">date</p></table-cell>
    <table-cell><p class="slate-p ">Date of birth.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">occupation</code></p></table-cell>
    <table-cell><p class="slate-p ">string | null</p></table-cell>
    <table-cell><p class="slate-p ">Occupation.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">email</code></p></table-cell>
    <table-cell><p class="slate-p ">string</p></table-cell>
    <table-cell><p class="slate-p ">Email address.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">phone</code></p></table-cell>
    <table-cell><p class="slate-p ">string</p></table-cell>
    <table-cell><p class="slate-p ">Home phone.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">mobile</code></p></table-cell>
    <table-cell><p class="slate-p ">string</p></table-cell>
    <table-cell><p class="slate-p ">Mobile phone.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">work_phone</code></p></table-cell>
    <table-cell><p class="slate-p ">string</p></table-cell>
    <table-cell><p class="slate-p ">Work phone.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">address1</code></p></table-cell>
    <table-cell><p class="slate-p ">string</p></table-cell>
    <table-cell><p class="slate-p ">Street address line 1.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">address2</code></p></table-cell>
    <table-cell><p class="slate-p ">string</p></table-cell>
    <table-cell><p class="slate-p ">Street address line 2.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">postcode</code></p></table-cell>
    <table-cell><p class="slate-p ">string</p></table-cell>
    <table-cell><p class="slate-p ">Postal code.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">suburb</code></p></table-cell>
    <table-cell><p class="slate-p ">string</p></table-cell>
    <table-cell><p class="slate-p ">City or suburb.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">state</code></p></table-cell>
    <table-cell><p class="slate-p ">string</p></table-cell>
    <table-cell><p class="slate-p ">State or territory.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">work_address1</code></p></table-cell>
    <table-cell><p class="slate-p ">string</p></table-cell>
    <table-cell><p class="slate-p ">Work address line 1.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">work_address2</code></p></table-cell>
    <table-cell><p class="slate-p ">string</p></table-cell>
    <table-cell><p class="slate-p ">Work address line 2.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">work_postcode</code></p></table-cell>
    <table-cell><p class="slate-p ">string | null</p></table-cell>
    <table-cell><p class="slate-p ">Work postal code.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">work_suburb</code></p></table-cell>
    <table-cell><p class="slate-p ">string</p></table-cell>
    <table-cell><p class="slate-p ">Work city or suburb.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">work_state</code></p></table-cell>
    <table-cell><p class="slate-p ">string</p></table-cell>
    <table-cell><p class="slate-p ">Work state.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">recall_comm_preference</code></p></table-cell>
    <table-cell><p class="slate-p ">string</p></table-cell>
    <table-cell><p class="slate-p ">Recall communication method.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">appointment_comm_preference</code></p></table-cell>
    <table-cell><p class="slate-p ">string</p></table-cell>
    <table-cell><p class="slate-p ">Appointment communication method.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">invoice_comm_preference</code></p></table-cell>
    <table-cell><p class="slate-p ">string</p></table-cell>
    <table-cell><p class="slate-p ">Invoice communication method.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">queries_comm_preference</code></p></table-cell>
    <table-cell><p class="slate-p ">string</p></table-cell>
    <table-cell><p class="slate-p ">Queries communication method.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">first_seen_date</code></p></table-cell>
    <table-cell><p class="slate-p ">date</p></table-cell>
    <table-cell><p class="slate-p ">First visit date.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">first_treatment_date</code></p></table-cell>
    <table-cell><p class="slate-p ">date</p></table-cell>
    <table-cell><p class="slate-p ">First treatment date.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">new_patient_date</code></p></table-cell>
    <table-cell><p class="slate-p ">date</p></table-cell>
    <table-cell><p class="slate-p ">New patient registration date.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">latest_seen_date</code></p></table-cell>
    <table-cell><p class="slate-p ">date</p></table-cell>
    <table-cell><p class="slate-p ">Most recent visit date.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">practitioner_id</code></p></table-cell>
    <table-cell><p class="slate-p ">integer</p></table-cell>
    <table-cell><p class="slate-p ">Primary practitioner ID.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">location_id</code></p></table-cell>
    <table-cell><p class="slate-p ">integer</p></table-cell>
    <table-cell><p class="slate-p ">Primary location ID.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">health_fund_name</code></p></table-cell>
    <table-cell><p class="slate-p ">string | null</p></table-cell>
    <table-cell><p class="slate-p ">Health fund provider.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">health_fund_member_id</code></p></table-cell>
    <table-cell><p class="slate-p ">string | null</p></table-cell>
    <table-cell><p class="slate-p ">Member ID.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">health_fund_ref_number</code></p></table-cell>
    <table-cell><p class="slate-p ">string | null</p></table-cell>
    <table-cell><p class="slate-p ">Reference number.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">fee_level</code></p></table-cell>
    <table-cell><p class="slate-p ">string</p></table-cell>
    <table-cell><p class="slate-p ">Fee schedule category.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">medicare_no</code></p></table-cell>
    <table-cell><p class="slate-p ">string | null</p></table-cell>
    <table-cell><p class="slate-p ">Medicare number.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">medicare_IRN</code></p></table-cell>
    <table-cell><p class="slate-p ">string | null</p></table-cell>
    <table-cell><p class="slate-p ">Medicare IRN.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">discount_percent</code></p></table-cell>
    <table-cell><p class="slate-p ">decimal</p></table-cell>
    <table-cell><p class="slate-p ">Default discount percentage.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">recall_date</code></p></table-cell>
    <table-cell><p class="slate-p ">date | null</p></table-cell>
    <table-cell><p class="slate-p ">Next recall due date.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">medical_conditions</code></p></table-cell>
    <table-cell><p class="slate-p ">string | null</p></table-cell>
    <table-cell><p class="slate-p ">Medical conditions.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">alerts</code></p></table-cell>
    <table-cell><p class="slate-p ">string | null</p></table-cell>
    <table-cell><p class="slate-p ">Patient alerts.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">allergies</code></p></table-cell>
    <table-cell><p class="slate-p ">string | null</p></table-cell>
    <table-cell><p class="slate-p ">Known allergies.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">personal_details</code></p></table-cell>
    <table-cell><p class="slate-p ">string | null</p></table-cell>
    <table-cell><p class="slate-p ">Additional personal details.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">med_hist_last_updated</code></p></table-cell>
    <table-cell><p class="slate-p ">date | null</p></table-cell>
    <table-cell><p class="slate-p ">Medical history last updated.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">referring_patient_id</code></p></table-cell>
    <table-cell><p class="slate-p ">integer | null</p></table-cell>
    <table-cell><p class="slate-p ">Referring patient.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">referral_source</code></p></table-cell>
    <table-cell><p class="slate-p ">string | null</p></table-cell>
    <table-cell><p class="slate-p ">Referral source.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">referral_date</code></p></table-cell>
    <table-cell><p class="slate-p ">date | null</p></table-cell>
    <table-cell><p class="slate-p ">Referral date.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">created_date</code></p></table-cell>
    <table-cell><p class="slate-p ">datetime</p></table-cell>
    <table-cell><p class="slate-p ">Record created.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">updated_date</code></p></table-cell>
    <table-cell><p class="slate-p ">datetime</p></table-cell>
    <table-cell><p class="slate-p ">Record modified.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">custom_fields</code></p></table-cell>
    <table-cell><p class="slate-p ">object</p></table-cell>
    <table-cell><p class="slate-p ">Practice-defined custom fields, keyed by field name (varies by org). Each value is a string.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">metadata</code></p></table-cell>
    <table-cell><p class="slate-p ">object</p></table-cell>
    <table-cell><p class="slate-p ">Informational fields describing capping, fallback, and default-window behaviour applied to this request. See <a href="/api-response-formats">API Response Formats</a> for the full field list.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">pagination</code></p></table-cell>
    <table-cell><p class="slate-p ">object</p></table-cell>
    <table-cell><p class="slate-p ">Paging details for this result set: <code class="slate-code">page</code>, <code class="slate-code">per_page</code>, <code class="slate-code">total_rows</code>, <code class="slate-code">total_pages</code>. See <a href="/api-response-formats">API Response Formats</a> for the full field list.</p></table-cell>
  </table-row>
</Table>

Important notes
---------------

*   **Path parameter:** `patient_id` is required.
    
*   **Not found:** returns 404 if the patient does not exist.
    
*   **PID-only:** other parameters (including `include` and FHIR) are not accepted at this endpoint. Use `GET /patients` for broad search.
    

Quick example
-------------

<CodeBlock attributes='{"isFitToPage":true,"style":{},"lang":"plainText","label":"Plain text"}'>
  <CodeLine>curl "https://api-uat.dental4web.com.au/api/v1/patients_extended/72" \</CodeLine>
  <CodeLine>    -H "x-api-key: $API_KEY" \</CodeLine>
  <CodeLine>    -H "org-id: $ORG_ID" \</CodeLine>
  <CodeLine>    -H "Accept: application/json" </CodeLine>
</CodeBlock>

GET Patient Extended By ID

Creates a new patient record and returns the persisted patient with a system-assigned `patient_id`. Duplicate patients (exact match on `firstname` + `surname` + `date_of_birth`) are blocked unless `force_create: 1` is set.

Use cases
---------

*   Create a patient via an external booking system.
    
*   Bulk-import patient demographics from a Customer Resource Management (CRM) system.
    
*   Create a new patient booking via a voice AI agent.
    

Request body
------------

<Table style="width:100%;min-width:100%" colSizes='["180px","135px","585px"]' isHeaderAdded='true' tableHeader='[{"id":"11d7282d-42c2-45e8-aebc-c87304b165c9","title":"Field"},{"id":"5f449205-c236-4b6d-a09f-037db8d57522","title":"Type"},{"id":"33fb82f4-25fe-4321-a5fe-b8e9035f5242","title":"Description"}]'>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">firstname</code></p></table-cell>
    <table-cell><p class="slate-p ">string</p></table-cell>
    <table-cell><p class="slate-p ">Required. 1-30 characters (Latin-1).</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">surname</code></p></table-cell>
    <table-cell><p class="slate-p ">string</p></table-cell>
    <table-cell><p class="slate-p ">Required. 1-30 characters (Latin-1).</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">date_of_birth</code></p></table-cell>
    <table-cell><p class="slate-p ">string</p></table-cell>
    <table-cell><p class="slate-p ">Required. YYYY-MM-DD, 1900-01-01 to today.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">practitioner_id</code></p></table-cell>
    <table-cell><p class="slate-p ">number</p></table-cell>
    <table-cell><p class="slate-p ">Active practitioner_id from /api/v1/practitioners (0 or greater).</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">gender_code</code></p></table-cell>
    <table-cell><p class="slate-p ">string</p></table-cell>
    <table-cell><p class="slate-p ">Exactly 1 character (for example M or F). Values other than M or F are silently stored as NULL. The response includes a <code class="slate-code">warnings[]</code> entry when this happens.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">title</code></p></table-cell>
    <table-cell><p class="slate-p ">string</p></table-cell>
    <table-cell><p class="slate-p ">Up to 6 characters (for example MR, MRS, DR).</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">middle_name</code></p></table-cell>
    <table-cell><p class="slate-p ">string</p></table-cell>
    <table-cell><p class="slate-p ">Up to 15 characters.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">email</code></p></table-cell>
    <table-cell><p class="slate-p ">string</p></table-cell>
    <table-cell><p class="slate-p ">Up to 60 characters. An empty or whitespace-only value is normalised to <code class="slate-code">NULL</code>.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">phone_home</code></p></table-cell>
    <table-cell><p class="slate-p ">string</p></table-cell>
    <table-cell><p class="slate-p ">Up to 20 characters.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">phone_mobile</code></p></table-cell>
    <table-cell><p class="slate-p ">string</p></table-cell>
    <table-cell><p class="slate-p ">Up to 20 characters. An empty or whitespace-only value is normalised to <code class="slate-code">NULL</code>.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">phone_work</code></p></table-cell>
    <table-cell><p class="slate-p ">string</p></table-cell>
    <table-cell><p class="slate-p ">Up to 20 characters.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">occupation</code></p></table-cell>
    <table-cell><p class="slate-p ">string</p></table-cell>
    <table-cell><p class="slate-p ">Up to 30 characters.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">company</code></p></table-cell>
    <table-cell><p class="slate-p ">string</p></table-cell>
    <table-cell><p class="slate-p ">Up to 100 characters.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">address_line1</code></p></table-cell>
    <table-cell><p class="slate-p ">string</p></table-cell>
    <table-cell><p class="slate-p ">Up to 300 characters.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">address_line2</code></p></table-cell>
    <table-cell><p class="slate-p ">string</p></table-cell>
    <table-cell><p class="slate-p ">Up to 40 characters.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">suburb</code></p></table-cell>
    <table-cell><p class="slate-p ">string</p></table-cell>
    <table-cell><p class="slate-p ">Up to 80 characters.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">state</code></p></table-cell>
    <table-cell><p class="slate-p ">string</p></table-cell>
    <table-cell><p class="slate-p ">Up to 5 characters (AU state code, for example NSW).</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">postcode</code></p></table-cell>
    <table-cell><p class="slate-p ">string</p></table-cell>
    <table-cell><p class="slate-p ">4 digits, 0200-9999.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">address_line1_work</code></p></table-cell>
    <table-cell><p class="slate-p ">string</p></table-cell>
    <table-cell><p class="slate-p ">Up to 300 characters.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">address_line2_work</code></p></table-cell>
    <table-cell><p class="slate-p ">string</p></table-cell>
    <table-cell><p class="slate-p ">Up to 40 characters.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">suburb_work</code></p></table-cell>
    <table-cell><p class="slate-p ">string</p></table-cell>
    <table-cell><p class="slate-p ">Up to 80 characters.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">state_work</code></p></table-cell>
    <table-cell><p class="slate-p ">string</p></table-cell>
    <table-cell><p class="slate-p ">Up to 5 characters (AU state code, for example NSW).</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">postcode_work</code></p></table-cell>
    <table-cell><p class="slate-p ">string</p></table-cell>
    <table-cell><p class="slate-p ">4 digits, 0200-9999.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">force_create</code></p></table-cell>
    <table-cell><p class="slate-p ">integer</p></table-cell>
    <table-cell><p class="slate-p ">0 blocks duplicates (default), 1 allows duplicate creation.</p></table-cell>
  </table-row>
</Table>

Returns
-------

A `200` response returns the persisted patient object in `data[0]`, including the system-assigned `patient_id`. The fields match those described on [Get patient by ID](/patient-resources/get-patient-by-id).

Error responses
---------------

<Table style="width:100%;min-width:100%" colSizes='["180px","135px","585px"]' isHeaderAdded='true' tableHeader='[{"id":"fc098875-a427-402c-be06-ab8e74c325f1","title":"Status"},{"id":"f5a81900-f971-42e8-9020-4228805d912e","title":"support_code"},{"id":"b02cb29b-35c0-468d-86b1-78dbe6dba440","title":"Meaning"}]'>
  <table-row>
    <table-cell><p class="slate-p ">400</p></table-cell>
    <table-cell><p class="slate-p "><code class="slate-code">PW-6010</code></p></table-cell>
    <table-cell><p class="slate-p "><code class="slate-code">date_of_birth</code> outside 1900-01-01 to today.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p ">400</p></table-cell>
    <table-cell><p class="slate-p "><code class="slate-code">PW-6020</code></p></table-cell>
    <table-cell><p class="slate-p "><code class="slate-code">postcode</code> failed Australian validation.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p ">400</p></table-cell>
    <table-cell><p class="slate-p "><code class="slate-code">PW-6025</code></p></table-cell>
    <table-cell><p class="slate-p ">A field contains characters with no supported ASCII equivalent.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p ">400</p></table-cell>
    <table-cell><p class="slate-p "><code class="slate-code">PW-6026</code></p></table-cell>
    <table-cell><p class="slate-p ">A field exceeds its maximum length after character conversion.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p ">404</p></table-cell>
    <table-cell><p class="slate-p "><code class="slate-code">PW-6012</code></p></table-cell>
    <table-cell><p class="slate-p "><code class="slate-code">practitioner_id</code> not found or not active.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p ">409</p></table-cell>
    <table-cell><p class="slate-p "><code class="slate-code">PW-6001</code></p></table-cell>
    <table-cell><p class="slate-p ">Duplicate patient (name and date-of-birth match). Pass <code class="slate-code">force_create: 1</code> to allow.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p ">422</p></table-cell>
    <table-cell><p class="slate-p ">(none)</p></table-cell>
    <table-cell><p class="slate-p ">Required field missing, wrong type, invalid date format, or value too long (schema validation).</p></table-cell>
  </table-row>
</Table>

For the canonical list of error codes, see [Validation, Limits & Character Handling](/validation-limits-and-character-handling).

### Example error responses

Required field missing (`422`):

<CodeBlock attributes='{"isFitToPage":true,"style":{},"lang":"json","label":"JSON"}'>
  <CodeLine></CodeLine>
  <CodeLine>    { "data": [], "status": false, "message": "'surname': field required; 'date_of_birth': field required" }</CodeLine>
</CodeBlock>

Invalid date format (`422`):

<CodeBlock attributes='{"isFitToPage":true,"style":{},"lang":"json","label":"JSON"}'>
  <CodeLine></CodeLine>
  <CodeLine>    { "data": [], "status": false, "message": "'date_of_birth': invalid date format" }</CodeLine>
</CodeBlock>

Value too long (`422`):

<CodeBlock attributes='{"isFitToPage":true,"style":{},"lang":"json","label":"JSON"}'>
  <CodeLine></CodeLine>
  <CodeLine>    { "data": [], "status": false, "message": "'firstname': ensure this value has at most 30 characters" }</CodeLine>
</CodeBlock>

Wrong type (`422`):

<CodeBlock attributes='{"isFitToPage":true,"style":{},"lang":"json","label":"JSON"}'>
  <CodeLine></CodeLine>
  <CodeLine>    { "data": [], "status": false, "message": "'force_create': value is not a valid integer" }</CodeLine>
</CodeBlock>

`date_of_birth` out of range (`400`):

<CodeBlock attributes='{"isFitToPage":true,"style":{},"lang":"json","label":"JSON"}'>
  <CodeLine></CodeLine>
  <CodeLine>    { "data": [], "status": false, "message": "date_of_birth must be between 1900-01-01 and today (got 1800-01-01).", "support_code": "PW-6010" }</CodeLine>
</CodeBlock>

Invalid postcode (`400`):

<CodeBlock attributes='{"isFitToPage":true,"style":{},"lang":"json","label":"JSON"}'>
  <CodeLine></CodeLine>
  <CodeLine>    { "data": [], "status": false, "message": "postcode must be a valid Australian postcode (4 digits, range 0200-9999; got 'ABCD').", "support_code": "PW-6020" }</CodeLine>
</CodeBlock>

Unsupported characters (`400`):

<CodeBlock attributes='{"isFitToPage":true,"style":{},"lang":"json","label":"JSON"}'>
  <CodeLine></CodeLine>
  <CodeLine>    { "data": [], "status": false, "message": "One or more fields contain characters the practice management system cannot store and that have no accepted ASCII equivalent (fields: firstname). Re-submit using Latin characters only. [PW-6025]", "support_code": "PW-6025" }</CodeLine>
</CodeBlock>

Field too long after conversion (`400`):

<CodeBlock attributes='{"isFitToPage":true,"style":{},"lang":"json","label":"JSON"}'>
  <CodeLine></CodeLine>
  <CodeLine>    { "data": [], "status": false, "message": "One or more fields exceed the maximum length the practice management system accepts after special characters were converted to plain text (fields: firstname (56&gt;30)). Shorten the affected field(s) and resubmit. [PW-6026]", "support_code": "PW-6026" }</CodeLine>
</CodeBlock>

Practitioner not found (`404`):

<CodeBlock attributes='{"isFitToPage":true,"style":{},"lang":"json","label":"JSON"}'>
  <CodeLine></CodeLine>
  <CodeLine>    { "data": [], "status": false, "message": "Practitioner not found.", "support_code": "PW-6012" }</CodeLine>
</CodeBlock>

Duplicate patient (`409`):

<CodeBlock attributes='{"isFitToPage":true,"style":{},"lang":"json","label":"JSON"}'>
  <CodeLine></CodeLine>
  <CodeLine>    { "data": [], "status": false, "message": "A patient with this name and date of birth already exists (patient ID 72, card 72).", "support_code": "PW-6001" }</CodeLine>
</CodeBlock>

Important notes
---------------

*   Required fields are `firstname`, `surname`, and `date_of_birth`.
    
*   `practitioner_id` is optional.
    
*   Duplicate detection is by exact match on `firstname` + `surname` + `date_of_birth`. Override with `force_create: 1`.
    
*   Character handling: accented characters are converted to their plain-letter equivalent (for example, `Zoë` becomes `Zoe`, `François` becomes `Francois`). Characters with no supported equivalent (CJK, emoji, Cyrillic) are rejected with `PW-6025`. See Validation, Limits & Character Handling.
    
*   `postcode` must be a 4-digit Australian postcode in the range 0200-9999 (both residential and work).
    
*   Unknown fields in the request body are silently ignored.
    

Quick example
-------------

<CodeBlock attributes='{"isFitToPage":true,"style":{},"lang":"plainText","label":"Plain text"}'>
  <CodeLine>curl -X POST "https://api-uat.dental4web.com.au/api/v1/patients" \</CodeLine>
  <CodeLine>    -H "x-api-key: $API_KEY" \</CodeLine>
  <CodeLine>    -H "org-id: $ORG_ID" \</CodeLine>
  <CodeLine>    -H "Content-Type: application/json" \</CodeLine>
  <CodeLine>    -H "Accept: application/json" \</CodeLine>
  <CodeLine>    -d '{"firstname":"John","surname":"Mitchell","date_of_birth":"1985-03-22","postcode":"2000","state":"NSW"}' </CodeLine>
</CodeBlock>

POST Patient

Updates an existing patient record. Pass only the fields you want to change. At least one updatable field must be supplied, and unknown fields are silently ignored.

Use cases
---------

*   Sync demographic changes from an external CRM.
    
*   Update contact details (phone, email, address) after a patient visit.
    
*   Correct typos in patient names.
    

Request body
------------

Pass any subset of the following fields. At least one is required.

<Table style="width:100%;min-width:100%" colSizes='["180px","135px","585px"]' isHeaderAdded='true' tableHeader='[{"id":"aeb6fa82-17e6-46fd-bd69-ef9ddb5509bf","title":"Field"},{"id":"5076ba74-78c4-430e-9a83-a16c2e989dd8","title":"Type"},{"id":"cc6d6719-479b-4fac-971c-1945bb9e600b","title":"Description"}]'>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">firstname</code></p></table-cell>
    <table-cell><p class="slate-p ">string</p></table-cell>
    <table-cell><p class="slate-p ">1-30 characters (Latin-1).</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">surname</code></p></table-cell>
    <table-cell><p class="slate-p ">string</p></table-cell>
    <table-cell><p class="slate-p ">1-30 characters (Latin-1).</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">date_of_birth</code></p></table-cell>
    <table-cell><p class="slate-p ">string</p></table-cell>
    <table-cell><p class="slate-p ">YYYY-MM-DD, 1900-01-01 to today.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">practitioner_id</code></p></table-cell>
    <table-cell><p class="slate-p ">number</p></table-cell>
    <table-cell><p class="slate-p ">Active practitioner_id from /api/v1/practitioners. Confirmed live: must be 1 or greater; 0 is rejected on update (unlike create).</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">gender_code</code></p></table-cell>
    <table-cell><p class="slate-p ">string</p></table-cell>
    <table-cell><p class="slate-p ">Exactly 1 character (for example M or F). Confirmed live: submitting a value other than M or F does not store NULL: the patient's existing stored <code class="slate-code">gender_code</code> is left unchanged, and the response includes a <code class="slate-code">warnings[]</code> entry. Submitting an empty string is treated identically to omitting the field, and does not produce a <code class="slate-code">warnings[]</code> entry; only an explicitly invalid non-blank value does.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">title</code></p></table-cell>
    <table-cell><p class="slate-p ">string</p></table-cell>
    <table-cell><p class="slate-p ">Up to 6 characters (for example MR, MRS, DR).</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">middle_name</code></p></table-cell>
    <table-cell><p class="slate-p ">string</p></table-cell>
    <table-cell><p class="slate-p ">Up to 15 characters.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">email</code></p></table-cell>
    <table-cell><p class="slate-p ">string</p></table-cell>
    <table-cell><p class="slate-p ">Up to 60 characters. An empty or whitespace-only value clears the field (stored as <code class="slate-code">NULL</code>).</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">phone_home</code></p></table-cell>
    <table-cell><p class="slate-p ">string</p></table-cell>
    <table-cell><p class="slate-p ">Up to 20 characters.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">phone_mobile</code></p></table-cell>
    <table-cell><p class="slate-p ">string</p></table-cell>
    <table-cell><p class="slate-p ">Up to 20 characters. An empty or whitespace-only value clears the field (stored as <code class="slate-code">NULL</code>).</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">phone_work</code></p></table-cell>
    <table-cell><p class="slate-p ">string</p></table-cell>
    <table-cell><p class="slate-p ">Up to 20 characters.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">occupation</code></p></table-cell>
    <table-cell><p class="slate-p ">string</p></table-cell>
    <table-cell><p class="slate-p ">Up to 30 characters.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">company</code></p></table-cell>
    <table-cell><p class="slate-p ">string</p></table-cell>
    <table-cell><p class="slate-p ">Up to 100 characters.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">address_line1</code></p></table-cell>
    <table-cell><p class="slate-p ">string</p></table-cell>
    <table-cell><p class="slate-p ">Up to 300 characters.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">address_line2</code></p></table-cell>
    <table-cell><p class="slate-p ">string</p></table-cell>
    <table-cell><p class="slate-p ">Up to 40 characters.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">suburb</code></p></table-cell>
    <table-cell><p class="slate-p ">string</p></table-cell>
    <table-cell><p class="slate-p ">Up to 80 characters.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">state</code></p></table-cell>
    <table-cell><p class="slate-p ">string</p></table-cell>
    <table-cell><p class="slate-p ">Up to 5 characters (AU state code, for example NSW).</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">postcode</code></p></table-cell>
    <table-cell><p class="slate-p ">string</p></table-cell>
    <table-cell><p class="slate-p ">4 digits, 0200-9999.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">address_line1_work</code></p></table-cell>
    <table-cell><p class="slate-p ">string</p></table-cell>
    <table-cell><p class="slate-p ">Up to 300 characters.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">address_line2_work</code></p></table-cell>
    <table-cell><p class="slate-p ">string</p></table-cell>
    <table-cell><p class="slate-p ">Up to 40 characters.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">suburb_work</code></p></table-cell>
    <table-cell><p class="slate-p ">string</p></table-cell>
    <table-cell><p class="slate-p ">Up to 80 characters.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">state_work</code></p></table-cell>
    <table-cell><p class="slate-p ">string</p></table-cell>
    <table-cell><p class="slate-p ">Up to 5 characters (AU state code, for example NSW).</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">postcode_work</code></p></table-cell>
    <table-cell><p class="slate-p ">string</p></table-cell>
    <table-cell><p class="slate-p ">4 digits, 0200-9999.</p></table-cell>
  </table-row>
</Table>

Returns
-------

A `200` response returns the updated patient object in `data[0]`. The fields match those described on [Get patient by ID](/patient-resources/get-patient-by-id).

Error responses
---------------

<Table style="width:100%;min-width:100%" colSizes='["180px","135px","585px"]' isHeaderAdded='true' tableHeader='[{"id":"802bf2b7-a1b4-439c-817a-44a7559ebbe5","title":"Status"},{"id":"5f324dcd-17d3-4da0-b7d8-220ef1723e84","title":"support_code"},{"id":"ebb1ba28-0893-4c94-a938-81c615ff7ab7","title":"Meaning"}]'>
  <table-row>
    <table-cell><p class="slate-p ">400</p></table-cell>
    <table-cell><p class="slate-p "><code class="slate-code">PW-6010</code></p></table-cell>
    <table-cell><p class="slate-p "><code class="slate-code">date_of_birth</code> outside 1900-01-01 to today.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p ">400</p></table-cell>
    <table-cell><p class="slate-p "><code class="slate-code">PW-6020</code></p></table-cell>
    <table-cell><p class="slate-p "><code class="slate-code">postcode</code> failed Australian validation.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p ">400</p></table-cell>
    <table-cell><p class="slate-p "><code class="slate-code">PW-6025</code> / <code class="slate-code">PW-6026</code></p></table-cell>
    <table-cell><p class="slate-p ">Unsupported character, or field too long after conversion.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p ">404</p></table-cell>
    <table-cell><p class="slate-p "><code class="slate-code">PW-6013</code></p></table-cell>
    <table-cell><p class="slate-p "><code class="slate-code">patient_id</code> does not exist.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p ">422</p></table-cell>
    <table-cell><p class="slate-p ">(none)</p></table-cell>
    <table-cell><p class="slate-p ">Empty body, invalid field type/format, or path <code class="slate-code">patient_id</code> out of range.</p></table-cell>
  </table-row>
</Table>

For the canonical list of error codes, see [Validation, Limits & Character Handling](/validation-limits-and-character-handling).

### Example error responses

Patient not found (`404`):

<CodeBlock attributes='{"isFitToPage":true,"style":{},"lang":"json","label":"JSON"}'>
  <CodeLine></CodeLine>
  <CodeLine>    { "data": [], "status": false, "message": "Patient 999999999 not found.", "support_code": "PW-6013" }</CodeLine>
</CodeBlock>

Empty body (`422`):

<CodeBlock attributes='{"isFitToPage":true,"style":{},"lang":"json","label":"JSON"}'>
  <CodeLine></CodeLine>
  <CodeLine>    { "data": [], "status": false, "message": "At least one field must be provided for update." }</CodeLine>
</CodeBlock>

Path `patient_id` out of range (`422`):

<CodeBlock attributes='{"isFitToPage":true,"style":{},"lang":"json","label":"JSON"}'>
  <CodeLine></CodeLine>
  <CodeLine>    { "data": [], "status": false, "message": "'path -&gt; patient_id': ensure this value is less than or equal to 999999999" }</CodeLine>
</CodeBlock>

`date_of_birth` out of range (`400`):

<CodeBlock attributes='{"isFitToPage":true,"style":{},"lang":"json","label":"JSON"}'>
  <CodeLine></CodeLine>
  <CodeLine>    { "data": [], "status": false, "message": "date_of_birth must be between 1900-01-01 and today (got 1850-01-01).", "support_code": "PW-6010" }</CodeLine>
</CodeBlock>

Invalid postcode (`400`):

<CodeBlock attributes='{"isFitToPage":true,"style":{},"lang":"json","label":"JSON"}'>
  <CodeLine></CodeLine>
  <CodeLine>    { "data": [], "status": false, "message": "postcode must be a valid Australian postcode (4 digits, range 0200-9999; got 'ABCD').", "support_code": "PW-6020" }</CodeLine>
</CodeBlock>

Unsupported characters (`400`):

<CodeBlock attributes='{"isFitToPage":true,"style":{},"lang":"json","label":"JSON"}'>
  <CodeLine></CodeLine>
  <CodeLine>    { "data": [], "status": false, "message": "One or more fields contain characters the practice management system cannot store and that have no accepted ASCII equivalent (fields: firstname). Re-submit using Latin characters only. [PW-6025]", "support_code": "PW-6025" }</CodeLine>
</CodeBlock>

Field too long after conversion (`400`):

<CodeBlock attributes='{"isFitToPage":true,"style":{},"lang":"json","label":"JSON"}'>
  <CodeLine></CodeLine>
  <CodeLine>    { "data": [], "status": false, "message": "One or more fields exceed the maximum length the practice management system accepts after special characters were converted to plain text (fields: firstname (56&gt;30)). Shorten the affected field(s) and resubmit. [PW-6026]", "support_code": "PW-6026" }</CodeLine>
</CodeBlock>

Important notes
---------------

*   Path parameter `patient_id` must be between 1 and 999,999,999.
    
*   An empty body is rejected with `422 "At least one field must be provided for update."`
    
*   `practitioner_id` must be an active `practitioner_id` from `/api/v1/practitioners`, 1 or greater. Confirmed live: unlike POST Patient (which accepts 0), PATCH rejects `practitioner_id: 0` with a 422.
    
*   All other field validation rules from Create patient apply, including accent conversion, postcode validation, and column-width caps.
    

Quick example
-------------

<CodeBlock attributes='{"isFitToPage":true,"style":{},"lang":"plainText","label":"Plain text"}'>
  <CodeLine>curl -X PATCH "https://api-uat.dental4web.com.au/api/v1/patients/72" \</CodeLine>
  <CodeLine>    -H "x-api-key: $API_KEY" \</CodeLine>
  <CodeLine>    -H "org-id: $ORG_ID" \</CodeLine>
  <CodeLine>    -H "Content-Type: application/json" \</CodeLine>
  <CodeLine>    -H "Accept: application/json" \</CodeLine>
  <CodeLine>    -d '{"phone_mobile":"0412345678","email":"john.mitchell@example.com"}' </CodeLine>
</CodeBlock>

PATCH Patient

Lightweight, multi-field patient search returning up to 7 core fields per row. Faster and simpler than [GET Patients](/patient-resources/get-patients) when you only need to look a patient up by name, card, date of birth, email, or mobile.

Use cases
---------

*   Quick patient lookup by name, card number, date of birth, email, or mobile without pulling the full patient object.
    
*   A lightweight search surface for voice or chat interfaces and reception lookups.
    
*   Verify a patient's core identity fields before making a heavier call such as [GET Patients](/patient-resources/get-patients) or [GET Patient Extended By ID](/patient-resources/get-patient-extended-by-id).
    

Parameters
----------

<Table style="width:100%;min-width:100%" colSizes='["180px","135px","585px"]' isHeaderAdded='true' tableHeader='[{"id":"b2c3d4e5-0015-4aaa-8015-000000000001","title":"Parameter"},{"id":"b2c3d4e5-0015-4aaa-8015-000000000002","title":"Type"},{"id":"b2c3d4e5-0015-4aaa-8015-000000000003","title":"Description"}]'>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">patient_id</code></p></table-cell>
    <table-cell><p class="slate-p ">integer</p></table-cell>
    <table-cell><p class="slate-p ">1-999999999.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">patient_card</code></p></table-cell>
    <table-cell><p class="slate-p ">string</p></table-cell>
    <table-cell><p class="slate-p ">1-50 characters.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">firstname</code></p></table-cell>
    <table-cell><p class="slate-p ">string</p></table-cell>
    <table-cell><p class="slate-p ">1-100 characters. Note: no underscore, unlike the <code class="slate-code">first_name</code> response field. This is a genuine asymmetry in the live API, not a typo.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">surname</code></p></table-cell>
    <table-cell><p class="slate-p ">string</p></table-cell>
    <table-cell><p class="slate-p ">1-100 characters.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">date_of_birth</code></p></table-cell>
    <table-cell><p class="slate-p ">string</p></table-cell>
    <table-cell><p class="slate-p ">YYYY-MM-DD.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">email</code></p></table-cell>
    <table-cell><p class="slate-p ">string</p></table-cell>
    <table-cell><p class="slate-p ">1-255 characters.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">mobile</code></p></table-cell>
    <table-cell><p class="slate-p ">string</p></table-cell>
    <table-cell><p class="slate-p ">1-50 characters.</p></table-cell>
  </table-row>
</Table>

Response fields
---------------

<Table style="width:100%;min-width:100%" colSizes='["180px","135px","585px"]' isHeaderAdded='true' tableHeader='[{"id":"b2c3d4e5-0015-4bbb-8015-000000000001","title":"Field"},{"id":"b2c3d4e5-0015-4bbb-8015-000000000002","title":"Type"},{"id":"b2c3d4e5-0015-4bbb-8015-000000000003","title":"Description"}]'>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">patient_id</code></p></table-cell>
    <table-cell><p class="slate-p ">integer</p></table-cell>
    <table-cell><p class="slate-p ">Patient identifier.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">patient_card</code></p></table-cell>
    <table-cell><p class="slate-p ">string</p></table-cell>
    <table-cell><p class="slate-p ">Patient card number.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">first_name</code></p></table-cell>
    <table-cell><p class="slate-p ">string</p></table-cell>
    <table-cell><p class="slate-p ">First name.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">surname</code></p></table-cell>
    <table-cell><p class="slate-p ">string</p></table-cell>
    <table-cell><p class="slate-p ">Surname.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">date_of_birth</code></p></table-cell>
    <table-cell><p class="slate-p ">date</p></table-cell>
    <table-cell><p class="slate-p ">Date of birth.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">email</code></p></table-cell>
    <table-cell><p class="slate-p ">string | null</p></table-cell>
    <table-cell><p class="slate-p ">Email address.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">mobile</code></p></table-cell>
    <table-cell><p class="slate-p ">string | null</p></table-cell>
    <table-cell><p class="slate-p ">Mobile phone number.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">metadata</code></p></table-cell>
    <table-cell><p class="slate-p ">object</p></table-cell>
    <table-cell><p class="slate-p ">Informational fields describing capping, fallback, and default-window behaviour applied to this request. See <a href="/api-response-formats">API Response Formats</a> for the full field list.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">pagination</code></p></table-cell>
    <table-cell><p class="slate-p ">object</p></table-cell>
    <table-cell><p class="slate-p ">Paging totals for this result set: <code class="slate-code">page</code>, <code class="slate-code">per_page</code>, <code class="slate-code">total_rows</code>, <code class="slate-code">total_pages</code>. Confirmed live: present on every response, but informational only, since this endpoint accepts no <code class="slate-code">page</code>/<code class="slate-code">per_page</code> query parameters and returns every matching row (up to the cap) in a single call. See <a href="/api-response-formats">API Response Formats</a> for the full field list.</p></table-cell>
  </table-row>
</Table>

Important notes
---------------

*   **At least one parameter required:** passing none of the 7 filters returns HTTP 400: `"At least one parameter is required (patient_id, patient_card, firstname, surname, date_of_birth, email, or mobile)"` (`support_code: RP-4000`, the same code used by [GET Patients](/patient-resources/get-patients)' equivalent check).
    
*   **Result caps:** capped at 1,000 rows when only `date_of_birth` is supplied (without `patient_id` or `patient_card`), 10,000 rows for any other combination. Confirmed live: the cap is disclosed **both** via this endpoint's own `warnings[]` text **and** via the standard `metadata.patient_fanout_cap_applied` / `metadata.patient_fanout_cap_value` fields, the same contract used by [GET Patients](/patient-resources/get-patients), not a divergent one.
    
*   **No FHIR, no `include`:** this endpoint has no FHIR variant and does not support the `include` relations parameter.
    
*   **Pagination is informational only:** confirmed live, the response includes a `pagination` object even though this endpoint accepts no `page`/`per_page` query parameters. Every matching row (up to the cap) is returned in a single call; `pagination.total_pages` exceeds `1` only if `total_rows` exceeds the fixed `per_page: 100`. See [API Response Formats](/api-response-formats).
    
*   **Requires V18:** introduced in the V18 data model. Pre-V18 orgs receive a clean HTTP 400. Check [GET Data-Model Version](/admin-resources/get-data-model-version) if you're unsure which version an org is running.
    

Quick example
-------------

<CodeBlock attributes='{"isFitToPage":true,"style":{},"lang":"plainText","label":"Plain text"}'>
  <CodeLine>curl "https://api-uat.dental4web.com.au/api/v1/patients_lite?surname=Mitchell&amp;date_of_birth=1985-03-22" \</CodeLine>
  <CodeLine>    -H "x-api-key: $API_KEY" \</CodeLine>
  <CodeLine>    -H "org-id: $ORG_ID" \</CodeLine>
  <CodeLine>    -H "Accept: application/json" </CodeLine>
</CodeBlock>


GET Patients Lite

<span style="color:#434343;background-color:transparent">The Treatment & Clinical Resources API gives access to core clinical records in the Dental4Web Practice Management System. It enables third-party systems to retrieve treatment histories, upcoming planned treatments, and clinical notes while maintaining patient privacy and security. These endpoints are designed for integration with external EHR systems, automated reporting and analytics, building patient-facing treatment history views, and supporting compliance and audit needs.</span>

Treatment & Clinical Resources

Retrieves completed treatment records for a patient. Each row is a performed procedure, with its item code, tooth and surface detail, fee, and treating practitioner.

Use cases
---------

*   Review a patient’s treatment history during a consultation.
    
*   Generate treatment-volume reports by practitioner or location.
    
*   Reconcile completed treatments for billing verification.
    
*   Track treatment patterns across the practice.
    

Parameters
----------

<Table style="width:100%;min-width:100%" colSizes='["180px","135px","585px"]' isHeaderAdded='true' tableHeader='[{"id":"8661ba36-9e49-4fcf-ade3-7c46043c9696","title":"Parameter"},{"id":"e749e1ba-e148-4bc4-8abf-9732b68af474","title":"Type"},{"id":"6496d741-80a2-4ee1-b03b-f039dc6c98a8","title":"Description"}]'>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">patient_id</code></p></table-cell>
    <table-cell><p class="slate-p ">integer</p></table-cell>
    <table-cell><p class="slate-p ">Filter to a specific patient. Optional (see Important Notes: at least one filter parameter is required).</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">practitioner_id</code></p></table-cell>
    <table-cell><p class="slate-p ">integer</p></table-cell>
    <table-cell><p class="slate-p ">Filter to a specific practitioner. Use <code class="slate-code">-1</code> to return data for all practitioners. Optional.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">location_id</code></p></table-cell>
    <table-cell><p class="slate-p ">integer</p></table-cell>
    <table-cell><p class="slate-p ">Filter to a specific practice location. Use <code class="slate-code">-1</code> to return data for all locations. Optional.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">from_date</code></p></table-cell>
    <table-cell><p class="slate-p ">string (date)</p></table-cell>
    <table-cell><p class="slate-p ">Start of the date range filter. Format <code class="slate-code">YYYY-MM-DD</code>. Optional; see Important Notes for default behaviour.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">to_date</code></p></table-cell>
    <table-cell><p class="slate-p ">string (date)</p></table-cell>
    <table-cell><p class="slate-p ">End of the date range filter. Format <code class="slate-code">YYYY-MM-DD</code>. Optional; see Important Notes for default behaviour.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">mode</code></p></table-cell>
    <table-cell><p class="slate-p ">integer</p></table-cell>
    <table-cell><p class="slate-p ">Controls date filtering behaviour. <code class="slate-code">0</code> (default) = filter by business date. <code class="slate-code">1</code> = filter by modification timestamp, for sync/delta operations. See <a href="/filtering-and-date-ranges">Filtering &amp; Date Ranges</a>.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">include</code></p></table-cell>
    <table-cell><p class="slate-p ">string</p></table-cell>
    <table-cell><p class="slate-p ">Comma-separated list of related resources to embed in the response. Confirmed live: <code class="slate-code">practitioners</code>, <code class="slate-code">locations</code>, and <code class="slate-code">items</code> embed the matching practitioner, location, and item objects (combine with commas, e.g. <code class="slate-code">practitioners,locations</code>). An unrecognised value returns <code class="slate-code">400</code> listing the full server-side allowed set: <code class="slate-code">patients, practitioners, locations, appt_books, items, payment_types</code>.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">page</code></p></table-cell>
    <table-cell><p class="slate-p ">integer</p></table-cell>
    <table-cell><p class="slate-p ">Page number for paginated results (1-indexed). Optional. Default <code class="slate-code">1</code>.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">per_page</code></p></table-cell>
    <table-cell><p class="slate-p ">integer</p></table-cell>
    <table-cell><p class="slate-p ">Records per page. Optional. Default <code class="slate-code">10</code>. Maximum <code class="slate-code">500</code>.</p></table-cell>
  </table-row>
</Table>

Response fields
---------------

<Table style="width:100%;min-width:100%" colSizes='["180px","135px","585px"]' isHeaderAdded='true' tableHeader='[{"id":"b788a960-5b83-4cab-a828-3ddea85ef8dc","title":"Field"},{"id":"dcddde37-2558-4e0a-86de-ab5ba7f6e40f","title":"Type"},{"id":"dfdc1166-37c5-44f3-9d14-7a7ebf62fd3b","title":"Description"}]'>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">treatment_id</code></p></table-cell>
    <table-cell><p class="slate-p ">integer</p></table-cell>
    <table-cell><p class="slate-p ">Primary identifier.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">patient_id</code></p></table-cell>
    <table-cell><p class="slate-p ">integer</p></table-cell>
    <table-cell><p class="slate-p ">Patient identifier.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">plan_date</code></p></table-cell>
    <table-cell><p class="slate-p ">date | null</p></table-cell>
    <table-cell><p class="slate-p ">Date from the treatment plan, if the treatment was planned.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">treatment_date</code></p></table-cell>
    <table-cell><p class="slate-p ">date</p></table-cell>
    <table-cell><p class="slate-p ">Date the treatment was performed.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">item_code</code></p></table-cell>
    <table-cell><p class="slate-p ">string</p></table-cell>
    <table-cell><p class="slate-p ">Procedure / item code.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">item_qty</code></p></table-cell>
    <table-cell><p class="slate-p ">integer</p></table-cell>
    <table-cell><p class="slate-p ">Quantity.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">tooth</code></p></table-cell>
    <table-cell><p class="slate-p ">string | null</p></table-cell>
    <table-cell><p class="slate-p ">Tooth number, if applicable.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">surface</code></p></table-cell>
    <table-cell><p class="slate-p ">string | null</p></table-cell>
    <table-cell><p class="slate-p ">Tooth surface, if applicable (for example <code class="slate-code">MOD</code>).</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">item_fee</code></p></table-cell>
    <table-cell><p class="slate-p ">decimal</p></table-cell>
    <table-cell><p class="slate-p ">Fee charged.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">practitioner_id</code></p></table-cell>
    <table-cell><p class="slate-p ">integer</p></table-cell>
    <table-cell><p class="slate-p ">Treating practitioner.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">location_id</code></p></table-cell>
    <table-cell><p class="slate-p ">integer</p></table-cell>
    <table-cell><p class="slate-p ">Treatment location.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">plan_id</code></p></table-cell>
    <table-cell><p class="slate-p ">integer | null</p></table-cell>
    <table-cell><p class="slate-p ">Associated treatment-plan identifier.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">created_date</code></p></table-cell>
    <table-cell><p class="slate-p ">datetime</p></table-cell>
    <table-cell><p class="slate-p ">Record creation timestamp.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">updated_date</code></p></table-cell>
    <table-cell><p class="slate-p ">datetime</p></table-cell>
    <table-cell><p class="slate-p ">Record last-modified timestamp.</p></table-cell>
  </table-row>
</Table>

Important notes
---------------

*   **Required filters:** at least one filter parameter is required.
    
*   **Date filtering:** supports the `mode` parameter: see [Filtering & Date Ranges](/filtering-and-date-ranges).
    
*   **Default range:** applies only to unscoped queries, meaning no `patient_id` is supplied (for example a wildcard `practitioner_id=-1` or `location_id=-1` call with no dates): a 90-day window is then applied automatically when no `from_date` / `to_date` is supplied. This window does not fire once `patient_id` narrows the query: a `patient_id`-scoped call with no dates returns that patient's complete history, unwindowed.
    
*   **Wildcard values:** use `practitioner_id=-1` for all practitioners and `location_id=-1` for all locations.
    

Quick example
-------------

<CodeBlock attributes='{"isFitToPage":true,"style":{},"lang":"plainText","label":"Plain text"}'>
  <CodeLine>curl "https://api-uat.dental4web.com.au/api/v1/treatments?patient_id=72&amp;per_page=10" \</CodeLine>
  <CodeLine>    -H "x-api-key: $API_KEY" \</CodeLine>
  <CodeLine>    -H "org-id: $ORG_ID" \</CodeLine>
  <CodeLine>    -H "Accept: application/json" </CodeLine>
</CodeBlock>

GET Treatments

Retrieves treatment plan records showing proposed future treatments. Each record represents a planned procedure, including its estimated cost, target tooth and surface, and scheduling status.

Use cases
---------

*   Display planned treatments to patients for informed consent.
    
*   Track outstanding treatment plans awaiting completion.
    
*   Estimate treatment costs for insurance pre-approvals.
    
*   Schedule future appointments based on treatment-plan items.
    

Parameters
----------

<Table style="width:100%;min-width:100%" colSizes='["180px","135px","585px"]' isHeaderAdded='true' tableHeader='[{"id":"f6dd5649-daff-4d36-a37e-64765b78b338","title":"Parameter"},{"id":"f9c62c5c-29c6-429f-ab01-557a62c8ea31","title":"Type"},{"id":"5a0865ad-99b7-47af-b6a7-503e780ead59","title":"Description"}]'>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">patient_id</code></p></table-cell>
    <table-cell><p class="slate-p ">integer</p></table-cell>
    <table-cell><p class="slate-p ">Filter to a specific patient. Optional (see Important Notes: at least one filter parameter is required).</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">practitioner_id</code></p></table-cell>
    <table-cell><p class="slate-p ">integer</p></table-cell>
    <table-cell><p class="slate-p ">Filter to a specific practitioner. Use <code class="slate-code">-1</code> to return data for all practitioners. Optional.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">location_id</code></p></table-cell>
    <table-cell><p class="slate-p ">integer</p></table-cell>
    <table-cell><p class="slate-p ">Filter to a specific practice location. Use <code class="slate-code">-1</code> to return data for all locations. Optional.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">from_date</code></p></table-cell>
    <table-cell><p class="slate-p ">string (date)</p></table-cell>
    <table-cell><p class="slate-p ">Start of the date range filter. Format <code class="slate-code">YYYY-MM-DD</code>. Optional; see Important Notes for default behaviour.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">to_date</code></p></table-cell>
    <table-cell><p class="slate-p ">string (date)</p></table-cell>
    <table-cell><p class="slate-p ">End of the date range filter. Format <code class="slate-code">YYYY-MM-DD</code>. Optional; see Important Notes for default behaviour.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">mode</code></p></table-cell>
    <table-cell><p class="slate-p ">integer</p></table-cell>
    <table-cell><p class="slate-p ">Controls date filtering behaviour. <code class="slate-code">0</code> (default) = filter by business date. <code class="slate-code">1</code> = filter by modification timestamp, for sync/delta operations. See <a href="/filtering-and-date-ranges">Filtering &amp; Date Ranges</a>.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">include</code></p></table-cell>
    <table-cell><p class="slate-p ">string</p></table-cell>
    <table-cell><p class="slate-p ">Comma-separated list of related resources to embed in the response. Confirmed live: <code class="slate-code">practitioners</code>, <code class="slate-code">locations</code>, and <code class="slate-code">items</code> embed the matching practitioner, location, and item objects (combine with commas, e.g. <code class="slate-code">practitioners,locations</code>). An unrecognised value returns <code class="slate-code">400</code> listing the full server-side allowed set: <code class="slate-code">patients, practitioners, locations, appt_books, items, payment_types</code>.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">page</code></p></table-cell>
    <table-cell><p class="slate-p ">integer</p></table-cell>
    <table-cell><p class="slate-p ">Page number for paginated results (1-indexed). Optional. Default <code class="slate-code">1</code>.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">per_page</code></p></table-cell>
    <table-cell><p class="slate-p ">integer</p></table-cell>
    <table-cell><p class="slate-p ">Records per page. Optional. Default <code class="slate-code">10</code>. Maximum <code class="slate-code">500</code>.</p></table-cell>
  </table-row>
</Table>

Response fields
---------------

<Table style="width:100%;min-width:100%" colSizes='["180px","135px","585px"]' isHeaderAdded='true' tableHeader='[{"id":"160c8612-c211-40f8-95ee-01a6e42648be","title":"Field"},{"id":"85498b0b-56e3-4fe1-8e18-36ae9580e635","title":"Type"},{"id":"35baaded-788e-4b08-b22d-7d68c883ce23","title":"Description"}]'>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">treatment_plan_id</code></p></table-cell>
    <table-cell><p class="slate-p ">integer</p></table-cell>
    <table-cell><p class="slate-p ">Plan identifier.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">treatment_plan_item_id</code></p></table-cell>
    <table-cell><p class="slate-p ">integer</p></table-cell>
    <table-cell><p class="slate-p ">Line-item identifier.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">patient_id</code></p></table-cell>
    <table-cell><p class="slate-p ">integer</p></table-cell>
    <table-cell><p class="slate-p ">Patient identifier.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">phase</code></p></table-cell>
    <table-cell><p class="slate-p ">integer</p></table-cell>
    <table-cell><p class="slate-p ">Treatment phase number.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">visit</code></p></table-cell>
    <table-cell><p class="slate-p ">integer</p></table-cell>
    <table-cell><p class="slate-p ">Planned visit number.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">planned_date</code></p></table-cell>
    <table-cell><p class="slate-p ">date</p></table-cell>
    <table-cell><p class="slate-p ">Planned treatment date.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">item_code</code></p></table-cell>
    <table-cell><p class="slate-p ">string</p></table-cell>
    <table-cell><p class="slate-p ">Procedure / item code.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">item_qty</code></p></table-cell>
    <table-cell><p class="slate-p ">integer</p></table-cell>
    <table-cell><p class="slate-p ">Quantity.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">tooth</code></p></table-cell>
    <table-cell><p class="slate-p ">string | null</p></table-cell>
    <table-cell><p class="slate-p ">Tooth number, if recorded.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">surface</code></p></table-cell>
    <table-cell><p class="slate-p ">string | null</p></table-cell>
    <table-cell><p class="slate-p ">Tooth surface, if recorded.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">item_fee</code></p></table-cell>
    <table-cell><p class="slate-p ">decimal</p></table-cell>
    <table-cell><p class="slate-p ">Estimated fee.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">practitioner_id</code></p></table-cell>
    <table-cell><p class="slate-p ">integer</p></table-cell>
    <table-cell><p class="slate-p ">Planning practitioner.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">location_id</code></p></table-cell>
    <table-cell><p class="slate-p ">integer</p></table-cell>
    <table-cell><p class="slate-p ">Associated location.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">treatment_plan_status</code></p></table-cell>
    <table-cell><p class="slate-p ">string</p></table-cell>
    <table-cell><p class="slate-p ">Plan-item status.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">is_alt_plan</code></p></table-cell>
    <table-cell><p class="slate-p ">boolean</p></table-cell>
    <table-cell><p class="slate-p ">Alternative-plan flag.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">is_plan_active</code></p></table-cell>
    <table-cell><p class="slate-p ">boolean</p></table-cell>
    <table-cell><p class="slate-p ">Active-plan flag.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">appointment_id</code></p></table-cell>
    <table-cell><p class="slate-p ">integer | null</p></table-cell>
    <table-cell><p class="slate-p ">Linked appointment.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">treatment_id</code></p></table-cell>
    <table-cell><p class="slate-p ">integer | null</p></table-cell>
    <table-cell><p class="slate-p ">Linked completed treatment.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">treatment_date</code></p></table-cell>
    <table-cell><p class="slate-p ">date | null</p></table-cell>
    <table-cell><p class="slate-p ">Completion date.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">created_date</code></p></table-cell>
    <table-cell><p class="slate-p ">datetime</p></table-cell>
    <table-cell><p class="slate-p ">Record creation timestamp.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">updated_date</code></p></table-cell>
    <table-cell><p class="slate-p ">datetime</p></table-cell>
    <table-cell><p class="slate-p ">Record last-modified timestamp.</p></table-cell>
  </table-row>
</Table>

Important notes
---------------

*   **Required filters:** at least one filter parameter is required.
    
*   **Date filtering:** supports the `mode` parameter: see [Filtering & Date Ranges](/filtering-and-date-ranges).
    
*   **Default range:** applies only to unscoped queries, meaning no `patient_id` is supplied (for example a wildcard `practitioner_id=-1` or `location_id=-1` call with no dates): a 180-day window is then applied automatically when no `from_date` / `to_date` is supplied. This window does not fire once `patient_id` narrows the query: a `patient_id`-scoped call with no dates returns that patient's complete history, unwindowed.
    
*   **Wildcard values:** use `practitioner_id=-1` for all practitioners and `location_id=-1` for all locations.
    

Quick example
-------------

<CodeBlock attributes='{"isFitToPage":true,"style":{},"lang":"plainText","label":"Plain text"}'>
  <CodeLine>curl "https://api-uat.dental4web.com.au/api/v1/treatment-plans?patient_id=2&amp;per_page=10" \</CodeLine>
  <CodeLine>    -H "x-api-key: $API_KEY" \</CodeLine>
  <CodeLine>    -H "org-id: $ORG_ID" \</CodeLine>
  <CodeLine>    -H "Accept: application/json" </CodeLine>
</CodeBlock>

GET Treatment Plans

Retrieves clinical notes recorded by practitioners during patient visits. Notes include observations, diagnoses, treatment summaries, and clinical documentation.

Use cases
---------

*   Review clinical history before follow-up appointments.
    
*   Generate clinical summaries for specialist referral letters.
    
*   Audit documentation compliance for regulatory requirements.
    
*   Integrate clinical notes with external EHR/EMR systems.
    

Parameters
----------

<Table style="width:100%;min-width:100%" colSizes='["180px","135px","585px"]' isHeaderAdded='true' tableHeader='[{"id":"2cc7c669-502c-4091-aa70-68d6a0cd8bfd","title":"Parameter"},{"id":"f8bfe936-e547-40ee-97dc-e200bb04d70f","title":"Type"},{"id":"016bdc8a-d428-4647-9772-c693be3be8c8","title":"Description"}]'>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">patient_id</code></p></table-cell>
    <table-cell><p class="slate-p ">integer</p></table-cell>
    <table-cell><p class="slate-p ">Filter to a specific patient. Optional (see Important Notes: at least one filter parameter is required).</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">practitioner_id</code></p></table-cell>
    <table-cell><p class="slate-p ">integer</p></table-cell>
    <table-cell><p class="slate-p ">Filter to a specific practitioner. Use <code class="slate-code">-1</code> to return data for all practitioners. Optional.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">location_id</code></p></table-cell>
    <table-cell><p class="slate-p ">integer</p></table-cell>
    <table-cell><p class="slate-p ">Filter to a specific practice location. Use <code class="slate-code">-1</code> to return data for all locations. Optional.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">from_date</code></p></table-cell>
    <table-cell><p class="slate-p ">string (date)</p></table-cell>
    <table-cell><p class="slate-p ">Start of the date range filter. Format <code class="slate-code">YYYY-MM-DD</code>. Optional; see Important Notes for default behaviour.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">to_date</code></p></table-cell>
    <table-cell><p class="slate-p ">string (date)</p></table-cell>
    <table-cell><p class="slate-p ">End of the date range filter. Format <code class="slate-code">YYYY-MM-DD</code>. Optional; see Important Notes for default behaviour.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">mode</code></p></table-cell>
    <table-cell><p class="slate-p ">integer</p></table-cell>
    <table-cell><p class="slate-p ">Controls date filtering behaviour. <code class="slate-code">0</code> (default) = filter by business date. <code class="slate-code">1</code> = filter by modification timestamp, for sync/delta operations. See <a href="/filtering-and-date-ranges">Filtering &amp; Date Ranges</a>.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">include</code></p></table-cell>
    <table-cell><p class="slate-p ">string</p></table-cell>
    <table-cell><p class="slate-p ">Comma-separated list of related resources to embed in the response. Confirmed live: <code class="slate-code">practitioners</code>, <code class="slate-code">locations</code>, and <code class="slate-code">items</code> embed the matching practitioner, location, and item objects (combine with commas, e.g. <code class="slate-code">practitioners,locations</code>). An unrecognised value returns <code class="slate-code">400</code> listing the full server-side allowed set: <code class="slate-code">patients, practitioners, locations, appt_books, items, payment_types</code>.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">page</code></p></table-cell>
    <table-cell><p class="slate-p ">integer</p></table-cell>
    <table-cell><p class="slate-p ">Page number for paginated results (1-indexed). Optional. Default <code class="slate-code">1</code>.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">per_page</code></p></table-cell>
    <table-cell><p class="slate-p ">integer</p></table-cell>
    <table-cell><p class="slate-p ">Records per page. Optional. Default <code class="slate-code">10</code>. Maximum <code class="slate-code">500</code>.</p></table-cell>
  </table-row>
</Table>

Response fields
---------------

<Table style="width:100%;min-width:100%" colSizes='["180px","135px","585px"]' isHeaderAdded='true' tableHeader='[{"id":"5838a504-8355-4777-b873-fa177c6249f0","title":"Field"},{"id":"a3d44528-47e8-48d3-aebd-3da576f64ad7","title":"Type"},{"id":"a5237d79-7276-441e-bfe2-3911c9f6aa75","title":"Description"}]'>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">note_id</code></p></table-cell>
    <table-cell><p class="slate-p ">integer</p></table-cell>
    <table-cell><p class="slate-p ">Primary identifier.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">treatment_id</code></p></table-cell>
    <table-cell><p class="slate-p ">integer | null</p></table-cell>
    <table-cell><p class="slate-p ">Linked treatment record.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">patient_id</code></p></table-cell>
    <table-cell><p class="slate-p ">integer</p></table-cell>
    <table-cell><p class="slate-p ">Patient identifier.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">note_date</code></p></table-cell>
    <table-cell><p class="slate-p ">date</p></table-cell>
    <table-cell><p class="slate-p ">Date the note was recorded.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">note_source</code></p></table-cell>
    <table-cell><p class="slate-p ">string</p></table-cell>
    <table-cell><p class="slate-p ">Origin of the note.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">item_code</code></p></table-cell>
    <table-cell><p class="slate-p ">string | null</p></table-cell>
    <table-cell><p class="slate-p ">Associated procedure / item code.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">tooth</code></p></table-cell>
    <table-cell><p class="slate-p ">string | null</p></table-cell>
    <table-cell><p class="slate-p ">Tooth number, if recorded.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">surface</code></p></table-cell>
    <table-cell><p class="slate-p ">string | null</p></table-cell>
    <table-cell><p class="slate-p ">Tooth surface, if recorded.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">notes</code></p></table-cell>
    <table-cell><p class="slate-p ">string</p></table-cell>
    <table-cell><p class="slate-p ">Note content.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">practitioner_id</code></p></table-cell>
    <table-cell><p class="slate-p ">integer</p></table-cell>
    <table-cell><p class="slate-p ">Authoring practitioner.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">location_id</code></p></table-cell>
    <table-cell><p class="slate-p ">integer</p></table-cell>
    <table-cell><p class="slate-p ">Location where the note was recorded.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">created_date</code></p></table-cell>
    <table-cell><p class="slate-p ">datetime</p></table-cell>
    <table-cell><p class="slate-p ">Record creation timestamp.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">updated_date</code></p></table-cell>
    <table-cell><p class="slate-p ">datetime</p></table-cell>
    <table-cell><p class="slate-p ">Record last-modified timestamp.</p></table-cell>
  </table-row>
</Table>

Important notes
---------------

*   **Required filters:** at least one filter parameter is required.
    
*   **Date filtering:** supports the `mode` parameter: see [Filtering & Date Ranges](/filtering-and-date-ranges).
    
*   **Default range:** applies only to unscoped queries, meaning no `patient_id` is supplied (for example a wildcard `practitioner_id=-1` or `location_id=-1` call with no dates): a 90-day window is then applied automatically when no `from_date` / `to_date` is supplied. This window does not fire once `patient_id` narrows the query: a `patient_id`-scoped call with no dates returns that patient's complete history, unwindowed.
    
*   **Wildcard values:** use `practitioner_id=-1` for all practitioners and `location_id=-1` for all locations.
    

Quick example
-------------

<CodeBlock attributes='{"isFitToPage":true,"style":{},"lang":"plainText","label":"Plain text"}'>
  <CodeLine>curl "https://api-uat.dental4web.com.au/api/v1/clinical-notes?patient_id=72&amp;per_page=10" \</CodeLine>
  <CodeLine>    -H "x-api-key: $API_KEY" \</CodeLine>
  <CodeLine>    -H "org-id: $ORG_ID" \</CodeLine>
  <CodeLine>    -H "Accept: application/json" </CodeLine>
</CodeBlock>

GET Clinical Notes

Creates a clinical note for a patient. The note is stored as a clinical/treatment record, and the response returns the new record’s `treatment_id`.

Request body
------------

<Table style="width:100%;min-width:100%" colSizes='["180px","135px","585px"]' isHeaderAdded='true' tableHeader='[{"id":"365a8c16-85ce-4416-ba58-05679cc2e88a","title":"Field"},{"id":"b3e4e041-00ff-4756-9ad5-4cd1d623fad0","title":"Type"},{"id":"8a040664-228b-488c-a35c-b09a96f157bb","title":"Description"}]'>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">patient_id</code></p></table-cell>
    <table-cell><p class="slate-p ">integer</p></table-cell>
    <table-cell><p class="slate-p ">Required. Patient the note belongs to.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">note</code></p></table-cell>
    <table-cell><p class="slate-p ">string</p></table-cell>
    <table-cell><p class="slate-p ">Required. Free-text note content, up to 20,000 characters. Submit as plain text.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">practitioner_id</code></p></table-cell>
    <table-cell><p class="slate-p ">integer</p></table-cell>
    <table-cell><p class="slate-p ">Authoring practitioner. If omitted, the patient's default is applied and returned in the response.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">location_id</code></p></table-cell>
    <table-cell><p class="slate-p ">integer</p></table-cell>
    <table-cell><p class="slate-p ">Location where the note is recorded. If omitted, the patient's default is applied and returned in the response.</p></table-cell>
  </table-row>
</Table>

Returns
-------

A `200` response returns the persisted note as a clinical/treatment record. It includes both a `note_id` (the note’s own identifier) and a `treatment_id` (the identifier of the underlying treatment record the note is attached to), which are two distinct IDs, not aliases of each other, plus the resolved `practitioner_id` and `location_id`, and a `pagination` block.

<CodeBlock attributes='{"isFitToPage":true,"style":{},"lang":"json","label":"JSON"}'>
  <CodeLine></CodeLine>
  <CodeLine>  {</CodeLine>
  <CodeLine>    "status": true,</CodeLine>
  <CodeLine>    "message": "Success",</CodeLine>
  <CodeLine>    "data": [</CodeLine>
  <CodeLine>      {</CodeLine>
  <CodeLine>        "note_id": 8043040,</CodeLine>
  <CodeLine>        "treatment_id": 1043040,</CodeLine>
  <CodeLine>        "patient_id": 25407,</CodeLine>
  <CodeLine>        "note_date": "2026-05-27",</CodeLine>
  <CodeLine>        "note_source": "Treatment",</CodeLine>
  <CodeLine>        "item_code": "9999",</CodeLine>
  <CodeLine>        "tooth": "",</CodeLine>
  <CodeLine>        "surface": "",</CodeLine>
  <CodeLine>        "notes": "Patient reports sensitivity on upper left.",</CodeLine>
  <CodeLine>        "practitioner_id": 315,</CodeLine>
  <CodeLine>        "location_id": 4,</CodeLine>
  <CodeLine>        "created_date": "2026-05-27T22:31:18.689000",</CodeLine>
  <CodeLine>        "updated_date": "2026-05-27T22:31:18.689000"</CodeLine>
  <CodeLine>      }</CodeLine>
  <CodeLine>    ],</CodeLine>
  <CodeLine>    "pagination": {</CodeLine>
  <CodeLine>      "page": 1,</CodeLine>
  <CodeLine>      "per_page": 100,</CodeLine>
  <CodeLine>      "total_rows": 1,</CodeLine>
  <CodeLine>      "total_pages": 1</CodeLine>
  <CodeLine>    }</CodeLine>
  <CodeLine>  }</CodeLine>
</CodeBlock>

Error responses
---------------

Clinical notes use the standard write-validation pipeline. Missing parameters return `RP-4000`, a non-integer `patient_id` returns `TYP-INT`, and a non-existent patient reuses the patient code `PW-6013`. See [Validation, Limits & Character Handling](/validation-limits-and-character-handling) for the full catalogue. The examples below are live-verified against Sandbox.

<Table style="width:100%;min-width:100%" colSizes='["180px","135px","585px"]' isHeaderAdded='true' tableHeader='[{"id":"61dd7530-c203-4779-8514-d25ef2e1b9a5","title":"Status"},{"id":"712c188b-4101-4acb-8a0c-afbd7ead0787","title":"support_code"},{"id":"c6458104-5da6-4168-bb57-3bfae30896ca","title":"Meaning"}]'>
  <table-row>
    <table-cell><p class="slate-p ">400</p></table-cell>
    <table-cell><p class="slate-p "><code class="slate-code">RP-4000</code></p></table-cell>
    <table-cell><p class="slate-p "><code class="slate-code">patient_id</code> and/or <code class="slate-code">note</code> missing.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p ">400</p></table-cell>
    <table-cell><p class="slate-p "><code class="slate-code">TYP-INT</code></p></table-cell>
    <table-cell><p class="slate-p "><code class="slate-code">patient_id</code> is not an integer.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p ">400</p></table-cell>
    <table-cell><p class="slate-p "><code class="slate-code">AW-6026</code></p></table-cell>
    <table-cell><p class="slate-p ">A field exceeds the maximum length the practice management system accepts after special characters were converted to plain text (for example <code class="slate-code">note</code> over 20,000 characters). Shorten the affected field and resubmit.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p ">400</p></table-cell>
    <table-cell><p class="slate-p ">None</p></table-cell>
    <table-cell><p class="slate-p ">Content rejected by the security policy (HTML/script-shaped, or an over-length or unusual payload).</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p ">400</p></table-cell>
    <table-cell><p class="slate-p ">None</p></table-cell>
    <table-cell><p class="slate-p "><code class="slate-code">org-id</code> not associated with the supplied key.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p ">403</p></table-cell>
    <table-cell><p class="slate-p ">None</p></table-cell>
    <table-cell><p class="slate-p ">Missing or invalid <code class="slate-code">x-api-key</code>.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p ">404</p></table-cell>
    <table-cell><p class="slate-p "><code class="slate-code">PW-6013</code></p></table-cell>
    <table-cell><p class="slate-p "><code class="slate-code">patient_id</code> not found.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p ">429</p></table-cell>
    <table-cell><p class="slate-p "><code class="slate-code">RL-001</code></p></table-cell>
    <table-cell><p class="slate-p ">Rate limit exceeded; honour the <code class="slate-code">Retry-After</code> header / <code class="slate-code">retry_after</code> field.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p ">500</p></table-cell>
    <table-cell><p class="slate-p ">None</p></table-cell>
    <table-cell><p class="slate-p ">Unexpected internal error.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p ">502</p></table-cell>
    <table-cell><p class="slate-p ">None</p></table-cell>
    <table-cell><p class="slate-p ">Temporary service unavailability.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p ">503</p></table-cell>
    <table-cell><p class="slate-p ">None</p></table-cell>
    <table-cell><p class="slate-p ">Service temporarily unavailable.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p ">504</p></table-cell>
    <table-cell><p class="slate-p ">None</p></table-cell>
    <table-cell><p class="slate-p ">Timeout.</p></table-cell>
  </table-row>
</Table>

Required parameter missing (`400`):

<CodeBlock attributes='{"isFitToPage":true,"style":{},"lang":"json","label":"JSON"}'>
  <CodeLine></CodeLine>
  <CodeLine>  { "data": [], "status": false, "message": "Missing required parameters: patient_id. Both patient_id and note parameters are required", "support_code": "RP-4000" }</CodeLine>
</CodeBlock>

`patient_id` not an integer (`400`):

<CodeBlock attributes='{"isFitToPage":true,"style":{},"lang":"json","label":"JSON"}'>
  <CodeLine></CodeLine>
  <CodeLine>  { "data": [], "status": false, "message": "patient_id must be an INTEGER; got non-numeric value", "support_code": "TYP-INT" }</CodeLine>
</CodeBlock>

`note` exceeds the maximum length (`400`):

<CodeBlock attributes='{"isFitToPage":true,"style":{},"lang":"json","label":"JSON"}'>
  <CodeLine></CodeLine>
  <CodeLine>  { "data": [], "status": false, "message": "One or more fields exceed the maximum length the practice management system accepts after special characters were converted to plain text (fields: note (20001&gt;20000)). Shorten the affected field(s) and resubmit. [AW-6026]", "support_code": "AW-6026" }</CodeLine>
</CodeBlock>

Patient not found (`404`):

<CodeBlock attributes='{"isFitToPage":true,"style":{},"lang":"json","label":"JSON"}'>
  <CodeLine></CodeLine>
  <CodeLine>  { "data": [], "status": false, "message": "Patient 999999999 not found.", "support_code": "PW-6013" }</CodeLine>
</CodeBlock>

Content rejected by security policy (`400`):

<CodeBlock attributes='{"isFitToPage":true,"style":{},"lang":"json","label":"JSON"}'>
  <CodeLine></CodeLine>
  <CodeLine>  { "data": [], "status": false, "message": "Request rejected by security policy. Check your input does not contain HTML or script content." }</CodeLine>
</CodeBlock>

Invalid or missing API key (`403`):

<CodeBlock attributes='{"isFitToPage":true,"style":{},"lang":"json","label":"JSON"}'>
  <CodeLine></CodeLine>
  <CodeLine>  { "message": "Forbidden" }</CodeLine>
</CodeBlock>

Organisation not associated with the key (`400`):

<CodeBlock attributes='{"isFitToPage":true,"style":{},"lang":"json","label":"JSON"}'>
  <CodeLine></CodeLine>
  <CodeLine>  { "data": [], "status": false, "message": "Given Organisation NOPE123 is not associated with provided token." }</CodeLine>
</CodeBlock>

Rate limit exceeded (`429`):

<CodeBlock attributes='{"isFitToPage":true,"style":{},"lang":"json","label":"JSON"}'>
  <CodeLine></CodeLine>
  <CodeLine>  { "data": [], "status": false, "message": "Rate limit exceeded. Please retry after the indicated time.", "retry_after": 60, "support_code": "RL-001" }</CodeLine>
</CodeBlock>

Important notes
---------------

*   Required fields are `patient_id` and `note`. `practitioner_id` and `location_id` are optional.
    
*   `note` is free text up to **20,000 characters**.
    
*   The note is persisted as a clinical/treatment record; the `200` response returns both a `note_id` and a `treatment_id` (distinct identifiers, not aliases of each other).
    
*   If `practitioner_id` or `location_id` are omitted, the patient’s defaults are applied and returned in the response.
    
*   The `fhir` query parameter is ignored on write endpoints. FHIR formatting is available on read endpoints only; use `GET /api/v1/fhir/clinical-notes` to read notes as FHIR Observation resources.
    
*   `patient_id` (and `practitioner_id` / `location_id`) must be integers; a non-numeric `patient_id` is rejected with `TYP-INT`.
    
*   Submit `note` as plain text. Content that looks like HTML or script, and very long or unusual payloads, is rejected by the security policy with a `400`.
    

Quick example
-------------

<CodeBlock attributes='{"isFitToPage":true,"style":{},"lang":"plainText","label":"Plain text"}'>
  <CodeLine>curl -X POST "https://api-uat.dental4web.com.au/api/v1/clinical-notes" \</CodeLine>
  <CodeLine>    -H "x-api-key: $API_KEY" \</CodeLine>
  <CodeLine>    -H "org-id: $ORG_ID" \</CodeLine>
  <CodeLine>    -H "Content-Type: application/json" \</CodeLine>
  <CodeLine>    -H "Accept: application/json" \</CodeLine>
  <CodeLine>    -d '{"patient_id": 25407, "note": "Patient reports sensitivity on upper left."}' </CodeLine>
</CodeBlock>

POST Clinical Notes

The Reference Data Resources API provides access to essential configuration and operational data in the Dental4Web Practice Management System. These resources are not patient treatment records, but rather supporting datasets that define the structure, people, and reference data used across other APIs. They are especially important for linking appointments, treatments, and financial transactions to the correct practitioner, location, or appointment book, integrating reference data like procedure codes and payment types, and managing user and recall reminder records.

<Table style="width:100%;min-width:100%" colSizes='["270px","630px"]' isHeaderAdded='true' tableHeader='[{"id":"61cce880-ae34-4cb8-8cae-04c18e47e1a7","title":"Group"},{"id":"e2a28040-170b-45e2-bc59-61ed095356a9","title":"Endpoint"},{"id":"8020e8bd-d452-4a3a-898c-d5536177d694","title":"Returns"}]'>
  <table-row>
    <table-cell><p class="slate-p ">People</p></table-cell>
    <table-cell><p class="slate-p "><code class="slate-code">GET /api/v1/practitioners</code></p></table-cell>
    <table-cell><p class="slate-p ">Active and inactive practitioners. Optional <code class="slate-code">location_id</code> filter.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p ">People</p></table-cell>
    <table-cell><p class="slate-p "><code class="slate-code">GET /api/v1/users</code></p></table-cell>
    <table-cell><p class="slate-p ">All system users (clinical + administrative). Optional <code class="slate-code">location_id</code>.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p ">Places</p></table-cell>
    <table-cell><p class="slate-p "><code class="slate-code">GET /api/v1/locations</code></p></table-cell>
    <table-cell><p class="slate-p ">All practice locations (clinic addresses, contact info).</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p ">Scheduling</p></table-cell>
    <table-cell><p class="slate-p "><code class="slate-code">GET /api/v1/appointment-books</code></p></table-cell>
    <table-cell><p class="slate-p ">All appointment books, with operating hours per book.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p ">Scheduling</p></table-cell>
    <table-cell><p class="slate-p "><code class="slate-code">GET /api/v1/appointment-classes</code></p></table-cell>
    <table-cell><p class="slate-p ">Appointment class options (e.g. Consultation, Filling).</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p ">Scheduling</p></table-cell>
    <table-cell><p class="slate-p "><code class="slate-code">GET /api/v1/slot-types</code></p></table-cell>
    <table-cell><p class="slate-p ">Bookable slot types (vacant time + preset templates).</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p ">Scheduling</p></table-cell>
    <table-cell><p class="slate-p "><code class="slate-code">GET /api/v1/cancel-reasons</code></p></table-cell>
    <table-cell><p class="slate-p ">Active cancel-reason IDs used by the cancel endpoint.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p ">Codes</p></table-cell>
    <table-cell><p class="slate-p "><code class="slate-code">GET /api/v1/items</code></p></table-cell>
    <table-cell><p class="slate-p ">All procedure/treatment items (e.g. ADA codes).</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p ">Codes</p></table-cell>
    <table-cell><p class="slate-p "><code class="slate-code">GET /api/v1/payment-types</code></p></table-cell>
    <table-cell><p class="slate-p ">All configured payment types.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p ">Patients</p></table-cell>
    <table-cell><p class="slate-p "><code class="slate-code">GET /api/v1/titles</code></p></table-cell>
    <table-cell><p class="slate-p ">Patient title options for create/update.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p ">Recalls</p></table-cell>
    <table-cell><p class="slate-p "><code class="slate-code">GET /api/v1/recalls</code></p></table-cell>
    <table-cell><p class="slate-p ">Practice-wide recall records. <strong class="slate-bold">Requires ≥1 filter parameter</strong> (HTTP 400 otherwise).</p></table-cell>
  </table-row>
</Table>

Reference Data Resources

Retrieves appointment book configurations for the organisation. An appointment book is a schedulable resource (typically a practitioner’s chair or room) with operating hours and an associated location.

Use cases
---------

*   Map appointments to the correct practitioner or resource.
    
*   Build scheduling interfaces that respect operating hours.
    
*   Manage multiple schedules within a single location.
    
*   Display available booking slots.
    

Response fields
---------------

<Table style="width:100%;min-width:100%" colSizes='["180px","135px","585px"]' isHeaderAdded='true' tableHeader='[{"id":"2cc26d1f-af76-4854-a64f-9652de942a24","title":"Field"},{"id":"0a228432-6c95-44f8-9be8-30c0cf139392","title":"Type"},{"id":"e8d2e177-848f-49f7-92ba-32b59a1771b2","title":"Description"}]'>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">appt_book_id</code></p></table-cell>
    <table-cell><p class="slate-p ">integer</p></table-cell>
    <table-cell><p class="slate-p ">Primary identifier.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">appt_book_name</code></p></table-cell>
    <table-cell><p class="slate-p ">string</p></table-cell>
    <table-cell><p class="slate-p ">Book / resource name.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">location_id</code></p></table-cell>
    <table-cell><p class="slate-p ">integer</p></table-cell>
    <table-cell><p class="slate-p ">Associated location.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">start_time</code></p></table-cell>
    <table-cell><p class="slate-p ">time</p></table-cell>
    <table-cell><p class="slate-p ">Operating start time.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">end_time</code></p></table-cell>
    <table-cell><p class="slate-p ">time</p></table-cell>
    <table-cell><p class="slate-p ">Operating end time.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">is_active</code></p></table-cell>
    <table-cell><p class="slate-p ">boolean</p></table-cell>
    <table-cell><p class="slate-p ">Active status.</p></table-cell>
  </table-row>
</Table>

Important notes
---------------

*   This endpoint supports only pagination and, where applicable, the `location_id` / `include` filters. There are no date or business filters.
    
*   **No one-to-one enforcement.** A practitioner is not rigidly bound to a single appointment book: any active practitioner can be booked into any active appointment book, regardless of which book they are nominally attached to. Where a practice has assigned a practitioner a default book, it is returned via the `appt_book_id` field on [Get practitioners](/reference-data-resources/get-practitioners).
    
*   **Naming has no fixed convention.** `appt_book_name` is free text set by the practice: some organisations name a book after the practitioner assigned to it (for example "Dr Smith"), others after the physical resource (for example "Room 2", "Chair 4"). Don't assume a naming pattern or try to parse structure out of this field.
    

Quick example
-------------

<CodeBlock attributes='{"isFitToPage":true,"style":{},"lang":"plainText","label":"Plain text"}'>
  <CodeLine>curl "https://api-uat.dental4web.com.au/api/v1/appointment-books?per_page=10" \</CodeLine>
  <CodeLine>    -H "x-api-key: $API_KEY" \</CodeLine>
  <CodeLine>    -H "org-id: $ORG_ID" \</CodeLine>
  <CodeLine>    -H "Accept: application/json" </CodeLine>
</CodeBlock>

GET Appointment Books

Returns all configured appointment classes (for example Consultation, Filling, Scale and Clean). Use `class_id` to populate appointment-class pickers and to supply the appointment class to POST /api/v1/appointments.

Response fields
---------------

<Table style="width:100%;min-width:100%" colSizes='["180px","135px","585px"]' isHeaderAdded='true' tableHeader='[{"id":"4c08d5cd-02d3-45f4-9bca-ff47b695a2e5","title":"Field"},{"id":"add50a14-becb-4777-9611-c8163b5c294e","title":"Type"},{"id":"7c4ccedd-b2f2-4f30-acbe-13107629d496","title":"Description"}]'>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">class_id</code></p></table-cell>
    <table-cell><p class="slate-p ">integer</p></table-cell>
    <table-cell><p class="slate-p ">Appointment-class identifier.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">class_name</code></p></table-cell>
    <table-cell><p class="slate-p ">string</p></table-cell>
    <table-cell><p class="slate-p ">Class name.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">is_active</code></p></table-cell>
    <table-cell><p class="slate-p ">integer</p></table-cell>
    <table-cell><p class="slate-p ">1 if active, 0 if not.</p></table-cell>
  </table-row>
</Table>

Quick example
-------------

<CodeBlock attributes='{"isFitToPage":true,"style":{},"lang":"plainText","label":"Plain text"}'>
  <CodeLine>curl "https://api-uat.dental4web.com.au/api/v1/appointment-classes?per_page=10" \</CodeLine>
  <CodeLine>    -H "x-api-key: $API_KEY" \</CodeLine>
  <CodeLine>    -H "org-id: $ORG_ID" \</CodeLine>
  <CodeLine>    -H "Accept: application/json" </CodeLine>
</CodeBlock>

GET Appointment Classes

Returns all active cancellation reasons. Use `cancel_reason_id` to supply the cancellation reason to POST /api/v1/appointments/{id}/cancel.

Response fields
---------------

<Table style="width:100%;min-width:100%" colSizes='["180px","135px","585px"]' isHeaderAdded='true' tableHeader='[{"id":"0565ed63-cb0d-4505-bb77-e7d206625189","title":"Field"},{"id":"2964842c-3009-436c-8be2-45c1e02dd62f","title":"Type"},{"id":"e8880638-a802-434d-ba65-ebb4b5e815da","title":"Description"}]'>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">cancel_reason_id</code></p></table-cell>
    <table-cell><p class="slate-p ">integer</p></table-cell>
    <table-cell><p class="slate-p ">Cancellation-reason identifier.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">reason_description</code></p></table-cell>
    <table-cell><p class="slate-p ">string</p></table-cell>
    <table-cell><p class="slate-p ">Reason text.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">sort_order</code></p></table-cell>
    <table-cell><p class="slate-p ">integer</p></table-cell>
    <table-cell><p class="slate-p ">Display sort order.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">is_system</code></p></table-cell>
    <table-cell><p class="slate-p ">boolean</p></table-cell>
    <table-cell><p class="slate-p ">True for built-in system reasons.</p></table-cell>
  </table-row>
</Table>

Quick example
-------------

<CodeBlock attributes='{"isFitToPage":true,"style":{},"lang":"plainText","label":"Plain text"}'>
  <CodeLine>curl "https://api-uat.dental4web.com.au/api/v1/cancel-reasons?per_page=10" \</CodeLine>
  <CodeLine>    -H "x-api-key: $API_KEY" \</CodeLine>
  <CodeLine>    -H "org-id: $ORG_ID" \</CodeLine>
  <CodeLine>    -H "Accept: application/json" </CodeLine>
</CodeBlock>

GET Cancel Reasons

Retrieves the practice locations (clinics, branches) within the organisation. Locations let multi-site practices associate patient records, appointments, and billing with the correct branch.

Use cases
---------

*   Build location selection dropdowns for booking interfaces.
    
*   Display practice addresses on appointment confirmations.
    
*   Filter reports and data by location.
    
*   Sync the location directory to external systems.
    

Response fields
---------------

<Table style="width:100%;min-width:100%" colSizes='["180px","135px","585px"]' isHeaderAdded='true' tableHeader='[{"id":"3b899b25-78d0-41f1-8cc4-896625f2933f","title":"Field"},{"id":"4f73a3bb-867c-4b00-a557-844cb7a854ba","title":"Type"},{"id":"8db075f5-4da5-4308-9b9f-fd3fd420376f","title":"Description"}]'>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">location_id</code></p></table-cell>
    <table-cell><p class="slate-p ">integer</p></table-cell>
    <table-cell><p class="slate-p ">Primary identifier.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">location_name</code></p></table-cell>
    <table-cell><p class="slate-p ">string</p></table-cell>
    <table-cell><p class="slate-p ">Location / branch name.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">address</code></p></table-cell>
    <table-cell><p class="slate-p ">string</p></table-cell>
    <table-cell><p class="slate-p ">Full street address.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">phone</code></p></table-cell>
    <table-cell><p class="slate-p ">string</p></table-cell>
    <table-cell><p class="slate-p ">Contact phone number.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">email</code></p></table-cell>
    <table-cell><p class="slate-p ">string</p></table-cell>
    <table-cell><p class="slate-p ">Contact email.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">is_active</code></p></table-cell>
    <table-cell><p class="slate-p ">boolean</p></table-cell>
    <table-cell><p class="slate-p ">Active status.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">updated_date</code></p></table-cell>
    <table-cell><p class="slate-p ">datetime</p></table-cell>
    <table-cell><p class="slate-p ">Record last-modified timestamp.</p></table-cell>
  </table-row>
</Table>

Important notes
---------------

*   This endpoint supports only pagination (`page`/`per_page`). There are no date or business filters.
    

Quick example
-------------

<CodeBlock attributes='{"isFitToPage":true,"style":{},"lang":"plainText","label":"Plain text"}'>
  <CodeLine>curl "https://api-uat.dental4web.com.au/api/v1/locations?per_page=10" \</CodeLine>
  <CodeLine>    -H "x-api-key: $API_KEY" \</CodeLine>
  <CodeLine>    -H "org-id: $ORG_ID" \</CodeLine>
  <CodeLine>    -H "Accept: application/json" </CodeLine>
</CodeBlock>

GET Locations

Returns all configured payment methods (Cash, EFTPOS, HealthFund variants, custom types, and so on). Use `payment_type_id` to interpret the `payment_type_id` field returned by GET /api/v1/receipts/{id}.

Response fields
---------------

<Table style="width:100%;min-width:100%" colSizes='["180px","135px","585px"]' isHeaderAdded='true' tableHeader='[{"id":"c380c52c-48cc-4e22-954d-d8524c21b2ac","title":"Field"},{"id":"7ee646c1-acd8-47c8-9217-27f17ec7505d","title":"Type"},{"id":"0eeeafc8-6796-4789-a62c-bd925ca200e9","title":"Description"}]'>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">payment_type_id</code></p></table-cell>
    <table-cell><p class="slate-p ">integer</p></table-cell>
    <table-cell><p class="slate-p ">Primary identifier.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">payment_type</code></p></table-cell>
    <table-cell><p class="slate-p ">string</p></table-cell>
    <table-cell><p class="slate-p ">Payment method name.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">reporting_name</code></p></table-cell>
    <table-cell><p class="slate-p ">string</p></table-cell>
    <table-cell><p class="slate-p ">Name used in reports.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">show_in_reports</code></p></table-cell>
    <table-cell><p class="slate-p ">boolean</p></table-cell>
    <table-cell><p class="slate-p ">Whether the type appears in reports.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">is_deleted</code></p></table-cell>
    <table-cell><p class="slate-p ">boolean</p></table-cell>
    <table-cell><p class="slate-p ">Soft-delete flag.</p></table-cell>
  </table-row>
</Table>

Important notes
---------------

*   This endpoint supports only pagination (`page`/`per_page`). There are no date or business filters.
    

Quick example
-------------

<CodeBlock attributes='{"isFitToPage":true,"style":{},"lang":"plainText","label":"Plain text"}'>
  <CodeLine>curl "https://api-uat.dental4web.com.au/api/v1/payment-types?per_page=10" \</CodeLine>
  <CodeLine>    -H "x-api-key: $API_KEY" \</CodeLine>
  <CodeLine>    -H "org-id: $ORG_ID" \</CodeLine>
  <CodeLine>    -H "Accept: application/json" </CodeLine>
</CodeBlock>

GET Payment Types

Retrieves the practitioners (dentists, hygienists, and other clinical staff) within the organisation. Practitioners link appointments, treatments, and billing to the correct healthcare provider.

Use cases
---------

*   Build practitioner selection dropdowns for booking interfaces.
    
*   Display practitioner information on appointment confirmations.
    
*   Map appointment data to the correct practitioners for reporting.
    
*   Sync the practitioner directory to external systems.
    

Response fields
---------------

<Table style="width:100%;min-width:100%" colSizes='["180px","135px","585px"]' isHeaderAdded='true' tableHeader='[{"id":"b3cd576e-541f-4349-929b-a3033699791c","title":"Field"},{"id":"75d2219e-c956-431d-9401-bab7b0b09c2d","title":"Type"},{"id":"269b70ef-fd68-435f-a89e-7b6795fb23f4","title":"Description"}]'>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">practitioner_id</code></p></table-cell>
    <table-cell><p class="slate-p ">integer</p></table-cell>
    <table-cell><p class="slate-p ">Practitioner identifier.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">is_active</code></p></table-cell>
    <table-cell><p class="slate-p ">boolean</p></table-cell>
    <table-cell><p class="slate-p ">Active status.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">practitioner_code</code></p></table-cell>
    <table-cell><p class="slate-p ">string</p></table-cell>
    <table-cell><p class="slate-p ">Short code.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">full_name</code></p></table-cell>
    <table-cell><p class="slate-p ">string</p></table-cell>
    <table-cell><p class="slate-p ">Full display name.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">first_name</code></p></table-cell>
    <table-cell><p class="slate-p ">string</p></table-cell>
    <table-cell><p class="slate-p ">First name.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">surname</code></p></table-cell>
    <table-cell><p class="slate-p ">string</p></table-cell>
    <table-cell><p class="slate-p ">Surname.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">title</code></p></table-cell>
    <table-cell><p class="slate-p ">string</p></table-cell>
    <table-cell><p class="slate-p ">Title (Dr / Mr / Ms).</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">role</code></p></table-cell>
    <table-cell><p class="slate-p ">string</p></table-cell>
    <table-cell><p class="slate-p ">Role (Dentist / Hygienist).</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">location_id</code></p></table-cell>
    <table-cell><p class="slate-p ">integer</p></table-cell>
    <table-cell><p class="slate-p ">Primary location.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">appt_book_id</code></p></table-cell>
    <table-cell><p class="slate-p ">integer | null</p></table-cell>
    <table-cell><p class="slate-p ">The practitioner's default appointment book, where one is set.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">provider_number</code></p></table-cell>
    <table-cell><p class="slate-p ">string | null</p></table-cell>
    <table-cell><p class="slate-p ">Provider number.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">qualifications</code></p></table-cell>
    <table-cell><p class="slate-p ">string | null</p></table-cell>
    <table-cell><p class="slate-p ">Qualifications.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">updated_date</code></p></table-cell>
    <table-cell><p class="slate-p ">datetime</p></table-cell>
    <table-cell><p class="slate-p ">Record last-modified timestamp.</p></table-cell>
  </table-row>
</Table>

Important notes
---------------

*   Optional filter: use `location_id` to filter by a specific location.
    
*   All practitioners: omit `location_id` to retrieve every practitioner across the organisation.
    

Quick example
-------------

<CodeBlock attributes='{"isFitToPage":true,"style":{},"lang":"plainText","label":"Plain text"}'>
  <CodeLine>curl "https://api-uat.dental4web.com.au/api/v1/practitioners?per_page=10" \</CodeLine>
  <CodeLine>    -H "x-api-key: $API_KEY" \</CodeLine>
  <CodeLine>    -H "org-id: $ORG_ID" \</CodeLine>
  <CodeLine>    -H "Accept: application/json" </CodeLine>
</CodeBlock>

GET Practitioners

Retrieves the procedure codes (item codes) used for treatments and billing. Each item includes its ADA code, description, category, and reporting flags, keeping treatment descriptions and billing consistent across integrations.

Use cases
---------

*   Map item codes to procedure descriptions for display.
    
*   Build treatment selection interfaces.
    
*   Validate item codes during data import.
    
*   Generate procedure category reports.
    

Response fields
---------------

<Table style="width:100%;min-width:100%" colSizes='["180px","135px","585px"]' isHeaderAdded='true' tableHeader='[{"id":"a37406e6-3cd9-4071-a116-982547d43855","title":"Field"},{"id":"dd83dc64-dff5-493d-be33-72a689781633","title":"Type"},{"id":"ab026e6e-5e70-4b84-a321-ec6d9c801ad5","title":"Description"}]'>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">item_code</code></p></table-cell>
    <table-cell><p class="slate-p ">string</p></table-cell>
    <table-cell><p class="slate-p ">Procedure code.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">ada_code</code></p></table-cell>
    <table-cell><p class="slate-p ">string</p></table-cell>
    <table-cell><p class="slate-p ">ADA (Australian Dental Association) code.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">description</code></p></table-cell>
    <table-cell><p class="slate-p ">string</p></table-cell>
    <table-cell><p class="slate-p ">Procedure description.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">category</code></p></table-cell>
    <table-cell><p class="slate-p ">string</p></table-cell>
    <table-cell><p class="slate-p ">Category / grouping.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">sub_category</code></p></table-cell>
    <table-cell><p class="slate-p ">string</p></table-cell>
    <table-cell><p class="slate-p ">Sub-category / grouping.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">non_reporting</code></p></table-cell>
    <table-cell><p class="slate-p ">boolean</p></table-cell>
    <table-cell><p class="slate-p ">Excluded from reporting.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">non_treatment</code></p></table-cell>
    <table-cell><p class="slate-p ">boolean</p></table-cell>
    <table-cell><p class="slate-p ">Not a treatment item.</p></table-cell>
  </table-row>
</Table>

Important notes
---------------

*   This endpoint supports only pagination (`page`/`per_page`). There are no date or business filters.
    
*   Large dataset: may return 1000+ records: use pagination.
    

Quick example
-------------

<CodeBlock attributes='{"isFitToPage":true,"style":{},"lang":"plainText","label":"Plain text"}'>
  <CodeLine>curl "https://api-uat.dental4web.com.au/api/v1/items?per_page=10" \</CodeLine>
  <CodeLine>    -H "x-api-key: $API_KEY" \</CodeLine>
  <CodeLine>    -H "org-id: $ORG_ID" \</CodeLine>
  <CodeLine>    -H "Accept: application/json" </CodeLine>
</CodeBlock>

GET Procedure Codes

Retrieves recall records across multiple patients, practitioners, and locations. Unlike the patient-specific `/patients/{id}/recalls` endpoint, this endpoint supports organisation-wide recall queries with comprehensive filtering.

Use cases
---------

*   Generate practice-wide recall due lists for outreach campaigns.
    
*   Build recall management dashboards showing upcoming reminders.
    
*   Analyse recall compliance rates across locations or practitioners.
    
*   Identify overdue recalls requiring urgent follow-up.
    

Parameters
----------

<Table style="width:100%;min-width:100%" colSizes='["180px","135px","585px"]' isHeaderAdded='true' tableHeader='[{"id":"2c0a7da0-ccb9-4f29-b2da-f626e39e9579","title":"Parameter"},{"id":"771d3784-68d5-4c57-8288-a6ed6693078e","title":"Type"},{"id":"ee4ce745-9596-4c59-af39-6b06bb305b8c","title":"Description"}]'>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">patient_id</code></p></table-cell>
    <table-cell><p class="slate-p ">integer</p></table-cell>
    <table-cell><p class="slate-p ">Filter recalls to a specific patient. Optional.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">practitioner_id</code></p></table-cell>
    <table-cell><p class="slate-p ">integer</p></table-cell>
    <table-cell><p class="slate-p ">Filter recalls to a specific practitioner. Use <code class="slate-code">-1</code> for all practitioners. Optional.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">location_id</code></p></table-cell>
    <table-cell><p class="slate-p ">integer</p></table-cell>
    <table-cell><p class="slate-p ">Filter recalls to a specific location. Use <code class="slate-code">-1</code> for all locations. Optional.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">from_date</code></p></table-cell>
    <table-cell><p class="slate-p ">string (date)</p></table-cell>
    <table-cell><p class="slate-p ">Start of the recall date range filter. Format <code class="slate-code">YYYY-MM-DD</code>. Optional; see Important Notes for default behaviour.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">to_date</code></p></table-cell>
    <table-cell><p class="slate-p ">string (date)</p></table-cell>
    <table-cell><p class="slate-p ">End of the recall date range filter. Format <code class="slate-code">YYYY-MM-DD</code>. Optional; see Important Notes for default behaviour.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">include</code></p></table-cell>
    <table-cell><p class="slate-p ">string</p></table-cell>
    <table-cell><p class="slate-p ">Comma-separated list of related resources to embed. Confirmed live: <code class="slate-code">practitioners</code> and <code class="slate-code">locations</code> embed the matching practitioner and location objects (combine with commas, e.g. <code class="slate-code">practitioners,locations</code>). An unrecognised value returns <code class="slate-code">400</code> listing the full server-side allowed set: <code class="slate-code">patients, practitioners, locations, appt_books, items, payment_types</code>.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">page</code></p></table-cell>
    <table-cell><p class="slate-p ">integer</p></table-cell>
    <table-cell><p class="slate-p ">Page number for paginated results. Optional. Default <code class="slate-code">1</code>.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">per_page</code></p></table-cell>
    <table-cell><p class="slate-p ">integer</p></table-cell>
    <table-cell><p class="slate-p ">Records per page. Optional. Default <code class="slate-code">10</code>. Maximum <code class="slate-code">500</code>.</p></table-cell>
  </table-row>
</Table>

Response fields
---------------

<Table style="width:100%;min-width:100%" colSizes='["180px","135px","585px"]' isHeaderAdded='true' tableHeader='[{"id":"3c00eea5-c659-453f-a285-35485c985f26","title":"Field"},{"id":"846a5738-b6e1-4be4-b5c2-31b07d4df2d2","title":"Type"},{"id":"df8e6d80-87d8-4e31-b0ef-21a00e804532","title":"Description"}]'>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">recall_type_id</code></p></table-cell>
    <table-cell><p class="slate-p ">integer</p></table-cell>
    <table-cell><p class="slate-p ">Recall type identifier.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">patient_id</code></p></table-cell>
    <table-cell><p class="slate-p ">integer</p></table-cell>
    <table-cell><p class="slate-p ">Patient identifier.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">recall_date</code></p></table-cell>
    <table-cell><p class="slate-p ">date</p></table-cell>
    <table-cell><p class="slate-p ">Scheduled recall date.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">reminder_date</code></p></table-cell>
    <table-cell><p class="slate-p ">date</p></table-cell>
    <table-cell><p class="slate-p ">Reminder sent / due date.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">reminder_type</code></p></table-cell>
    <table-cell><p class="slate-p ">string</p></table-cell>
    <table-cell><p class="slate-p ">Reminder method (SMS, Email, Letter).</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">reminder_no</code></p></table-cell>
    <table-cell><p class="slate-p ">integer</p></table-cell>
    <table-cell><p class="slate-p ">Reminder sequence number.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">practitioner_id</code></p></table-cell>
    <table-cell><p class="slate-p ">integer</p></table-cell>
    <table-cell><p class="slate-p ">Associated practitioner.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">location_id</code></p></table-cell>
    <table-cell><p class="slate-p ">integer</p></table-cell>
    <table-cell><p class="slate-p ">Associated location.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">created_date</code></p></table-cell>
    <table-cell><p class="slate-p ">datetime</p></table-cell>
    <table-cell><p class="slate-p ">Record creation timestamp.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">updated_date</code></p></table-cell>
    <table-cell><p class="slate-p ">datetime</p></table-cell>
    <table-cell><p class="slate-p ">Record last-modified timestamp.</p></table-cell>
  </table-row>
</Table>

Important notes
---------------

*   Required parameters: at least one filter parameter is required.
    
*   Date filtering: see [Filtering & Date Ranges](/filtering-and-date-ranges).
    
*   Default range: last 30 days plus the next 180 days (210 days total) when no `from_date` / `to_date` is supplied.
    
*   **No matches:** a filtered query that matches zero records returns 404, not an empty 200 result set.
    

Quick example
-------------

<CodeBlock attributes='{"isFitToPage":true,"style":{},"lang":"plainText","label":"Plain text"}'>
  <CodeLine>curl "https://api-uat.dental4web.com.au/api/v1/recalls?from_date=2026-01-01&amp;to_date=2026-06-09&amp;per_page=10" \</CodeLine>
  <CodeLine>    -H "x-api-key: $API_KEY" \</CodeLine>
  <CodeLine>    -H "org-id: $ORG_ID" \</CodeLine>
  <CodeLine>    -H "Accept: application/json" </CodeLine>
</CodeBlock>

GET Recalls

Returns all bookable slot types: `Vacant appointment time` plus configured preset types (for example “New patient appointments” or “eAppointments: Emergency”). Use these values to populate appointment-type pickers and to inform the slot mode when calling GET /api/v1/appointment-slots.

Response fields
---------------

<Table style="width:100%;min-width:100%" colSizes='["180px","135px","585px"]' isHeaderAdded='true' tableHeader='[{"id":"8636d6f2-9923-49bf-95dc-1b7143fa3295","title":"Field"},{"id":"2da95afa-bd8c-4c79-b819-d9fa206a3f63","title":"Type"},{"id":"eb51a599-ebaa-4b62-968d-9d507382b9a1","title":"Description"}]'>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">slot_type_id</code></p></table-cell>
    <table-cell><p class="slate-p ">integer</p></table-cell>
    <table-cell><p class="slate-p ">Slot-type identifier.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">slot_type</code></p></table-cell>
    <table-cell><p class="slate-p ">string</p></table-cell>
    <table-cell><p class="slate-p ">Slot-type name.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">is_preset</code></p></table-cell>
    <table-cell><p class="slate-p ">boolean</p></table-cell>
    <table-cell><p class="slate-p ">True if a preset slot type.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">is_online</code></p></table-cell>
    <table-cell><p class="slate-p ">integer</p></table-cell>
    <table-cell><p class="slate-p ">1 if available for online booking, 0 if not.</p></table-cell>
  </table-row>
</Table>

Quick example
-------------

<CodeBlock attributes='{"isFitToPage":true,"style":{},"lang":"plainText","label":"Plain text"}'>
  <CodeLine>curl "https://api-uat.dental4web.com.au/api/v1/slot-types?per_page=10" \</CodeLine>
  <CodeLine>    -H "x-api-key: $API_KEY" \</CodeLine>
  <CodeLine>    -H "org-id: $ORG_ID" \</CodeLine>
  <CodeLine>    -H "Accept: application/json" </CodeLine>
</CodeBlock>

GET Slot Types

Returns all available patient title options (Mr, Mrs, Dr, Miss, Master, Prof, Rev, and so on). Use `title_name` as the title value when calling POST /api/v1/patients and PATCH /api/v1/patients/{id}.

Response fields
---------------

<Table style="width:100%;min-width:100%" colSizes='["180px","135px","585px"]' isHeaderAdded='true' tableHeader='[{"id":"6dd8a4dc-a5b1-4368-a9f8-b2553f006680","title":"Field"},{"id":"6b9512f1-e0a2-438c-9e72-2fbcd54e5288","title":"Type"},{"id":"68aac717-4414-4085-91e5-3d32e2402a66","title":"Description"}]'>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">title_id</code></p></table-cell>
    <table-cell><p class="slate-p ">integer</p></table-cell>
    <table-cell><p class="slate-p ">Title identifier.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">title_name</code></p></table-cell>
    <table-cell><p class="slate-p ">string</p></table-cell>
    <table-cell><p class="slate-p ">Title text, e.g. Mr, Ms, Dr.</p></table-cell>
  </table-row>
</Table>

Quick example
-------------

<CodeBlock attributes='{"isFitToPage":true,"style":{},"lang":"plainText","label":"Plain text"}'>
  <CodeLine>curl "https://api-uat.dental4web.com.au/api/v1/titles?per_page=10" \</CodeLine>
  <CodeLine>    -H "x-api-key: $API_KEY" \</CodeLine>
  <CodeLine>    -H "org-id: $ORG_ID" \</CodeLine>
  <CodeLine>    -H "Accept: application/json" </CodeLine>
</CodeBlock>

GET Titles

Returns all system users: practitioners, hygienists, and administrative staff. Use `user_id` to interpret `created_user_id` and similar fields in write responses.

Use cases
---------

*   Audit user activity and permissions.
    
*   Track which user created or modified records.
    
*   Build user management interfaces.
    
*   Map `created_user_id` from other endpoints to user names.
    

Response fields
---------------

<Table style="width:100%;min-width:100%" colSizes='["180px","135px","585px"]' isHeaderAdded='true' tableHeader='[{"id":"d6f38042-8015-43c8-be32-844b5534ba5b","title":"Field"},{"id":"f85da7d5-50ff-40fd-b9e5-122e9c6ee5f1","title":"Type"},{"id":"76913336-f5b6-4fde-b00d-30edfc6e34c3","title":"Description"}]'>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">user_id</code></p></table-cell>
    <table-cell><p class="slate-p ">integer</p></table-cell>
    <table-cell><p class="slate-p ">Primary identifier.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">user_code</code></p></table-cell>
    <table-cell><p class="slate-p ">string</p></table-cell>
    <table-cell><p class="slate-p ">Short user code.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">first_name</code></p></table-cell>
    <table-cell><p class="slate-p ">string</p></table-cell>
    <table-cell><p class="slate-p ">Given name.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">surname</code></p></table-cell>
    <table-cell><p class="slate-p ">string</p></table-cell>
    <table-cell><p class="slate-p ">Family name.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">location_id</code></p></table-cell>
    <table-cell><p class="slate-p ">integer | null</p></table-cell>
    <table-cell><p class="slate-p ">Associated location (null for all locations).</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">is_active</code></p></table-cell>
    <table-cell><p class="slate-p ">boolean</p></table-cell>
    <table-cell><p class="slate-p ">Active status.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">user_type</code></p></table-cell>
    <table-cell><p class="slate-p ">string</p></table-cell>
    <table-cell><p class="slate-p ">User type.</p></table-cell>
  </table-row>
</Table>

Important notes
---------------

*   This endpoint supports only pagination and, where applicable, the `location_id` / `include` filters. There are no date or business filters.
    

Quick example
-------------

<CodeBlock attributes='{"isFitToPage":true,"style":{},"lang":"plainText","label":"Plain text"}'>
  <CodeLine>curl "https://api-uat.dental4web.com.au/api/v1/users?per_page=10" \</CodeLine>
  <CodeLine>    -H "x-api-key: $API_KEY" \</CodeLine>
  <CodeLine>    -H "org-id: $ORG_ID" \</CodeLine>
  <CodeLine>    -H "Accept: application/json" </CodeLine>
</CodeBlock>

GET Users

The Upload endpoints implement a zero-trust file upload flow: the API issues a short-lived, pre-signed upload target and the file is uploaded directly to storage, scanned for malware, and only made available once clean. File bytes never transit the Dental API itself. Online (cloud-hosted) orgs only.


Upload Resources

Initiates a zero-trust file upload session and returns a pre-signed upload target, valid for **15 minutes**. File bytes never transit the Dental API; this call only issues the upload target. Uploading the file itself, and checking on it, are covered by [GET Upload Status](/upload-resources/get-upload-status).

Use cases
---------

*   Attach a clinical document or image to a patient record.
    

Request body
------------

<Table style="width:100%;min-width:100%" colSizes='["180px","135px","585px"]' isHeaderAdded='true' tableHeader='[{"id":"b2c3d4e5-0011-4aaa-8011-000000000001","title":"Field"},{"id":"b2c3d4e5-0011-4aaa-8011-000000000002","title":"Type"},{"id":"b2c3d4e5-0011-4aaa-8011-000000000003","title":"Description"}]'>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">patient_id</code></p></table-cell>
    <table-cell><p class="slate-p ">integer</p></table-cell>
    <table-cell><p class="slate-p ">Required. 1-999999999.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">files</code></p></table-cell>
    <table-cell><p class="slate-p ">array</p></table-cell>
    <table-cell><p class="slate-p ">Required. One file object per upload. Currently capped at 1 file per request (enforced server-side).</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">files[].filename</code></p></table-cell>
    <table-cell><p class="slate-p ">string</p></table-cell>
    <table-cell><p class="slate-p ">Required. File name with extension, 1-255 characters.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">files[].content_type</code></p></table-cell>
    <table-cell><p class="slate-p ">string</p></table-cell>
    <table-cell><p class="slate-p ">Required. MIME type: one of <code class="slate-code">application/pdf</code>, <code class="slate-code">image/jpeg</code>, <code class="slate-code">image/png</code>, <code class="slate-code">image/tiff</code>, <code class="slate-code">text/csv</code>, <code class="slate-code">application/vnd.openxmlformats-officedocument.wordprocessingml.document</code> (DOCX), <code class="slate-code">application/vnd.openxmlformats-officedocument.spreadsheetml.sheet</code> (XLSX), or <code class="slate-code">application/dicom</code>.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">files[].size_bytes</code></p></table-cell>
    <table-cell><p class="slate-p ">integer</p></table-cell>
    <table-cell><p class="slate-p ">Required. File size in bytes, positive integer. Maximum 50 MB.</p></table-cell>
  </table-row>
</Table>

Response fields
---------------

<Table style="width:100%;min-width:100%" colSizes='["180px","135px","585px"]' isHeaderAdded='true' tableHeader='[{"id":"b2c3d4e5-0011-4bbb-8011-000000000001","title":"Field"},{"id":"b2c3d4e5-0011-4bbb-8011-000000000002","title":"Type"},{"id":"b2c3d4e5-0011-4bbb-8011-000000000003","title":"Description"}]'>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">upload_id</code></p></table-cell>
    <table-cell><p class="slate-p ">string</p></table-cell>
    <table-cell><p class="slate-p ">Upload session identifier. Pass this to <a href="/upload-resources/get-upload-status">GET Upload Status</a>.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">files</code></p></table-cell>
    <table-cell><p class="slate-p ">array</p></table-cell>
    <table-cell><p class="slate-p ">One entry per requested file.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">files[].file_id</code></p></table-cell>
    <table-cell><p class="slate-p ">string</p></table-cell>
    <table-cell><p class="slate-p ">File identifier within the upload session, distinct from <code class="slate-code">upload_id</code>.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">files[].filename</code></p></table-cell>
    <table-cell><p class="slate-p ">string</p></table-cell>
    <table-cell><p class="slate-p ">File name as submitted to Upload Initiate.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">files[].upload_method</code></p></table-cell>
    <table-cell><p class="slate-p ">string</p></table-cell>
    <table-cell><p class="slate-p ">HTTP method for the upload request. Currently always <code class="slate-code">POST</code>.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">files[].upload_url</code></p></table-cell>
    <table-cell><p class="slate-p ">string</p></table-cell>
    <table-cell><p class="slate-p ">Pre-signed upload target URL.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">files[].upload_fields</code></p></table-cell>
    <table-cell><p class="slate-p ">object</p></table-cell>
    <table-cell><p class="slate-p ">Form fields for the pre-signed upload target.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">files[].expires_in</code></p></table-cell>
    <table-cell><p class="slate-p ">integer</p></table-cell>
    <table-cell><p class="slate-p ">Seconds until the upload target expires (matches the 15-minute session validity above).</p></table-cell>
  </table-row>
</Table>

Once the file has been uploaded, poll [GET Upload Status](/upload-resources/get-upload-status) with the returned `upload_id`; see Important notes below for the polling cadence.

Error responses
---------------

<Table style="width:100%;min-width:100%" colSizes='["180px","135px","585px"]' isHeaderAdded='true' tableHeader='[{"id":"b2c3d4e5-0011-4ccc-8011-000000000001","title":"Status"},{"id":"b2c3d4e5-0011-4ccc-8011-000000000002","title":"support_code"},{"id":"b2c3d4e5-0011-4ccc-8011-000000000003","title":"Meaning"}]'>
  <table-row>
    <table-cell><p class="slate-p ">400</p></table-cell>
    <table-cell><p class="slate-p "><code class="slate-code">UPL-4000</code></p></table-cell>
    <table-cell><p class="slate-p ">Uploads are only available to cloud-hosted (online) orgs. On-premise orgs receive a 400.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p ">400</p></table-cell>
    <table-cell><p class="slate-p "><code class="slate-code">UPL-4000</code></p></table-cell>
    <table-cell><p class="slate-p ">Business-rule validation failure: file size over 50 MB, more than 1 file per request, a blocked or double file extension, or a <code class="slate-code">content_type</code> not in the allowed list. Confirmed live for all four; returned immediately at Upload Initiate, not deferred to upload processing.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p ">400</p></table-cell>
    <table-cell><p class="slate-p "><code class="slate-code">UPL-4000</code></p></table-cell>
    <table-cell><p class="slate-p ">The <code class="slate-code">patient_id</code> does not exist in this organisation. The message is <code class="slate-code">Patient not found in this organisation</code>. Confirmed live. This rejection does not count towards the rate limit below.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p ">422</p></table-cell>
    <table-cell><p class="slate-p ">(none)</p></table-cell>
    <table-cell><p class="slate-p ">Required field missing or wrong type (schema validation), including a numeric value outside its schema-level range (for example <code class="slate-code">patient_id</code> below 1 or above 999999999, or a non-positive <code class="slate-code">size_bytes</code>). Confirmed live: these return 422 with no <code class="slate-code">support_code</code>. Only the file-size business rule (over 50 MB) returns 400 with <code class="slate-code">UPL-4000</code>; see that row above.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p ">429</p></table-cell>
    <table-cell><p class="slate-p "><code class="slate-code">UPL-4000</code></p></table-cell>
    <table-cell><p class="slate-p ">Rate limit exceeded. The message is <code class="slate-code">Upload rate limit exceeded: maximum 50 files per hour per organisation</code>. The limit is 50 files per Sydney clock hour, per organisation, shared by all integrators on the practice. It counts every started upload, including one rejected for its file name or type, but not a patient not found. The count resets at the top of each hour, so wait until the next hour before retrying.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p ">503</p></table-cell>
    <table-cell><p class="slate-p ">(none)</p></table-cell>
    <table-cell><p class="slate-p ">Upload service temporarily unavailable. The response has a generic message, no <code class="slate-code">support_code</code> and no <code class="slate-code">Retry-After</code> header. Safe to retry after a short delay.</p></table-cell>
  </table-row>
</Table>

Important notes
---------------

*   **Limits:** maximum file size 50 MB, maximum 1 file per request. Confirmed live: both are enforced immediately at this call, as a 400 with `support_code: UPL-4000`, not deferred to upload processing.
    
*   **Blocked extensions:** `.exe .bat .cmd .com .msi .scr .pif .vbs .vbe .js .jse .wsf .wsh .ps1 .sh .csh .ksh .dll .sys .drv`. The check is case insensitive. Confirmed live: all seven of `.vbe .jse .wsf .wsh .csh .ksh .drv` are rejected with `UPL-4000`.
    
*   **Double extensions:** a file name is rejected when a blocked extension is followed by another dot, for example `scan.exe.pdf` or `notes.js.pdf`. This also catches `.com`, so `acme.com.invoice.pdf` is rejected even though it is a harmless name. Other dots are fine: `report.v2.final.pdf` and `xray.2026.03.01.pdf` are accepted. The final extension must also match the declared `content_type`.
    
*   **Malware scanning:** every uploaded file is scanned before it becomes available; a file that fails the scan is quarantined rather than promoted. See [GET Upload Status](/upload-resources/get-upload-status) for the per-file status values.
    
*   **Online orgs only:** this endpoint is not available to on-premise orgs (400 with `UPL-4000`). Online practices must be on data model V13 or later.
    
*   **Stored file name:** the stored name is your file name with every character other than a letter, digit, hyphen, underscore or dot replaced by an underscore, followed by a Sydney time stamp in the form ` [dd-mm-yyyy hh.mm.ss]` before the extension, for example `clean [12-10-2026 16.15.53].csv`. Only the file name can be set.
    
*   Once the file has been uploaded, poll [GET Upload Status](/upload-resources/get-upload-status) every 5 seconds for the first minute, then every 30 seconds, until the session `status` is `completed`, `rejected` or `error`. These are the three terminal states. A session that ends in `error` is not retried automatically; start a new upload with this endpoint. Status is kept for 30 days; see [GET Upload Status](/upload-resources/get-upload-status) for the retention rules.
    

Quick example
-------------

<CodeBlock attributes='{"isFitToPage":true,"style":{},"lang":"plainText","label":"Plain text"}'>
  <CodeLine>curl -X POST "https://api-uat.dental4web.com.au/api/v1/uploads/initiate" \</CodeLine>
  <CodeLine>    -H "x-api-key: $API_KEY" \</CodeLine>
  <CodeLine>    -H "org-id: $ORG_ID" \</CodeLine>
  <CodeLine>    -H "Content-Type: application/json" \</CodeLine>
  <CodeLine>    -H "Accept: application/json" \</CodeLine>
  <CodeLine>    -d '{"patient_id":744,"files":[{"filename":"xray-2026-03-01.pdf","content_type":"application/pdf","size_bytes":482013}]}' </CodeLine>
</CodeBlock>


POST Upload Initiate

Returns the current status of an upload session, including per-file malware-scan status. Poll this after uploading a file to the URL returned by [POST Upload Initiate](/upload-resources/post-upload-initiate).

Use cases
---------

*   Confirm a file has cleared malware scanning before referencing it elsewhere.
    
*   Build a progress indicator for an in-flight upload.
    

Parameters
----------

<Table style="width:100%;min-width:100%" colSizes='["180px","135px","585px"]' isHeaderAdded='true' tableHeader='[{"id":"b2c3d4e5-0012-4aaa-8012-000000000001","title":"Parameter"},{"id":"b2c3d4e5-0012-4aaa-8012-000000000002","title":"Type"},{"id":"b2c3d4e5-0012-4aaa-8012-000000000003","title":"Description"}]'>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">upload_id</code></p></table-cell>
    <table-cell><p class="slate-p ">string</p></table-cell>
    <table-cell><p class="slate-p ">Path parameter. Required. The upload session identifier returned by <a href="/upload-resources/post-upload-initiate">POST Upload Initiate</a>.</p></table-cell>
  </table-row>
</Table>

Response fields
---------------

<Table style="width:100%;min-width:100%" colSizes='["180px","135px","585px"]' isHeaderAdded='true' tableHeader='[{"id":"b2c3d4e5-0012-4bbb-8012-000000000001","title":"Field"},{"id":"b2c3d4e5-0012-4bbb-8012-000000000002","title":"Type"},{"id":"b2c3d4e5-0012-4bbb-8012-000000000003","title":"Description"}]'>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">upload_id</code></p></table-cell>
    <table-cell><p class="slate-p ">string</p></table-cell>
    <table-cell><p class="slate-p ">Upload session identifier.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">status</code></p></table-cell>
    <table-cell><p class="slate-p ">string</p></table-cell>
    <table-cell><p class="slate-p ">Overall session status. In progress: <code class="slate-code">awaiting_upload</code> (the file has not been received yet) and <code class="slate-code">processing</code>. Terminal: <code class="slate-code">completed</code>, <code class="slate-code">rejected</code> (the file failed the malware scan or a content check) and <code class="slate-code">error</code> (the scan could not be completed).</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">files</code></p></table-cell>
    <table-cell><p class="slate-p ">array</p></table-cell>
    <table-cell><p class="slate-p ">One entry per file in the session.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">files[].file_id</code></p></table-cell>
    <table-cell><p class="slate-p ">string</p></table-cell>
    <table-cell><p class="slate-p ">File identifier within the upload session, matching the <code class="slate-code">file_id</code> returned by <a href="/upload-resources/post-upload-initiate">POST Upload Initiate</a>.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">files[].filename</code></p></table-cell>
    <table-cell><p class="slate-p ">string</p></table-cell>
    <table-cell><p class="slate-p ">File name as submitted to Upload Initiate.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">files[].status</code></p></table-cell>
    <table-cell><p class="slate-p ">string</p></table-cell>
    <table-cell><p class="slate-p ">Per-file processing status. In progress: <code class="slate-code">pending_upload</code> (not uploaded yet), <code class="slate-code">pending_scan</code> and <code class="slate-code">scanning</code>. Final: <code class="slate-code">completed</code> (clean), <code class="slate-code">quarantined</code> (malware detected; this value is used for malware only), <code class="slate-code">integrity_failed</code> (a content check failed: the file does not match its declared type, or it has unusually high entropy) and <code class="slate-code">scan_failed</code> (the scan did not complete). All of these values have been confirmed live. See the Outcomes note below for how the file, scan and session values line up.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">files[].scan_result</code></p></table-cell>
    <table-cell><p class="slate-p ">string</p></table-cell>
    <table-cell><p class="slate-p ">Malware-scan verdict: <code class="slate-code">none</code> before the file has been scanned, <code class="slate-code">no_threats_found</code> for a clean file, <code class="slate-code">threat_detected</code> when malware is found, <code class="slate-code">integrity_failed</code> for high entropy, and <code class="slate-code">error</code> when the file does not match its declared type or the scan could not be completed. Use the file <code class="slate-code">status</code> to decide what happened, not <code class="slate-code">scan_result</code>. The name of a detected threat is never returned. It can read <code class="slate-code">error</code> while the file <code class="slate-code">status</code> is <code class="slate-code">scanning</code> (observed live for 2 to 3 seconds). All of these values have been confirmed live.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">files[].production_key</code></p></table-cell>
    <table-cell><p class="slate-p ">string | null</p></table-cell>
    <table-cell><p class="slate-p ">Storage key for the scanned file. The key is absent from the response entirely (not present as <code class="slate-code">null</code>) unless the file <code class="slate-code">status</code> is <code class="slate-code">completed</code>.</p></table-cell>
  </table-row>
</Table>

Important notes
---------------

*   **404 on organisation mismatch:** a valid `upload_id` belonging to a different org returns 404, the same as a genuinely unknown `upload_id`. This is deliberate: an organisation mismatch and a not-found are indistinguishable by design, to avoid leaking whether an ID exists.
    
*   **On-premise orgs:** this endpoint returns 400 with the message `File uploads are only available for online organisations` and `support_code` `UPL-4000`.
    
*   **Polling guidance:** every 5 seconds for the first minute, then every 30 seconds, until `status` is `completed`, `rejected` or `error`. These are the three terminal states. There is no webhook and no batch status call, so poll each upload separately. Each upload carries one file.
    
*   **Outcomes:** a clean file ends as file `completed`, `scan_result` `no_threats_found`, session `completed`. Malware ends as `quarantined`, `threat_detected`, session `rejected`. A file that does not match its declared type ends as `integrity_failed`, `error`, session `rejected`. A file with unusually high entropy ends as `integrity_failed`, `integrity_failed`, session `rejected`. A scan that could not be completed ends as `scan_failed`, `error`, session `error`. `scan_result` can read `error` while the file `status` is `scanning` (observed live for 2 to 3 seconds), so use `status` for decisions.
    
*   **Scan time:** a clean file normally finishes in a few seconds (2 to 5 seconds in UAT). This is an observation, not a guaranteed time.
    
*   **Errors are not retried:** an upload in `error` is not retried automatically. Start a new upload with [POST Upload Initiate](/upload-resources/post-upload-initiate). A scan that has not finished after about 15 minutes is marked `error`. If a file has not reached a final state about 20 minutes after it was uploaded, treat it as failed and start a new upload.
    
*   **Status retention:** upload status is available for 30 days. After that the call returns 400 with the message `Upload session has expired`. The upload URL itself is valid for 15 minutes. If the file is never sent, the session stays `awaiting_upload` and the file stays `pending_upload` until the 30 days end; it does not move to a failed state. This was observed unchanged after 5 minutes.
    

Quick example
-------------

<CodeBlock attributes='{"isFitToPage":true,"style":{},"lang":"plainText","label":"Plain text"}'>
  <CodeLine>curl "https://api-uat.dental4web.com.au/api/v1/uploads/a3f5c9e2-8b1d-4e6a-9c3f-1d2e3f4a5b6c" \</CodeLine>
  <CodeLine>    -H "x-api-key: $API_KEY" \</CodeLine>
  <CodeLine>    -H "org-id: $ORG_ID" \</CodeLine>
  <CodeLine>    -H "Accept: application/json" </CodeLine>
</CodeBlock>


GET Upload Status

The Admin endpoints return read-only, organisation-level metadata about the connected practice management system: whether it is cloud-hosted or on-premise, and which data-model version it is running. Useful for integrators that need to branch behaviour by deployment type or schema version. Both endpoints resolve the org from your API credentials; no parameters required.


Admin Resources

Returns whether the calling org's practice management system is cloud-hosted or on-premise.

Use cases
---------

*   Branch integration behaviour by deployment type: some endpoints (Upload Resources, for example) are online-orgs-only.
    
*   Surface deployment context in a support or diagnostics tool.
    

No query parameters. Requires the `org-id` header (see Authentication); the org is resolved from that header, not from the API key alone.

Response fields
---------------

<Table style="width:100%;min-width:100%" colSizes='["180px","135px","585px"]' isHeaderAdded='true' tableHeader='[{"id":"b2c3d4e5-0013-4aaa-8013-000000000001","title":"Field"},{"id":"b2c3d4e5-0013-4aaa-8013-000000000002","title":"Type"},{"id":"b2c3d4e5-0013-4aaa-8013-000000000003","title":"Description"}]'>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">org_id</code></p></table-cell>
    <table-cell><p class="slate-p ">string</p></table-cell>
    <table-cell><p class="slate-p ">The calling org's identifier.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">deployment_type</code></p></table-cell>
    <table-cell><p class="slate-p ">string</p></table-cell>
    <table-cell><p class="slate-p ">Either <code class="slate-code">Cloud Hosted</code> or <code class="slate-code">On Premise</code>.</p></table-cell>
  </table-row>
</Table>

Important notes
---------------

*   **Timeouts and upstream errors are retryable:** a slow or unreachable admin service returns 504 or 502 respectively, both safe to retry.
    

Quick example
-------------

<CodeBlock attributes='{"isFitToPage":true,"style":{},"lang":"plainText","label":"Plain text"}'>
  <CodeLine>curl "https://api-uat.dental4web.com.au/api/v1/admin/deployment-type" \</CodeLine>
  <CodeLine>    -H "x-api-key: $API_KEY" \</CodeLine>
  <CodeLine>    -H "org-id: $ORG_ID" \</CodeLine>
  <CodeLine>    -H "Accept: application/json" </CodeLine>
</CodeBlock>


GET Deployment Type

Returns the data-model version (for example `V18`) the calling org is currently running.

Use cases
---------

*   Gate use of newer fields or endpoints (such as `patients_lite`, introduced in V18) on the org's actual data-model version rather than assuming every org is current.
    
*   Surface data-model context in a support or diagnostics tool.
    

No query parameters. Requires the `org-id` header (see Authentication); the org is resolved from that header, not from the API key alone.

Response fields
---------------

<Table style="width:100%;min-width:100%" colSizes='["180px","135px","585px"]' isHeaderAdded='true' tableHeader='[{"id":"b2c3d4e5-0014-4aaa-8014-000000000001","title":"Field"},{"id":"b2c3d4e5-0014-4aaa-8014-000000000002","title":"Type"},{"id":"b2c3d4e5-0014-4aaa-8014-000000000003","title":"Description"}]'>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">org_id</code></p></table-cell>
    <table-cell><p class="slate-p ">string</p></table-cell>
    <table-cell><p class="slate-p ">The calling org's identifier.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">data_model_version</code></p></table-cell>
    <table-cell><p class="slate-p ">string</p></table-cell>
    <table-cell><p class="slate-p ">The org's current data-model version, e.g. <code class="slate-code">V18</code>.</p></table-cell>
  </table-row>
</Table>

Important notes
---------------

*   **On-premise data-model lag:** on-premise organisations may, from time to time, lag behind the latest data model depending on their local database build. Use this endpoint to check an org's current `data_model_version` before relying on newer fields or endpoints, and contact us if an org's data model needs to be updated.
    
*   **Timeouts are retryable:** a slow admin service returns 504.
    
*   **Transient failures return 503, not 502:** a transient probe failure is surfaced as 503 with a `Retry-After: 30` header rather than passed through as a raw 502. Safe to retry after the indicated delay.
    

Quick example
-------------

<CodeBlock attributes='{"isFitToPage":true,"style":{},"lang":"plainText","label":"Plain text"}'>
  <CodeLine>curl "https://api-uat.dental4web.com.au/api/v1/admin/data-model-version" \</CodeLine>
  <CodeLine>    -H "x-api-key: $API_KEY" \</CodeLine>
  <CodeLine>    -H "org-id: $ORG_ID" \</CodeLine>
  <CodeLine>    -H "Accept: application/json" </CodeLine>
</CodeBlock>


GET Data Model Version

MediaWeb PACS endpoints provide access to Dental4Web’s digital imaging platform. You use them to search, retrieve, and bulk-download dental images in DICOM format or converted to JPEG.

Key features
------------

*   DICOM native storage: all images are stored in DICOM format for diagnostic quality.
    
*   Optional JPEG conversion: request JPEG format for viewing and display use cases (quality level 98).
    
*   Pre-signed URLs: secure, time-limited download links that need no additional authentication.
    
*   Bulk retrieval: download all images for a patient in a single request.
    

Image format recommendations
----------------------------

*   Use DICOM format for diagnostic purposes and archival.
    
*   Use JPEG for display in non-diagnostic applications and patient portals.
    
*   If JPEG conversion fails to meet quality thresholds, the original DICOM is returned.
    

Pre-signed URL expiry
---------------------

<Table style="width:100%;min-width:100%" colSizes='["270px","630px"]' isHeaderAdded='true' tableHeader='[{"id":"5c324e78-2391-4bc4-b09d-14a171d0c172","title":"Operation"},{"id":"e144da20-c6cd-4dfd-bbf3-d644295b5cb4","title":"Expiry time"}]'>
  <table-row>
    <table-cell><p class="slate-p ">Single image (<code class="slate-code">GET /mwp/images/{image_id}</code>)</p></table-cell>
    <table-cell><p class="slate-p ">5 minutes</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p ">Bulk patient images (<code class="slate-code">GET /mwp/images/patient/{patient_id}</code>)</p></table-cell>
    <table-cell><p class="slate-p ">10 minutes</p></table-cell>
  </table-row>
</Table>

### URL lifetimes

Pre-signed download URLs use a tiered expiry policy that depends on the operation that issued them. Each URL stops working once its lifetime elapses; request a fresh one by calling the originating endpoint again.

*   Single image (`GET /mwp/images/{image_id}`): the pre-signed URL expires after 5 minutes (300 seconds).
    
*   Bulk patient images (`GET /mwp/images/patient/{patient_id}`): each pre-signed URL expires after 10 minutes (600 seconds).
    

The exact lifetime for each URL is also returned in the response. Single-image responses include an `expires_in` field reporting the value in seconds.

For the canonical list of error codes, see [Validation, Limits & Character Handling](/validation-limits-and-character-handling).

MediaWeb PACS Resources

Searches for dental images stored in MediaWeb PACS and returns image metadata without the image data itself. You use the returned `image_id` to retrieve an individual image, or fetch every image for a patient with the bulk endpoint.

Use cases
---------

*   Search for images by patient, study, or modality.
    
*   Build an image gallery interface that shows the available studies.
    
*   Identify images to download or display.
    

Parameters
----------

<Table style="width:100%;min-width:100%" colSizes='["180px","135px","585px"]' isHeaderAdded='true' tableHeader='[{"id":"b1b2c3d4-0003-4bbb-8003-000000000001","title":"Parameter"},{"id":"b1b2c3d4-0003-4bbb-8003-000000000002","title":"Type"},{"id":"b1b2c3d4-0003-4bbb-8003-000000000003","title":"Description"}]'>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">patient_id</code></p></table-cell>
    <table-cell><p class="slate-p ">integer</p></table-cell>
    <table-cell><p class="slate-p ">Filter by patient.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">start_date</code></p></table-cell>
    <table-cell><p class="slate-p ">date</p></table-cell>
    <table-cell><p class="slate-p ">Required. Start of the date range. See <code class="slate-code">mode</code> below for which date this filters on.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">end_date</code></p></table-cell>
    <table-cell><p class="slate-p ">date</p></table-cell>
    <table-cell><p class="slate-p ">Required. End of the date range. Confirmed live: omitting either <code class="slate-code">start_date</code> or <code class="slate-code">end_date</code> returns <code class="slate-code">400</code> (<code class="slate-code">support_code: MWP_DATE_RANGE_REQUIRED</code>); there is no default range.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">modality</code></p></table-cell>
    <table-cell><p class="slate-p ">string</p></table-cell>
    <table-cell><p class="slate-p ">Filter by imaging modality (IO, PX, CT, CR, etc.), 1-50 characters. Confirmed live as an accepted filter.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">mode</code></p></table-cell>
    <table-cell><p class="slate-p ">integer</p></table-cell>
    <table-cell><p class="slate-p "><code class="slate-code">0</code> (default) filters by <code class="slate-code">study_date</code>; <code class="slate-code">1</code> filters by the image's last-modified timestamp.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">per_page</code></p></table-cell>
    <table-cell><p class="slate-p ">integer</p></table-cell>
    <table-cell><p class="slate-p ">Results per page: see <a href="/api-response-formats">API response formats</a>.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">page</code></p></table-cell>
    <table-cell><p class="slate-p ">integer</p></table-cell>
    <table-cell><p class="slate-p ">Page number.</p></table-cell>
  </table-row>
</Table>

Response fields
---------------

<Table style="width:100%;min-width:100%" colSizes='["180px","135px","585px"]' isHeaderAdded='true' tableHeader='[{"id":"066e26c0-adc5-4318-b7d6-65b9bb4a75ff","title":"Field"},{"id":"96ee6ee3-a701-4e4e-be14-9d1b3a6d5f10","title":"Type"},{"id":"89590686-576f-4d6c-a250-cfa0614e6ea8","title":"Description"}]'>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">image_id</code></p></table-cell>
    <table-cell><p class="slate-p ">string</p></table-cell>
    <table-cell><p class="slate-p ">DICOM SOP Instance UID.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">patient_id</code></p></table-cell>
    <table-cell><p class="slate-p ">integer</p></table-cell>
    <table-cell><p class="slate-p ">Patient identifier.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">patient_card</code></p></table-cell>
    <table-cell><p class="slate-p ">string</p></table-cell>
    <table-cell><p class="slate-p ">Patient card number.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">study_id</code></p></table-cell>
    <table-cell><p class="slate-p ">integer</p></table-cell>
    <table-cell><p class="slate-p ">Study identifier.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">study_date</code></p></table-cell>
    <table-cell><p class="slate-p ">date</p></table-cell>
    <table-cell><p class="slate-p ">Date of the imaging study.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">modality</code></p></table-cell>
    <table-cell><p class="slate-p ">string</p></table-cell>
    <table-cell><p class="slate-p ">Imaging modality (IO, PX, CT, CR, etc.).</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">series_id</code></p></table-cell>
    <table-cell><p class="slate-p ">integer</p></table-cell>
    <table-cell><p class="slate-p ">Series identifier.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">updated_at</code></p></table-cell>
    <table-cell><p class="slate-p ">datetime</p></table-cell>
    <table-cell><p class="slate-p ">Record last-modified timestamp. Populated automatically whenever the imaging time-filter feature is enabled for the environment and the organisation's database has the <code class="slate-code">updated_at</code> column, independent of whether <code class="slate-code">mode</code> is passed. <code class="slate-code">metadata.updated_at_available</code> reports this per response.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">metadata</code></p></table-cell>
    <table-cell><p class="slate-p ">object</p></table-cell>
    <table-cell><p class="slate-p ">Response envelope metadata, including <code class="slate-code">updated_at_available</code>. See <a href="/api-response-formats">API response formats</a> for the full field list.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">pagination</code></p></table-cell>
    <table-cell><p class="slate-p ">object</p></table-cell>
    <table-cell><p class="slate-p ">Pagination for the result set. See <a href="/api-response-formats">API response formats</a> for the full field list.</p></table-cell>
  </table-row>
</Table>

Important notes
---------------

*   MWP-enabled only: available only for organisations with MediaWeb PACS integration.
    
*   Metadata only: returns image references, not the image data itself.
    
*   Both dates required: `start_date` and `end_date` must both be supplied. Confirmed live: omitting either returns `400` with `support_code: MWP_DATE_RANGE_REQUIRED`. There is no default date range.
    
*   Last-modified metadata: `updated_at` is populated automatically whenever the imaging time-filter feature is enabled for the environment and the organisation's database has the `updated_at` column, independent of whether `mode` is passed. The response's top-level `metadata.updated_at_available` boolean indicates whether last-modified data is available for the result set.
    

Quick example
-------------

<CodeBlock attributes='{"isFitToPage":true,"style":{},"lang":"plainText","label":"Plain text"}'>
  <CodeLine>curl "https://api-uat.dental4web.com.au/api/v1/mwp/images?patient_id=10016&amp;per_page=10&amp;start_date=2024-01-01&amp;end_date=2025-12-31" \</CodeLine>
  <CodeLine>    -H "x-api-key: $API_KEY" \</CodeLine>
  <CodeLine>    -H "org-id: $ORG_ID" \</CodeLine>
  <CodeLine>    -H "Accept: application/json" </CodeLine>
</CodeBlock>

GET Image Search

Retrieves a single image record with a short-lived, pre-signed download URL.

Parameters
----------

<Table style="width:100%;min-width:100%" colSizes='["180px","135px","585px"]' isHeaderAdded='true' tableHeader='[{"id":"8f710ec8-a988-4eb1-8399-937600418b45","title":"Field"},{"id":"578d642b-01e2-499c-8ae1-0956b8f6dd64","title":"Type"},{"id":"8f0e7cb5-1238-4247-b86b-1d7cc6376188","title":"Description"}]'>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">image_id</code></p></table-cell>
    <table-cell><p class="slate-p ">string</p></table-cell>
    <table-cell><p class="slate-p ">Path parameter. DICOM SOP Instance UID. Use the <code class="slate-code">image_id</code> value from <code class="slate-code">GET /api/v1/mwp/images</code> (search) or <code class="slate-code">GET /api/v1/mwp/images/patient/{patient_id}</code> (bulk).</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">jpeg</code></p></table-cell>
    <table-cell><p class="slate-p ">boolean</p></table-cell>
    <table-cell><p class="slate-p ">Query parameter. Pass <code class="slate-code">true</code> to receive a JPEG conversion (quality ~98). If conversion fails, the response falls back to DICOM, and the <code class="slate-code">format</code> field reports which format was returned.</p></table-cell>
  </table-row>
</Table>

Use cases
---------

*   Download specific images for diagnostic viewing.
    
*   Display images in patient portals or clinical applications.
    
*   Archive images to external storage systems.
    

Response fields
---------------

<Table style="width:100%;min-width:100%" colSizes='["180px","135px","585px"]' isHeaderAdded='true' tableHeader='[{"id":"4d045901-1962-4e3e-9b87-ad3d39a0bcf2","title":"Field"},{"id":"2126ec73-e393-48f6-8af8-51bd24cfa125","title":"Type"},{"id":"226fee9a-2dce-400e-bfbe-c6881da55c81","title":"Description"}]'>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">image_id</code></p></table-cell>
    <table-cell><p class="slate-p ">string</p></table-cell>
    <table-cell><p class="slate-p ">DICOM SOP Instance UID.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">patient_id</code></p></table-cell>
    <table-cell><p class="slate-p ">integer</p></table-cell>
    <table-cell><p class="slate-p ">Patient identifier.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">patient_card</code></p></table-cell>
    <table-cell><p class="slate-p ">string</p></table-cell>
    <table-cell><p class="slate-p ">Patient card number.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">study_id</code></p></table-cell>
    <table-cell><p class="slate-p ">integer</p></table-cell>
    <table-cell><p class="slate-p ">Study identifier.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">study_date</code></p></table-cell>
    <table-cell><p class="slate-p ">date</p></table-cell>
    <table-cell><p class="slate-p ">Date of the imaging study.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">series_id</code></p></table-cell>
    <table-cell><p class="slate-p ">integer</p></table-cell>
    <table-cell><p class="slate-p ">Series identifier.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">format</code></p></table-cell>
    <table-cell><p class="slate-p ">string</p></table-cell>
    <table-cell><p class="slate-p ">Format actually returned: <code class="slate-code">dicom</code> or <code class="slate-code">jpeg</code>.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">url</code></p></table-cell>
    <table-cell><p class="slate-p ">string</p></table-cell>
    <table-cell><p class="slate-p ">Pre-signed download URL.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">expires_in</code></p></table-cell>
    <table-cell><p class="slate-p ">integer</p></table-cell>
    <table-cell><p class="slate-p ">URL validity in seconds (300 for a single image).</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">metadata</code></p></table-cell>
    <table-cell><p class="slate-p ">object</p></table-cell>
    <table-cell><p class="slate-p ">Response envelope metadata, including <code class="slate-code">updated_at_available</code>. See <a href="/api-response-formats">API response formats</a> for the full field list.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">pagination</code></p></table-cell>
    <table-cell><p class="slate-p ">object</p></table-cell>
    <table-cell><p class="slate-p ">Pagination for the result set. See <a href="/api-response-formats">API response formats</a> for the full field list.</p></table-cell>
  </table-row>
</Table>

Important notes
---------------

*   URL expiry: the pre-signed URL expires after 5 minutes (300 seconds).
    
*   Format parameter: pass `jpeg=true` to receive a JPEG conversion. When omitted, the image is returned in DICOM format. The response `format` field reports the format actually returned.
    
*   JPEG quality: JPEG conversion uses quality level 98.
    

Quick example
-------------

<CodeBlock attributes='{"isFitToPage":true,"style":{},"lang":"plainText","label":"Plain text"}'>
  <CodeLine>curl "https://api-uat.dental4web.com.au/api/v1/mwp/images/1.2.36.18057620390.9700831451752.3?jpeg=true" \</CodeLine>
  <CodeLine>    -H "x-api-key: $API_KEY" \</CodeLine>
  <CodeLine>    -H "org-id: $ORG_ID" \</CodeLine>
  <CodeLine>    -H "Accept: application/json" </CodeLine>
</CodeBlock>

GET Single Image

Retrieves all images for a patient, each with a pre-signed download URL. This is more efficient than fetching images individually when you need several at once.

Use cases
---------

*   Download all patient images for backup or migration.
    
*   Display a complete patient imaging history.
    
*   Build patient image galleries.
    

Response fields
---------------

<Table style="width:100%;min-width:100%" colSizes='["180px","135px","585px"]' isHeaderAdded='true' tableHeader='[{"id":"0bb9263c-a008-4e74-a64d-eacbd6c9269c","title":"Field"},{"id":"a73912e0-8e23-4077-85ec-22395dc0c2b7","title":"Type"},{"id":"7bfa8ad2-1743-45f1-9b05-936acf239930","title":"Description"}]'>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">image_id</code></p></table-cell>
    <table-cell><p class="slate-p ">string</p></table-cell>
    <table-cell><p class="slate-p ">DICOM SOP Instance UID.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">patient_id</code></p></table-cell>
    <table-cell><p class="slate-p ">integer</p></table-cell>
    <table-cell><p class="slate-p ">Patient identifier.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">patient_card</code></p></table-cell>
    <table-cell><p class="slate-p ">string</p></table-cell>
    <table-cell><p class="slate-p ">Patient card number.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">study_id</code></p></table-cell>
    <table-cell><p class="slate-p ">integer</p></table-cell>
    <table-cell><p class="slate-p ">Study identifier.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">study_date</code></p></table-cell>
    <table-cell><p class="slate-p ">date</p></table-cell>
    <table-cell><p class="slate-p ">Date of the imaging study.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">modality</code></p></table-cell>
    <table-cell><p class="slate-p ">string</p></table-cell>
    <table-cell><p class="slate-p ">Imaging modality.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">series_id</code></p></table-cell>
    <table-cell><p class="slate-p ">integer</p></table-cell>
    <table-cell><p class="slate-p ">Series identifier.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">format</code></p></table-cell>
    <table-cell><p class="slate-p ">string</p></table-cell>
    <table-cell><p class="slate-p ">Format actually returned: <code class="slate-code">dicom</code> or <code class="slate-code">jpeg</code>.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">url</code></p></table-cell>
    <table-cell><p class="slate-p ">string</p></table-cell>
    <table-cell><p class="slate-p ">Pre-signed download URL (valid for 600 seconds).</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">metadata</code></p></table-cell>
    <table-cell><p class="slate-p ">object</p></table-cell>
    <table-cell><p class="slate-p ">Response envelope metadata, including <code class="slate-code">updated_at_available</code>. See <a href="/api-response-formats">API response formats</a> for the full field list.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">pagination</code></p></table-cell>
    <table-cell><p class="slate-p ">object</p></table-cell>
    <table-cell><p class="slate-p ">Pagination for the result set. See <a href="/api-response-formats">API response formats</a> for the full field list.</p></table-cell>
  </table-row>
</Table>

Important notes
---------------

*   URL expiry: the pre-signed URLs expire after 10 minutes (600 seconds).
    
*   **No pagination:** this endpoint does not accept `page` or `per_page` query parameters. Confirmed live: passing either returns 400 ("Unexpected parameters"); all matching images for the patient are returned in a single response.
    
*   Format parameter: pass `jpeg=true` to receive JPEG conversions. When omitted, images are returned in DICOM format. The response `format` field reports the format actually returned.
    

Quick example
-------------

<CodeBlock attributes='{"isFitToPage":true,"style":{},"lang":"plainText","label":"Plain text"}'>
  <CodeLine>curl "https://api-uat.dental4web.com.au/api/v1/mwp/images/patient/10016" \</CodeLine>
  <CodeLine>    -H "x-api-key: $API_KEY" \</CodeLine>
  <CodeLine>    -H "org-id: $ORG_ID" \</CodeLine>
  <CodeLine>    -H "Accept: application/json" </CodeLine>
</CodeBlock>

GET Patient Images (Bulk)

This section documents all FHIR R4-compliant endpoints. These endpoints return data in standard FHIR Bundle format for healthcare interoperability.

**For detailed FHIR documentation, see the** [**FHIR Capabilities page**](/fhir-capabilities)**.**

All FHIR endpoints:

*   Return data wrapped in a FHIR Bundle with `resourceType: "Bundle"`
    
*   Include inline references to related resources (Patient, Practitioner, Location)
    
*   Follow FHIR R4 specification naming conventions
    
*   Accept the same query parameters as their standard counterparts

FHIR Resources

Retrieves completed treatments as FHIR R4 `Procedure` resources. Each `Procedure` carries the item code, performed date, treating practitioner, location, fee, and quantity. The bundle also includes the referenced `Practitioner` and `Location` resources. Parameters and constraints match [Get treatments](/treatment-and-clinical-resources/get-treatments).

Resource mapping
----------------

How each source treatment field maps onto the FHIR `Procedure` resource.

<Table style="width:100%;min-width:100%" colSizes='["180px","135px","585px"]' isHeaderAdded='true' tableHeader='[{"id":"15f25e78-3d32-4f6a-8512-ae2d777e69fc","title":"Source field"},{"id":"f02ceab6-9259-42a8-9a29-3e2c6bdc5361","title":"FHIR element"},{"id":"2b4a4844-b67f-4ee3-9959-84bf03f40070","title":"Notes"}]'>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">treatment_id</code></p></table-cell>
    <table-cell><p class="slate-p "><code class="slate-code">Procedure.id</code></p></table-cell>
    <table-cell><p class="slate-p ">Resource identifier.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">item_code</code></p></table-cell>
    <table-cell><p class="slate-p "><code class="slate-code">Procedure.code.coding[].code</code></p></table-cell>
    <table-cell><p class="slate-p ">System <code class="slate-code">https://api.dental4web.com.au/fhir/codes/procedure-codes</code>; the procedure description is carried in <code class="slate-code">display</code>.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">patient_id</code></p></table-cell>
    <table-cell><p class="slate-p "><code class="slate-code">Procedure.subject.reference</code></p></table-cell>
    <table-cell><p class="slate-p ">In the form <code class="slate-code">Patient/{patient_id}</code>.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">treatment_date</code></p></table-cell>
    <table-cell><p class="slate-p "><code class="slate-code">Procedure.performedDateTime</code></p></table-cell>
    <table-cell><p class="slate-p ">Date precision (<code class="slate-code">YYYY-MM-DD</code>).</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">practitioner_id</code></p></table-cell>
    <table-cell><p class="slate-p "><code class="slate-code">Procedure.performer[].actor.reference</code></p></table-cell>
    <table-cell><p class="slate-p ">In the form <code class="slate-code">Practitioner/{practitioner_id}</code>; the practitioner name is carried in <code class="slate-code">display</code>.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">location_id</code></p></table-cell>
    <table-cell><p class="slate-p "><code class="slate-code">Procedure.location.reference</code></p></table-cell>
    <table-cell><p class="slate-p ">In the form <code class="slate-code">Location/{location_id}</code>; the location name is carried in <code class="slate-code">display</code>.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">tooth</code> / <code class="slate-code">surface</code></p></table-cell>
    <table-cell><p class="slate-p "><code class="slate-code">Procedure.bodySite</code></p></table-cell>
    <table-cell><p class="slate-p "><code class="slate-code">null</code> when neither is recorded.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">item_fee</code></p></table-cell>
    <table-cell><p class="slate-p "><code class="slate-code">Procedure.extension[procedure-fee].valueMoney</code></p></table-cell>
    <table-cell><p class="slate-p ">Amount in AUD. URL <code class="slate-code">https://api.dental4web.com.au/fhir/extensions/procedure-fee</code>.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">item_qty</code></p></table-cell>
    <table-cell><p class="slate-p "><code class="slate-code">Procedure.extension[procedure-quantity].valueInteger</code></p></table-cell>
    <table-cell><p class="slate-p ">URL <code class="slate-code">https://api.dental4web.com.au/fhir/extensions/procedure-quantity</code>.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p ">(fixed)</p></table-cell>
    <table-cell><p class="slate-p "><code class="slate-code">Procedure.status</code></p></table-cell>
    <table-cell><p class="slate-p ">Always <code class="slate-code">completed</code>: only performed treatments are returned.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">updated_date</code></p></table-cell>
    <table-cell><p class="slate-p "><code class="slate-code">Procedure.meta.lastUpdated</code></p></table-cell>
    <table-cell><p class="slate-p ">Record last-modified timestamp.</p></table-cell>
  </table-row>
</Table>

The referenced `Practitioner` and `Location` resources are included as additional bundle entries. If a requested relation cannot be expanded (for example `patients`), the bundle appends an `OperationOutcome` entry with a `warning` issue rather than failing the request.

Response envelope
------------------

Every response also includes top-level `metadata` and `pagination` objects alongside the FHIR `Bundle` in `data`. See [API response formats](/api-response-formats) for the full field list.

<Table style="width:100%;min-width:100%" colSizes='["180px","135px","585px"]' isHeaderAdded='true' tableHeader='[{"id":"dea9da10-9ff7-4b6f-ac98-2e2bc7a29e37","title":"Field"},{"id":"ee64dc4d-b4ed-4d13-8219-333abdec3e41","title":"Type"},{"id":"a99f7f10-46fe-4734-8bd3-2377089e1946","title":"Description"}]'>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">metadata</code></p></table-cell>
    <table-cell><p class="slate-p ">object</p></table-cell>
    <table-cell><p class="slate-p ">Response envelope metadata. See <a href="/api-response-formats">API response formats</a> for the full field list.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">pagination</code></p></table-cell>
    <table-cell><p class="slate-p ">object</p></table-cell>
    <table-cell><p class="slate-p ">Pagination for the result set. See <a href="/api-response-formats">API response formats</a> for the full field list.</p></table-cell>
  </table-row>
</Table>

Sample bundle
-------------

<CodeBlock attributes='{"isFitToPage":true,"style":{},"lang":"json","label":"JSON"}'>
  <CodeLine></CodeLine>
  <CodeLine>  {</CodeLine>
  <CodeLine>    "status": true,</CodeLine>
  <CodeLine>    "message": "Success",</CodeLine>
  <CodeLine>    "data": {</CodeLine>
  <CodeLine>      "resourceType": "Bundle",</CodeLine>
  <CodeLine>      "id": "b41fa10c-1398-423c-9d75-576335871a29",</CodeLine>
  <CodeLine>      "type": "searchset",</CodeLine>
  <CodeLine>      "total": 21,</CodeLine>
  <CodeLine>      "entry": [</CodeLine>
  <CodeLine>        {</CodeLine>
  <CodeLine>          "resource": {</CodeLine>
  <CodeLine>            "resourceType": "Procedure",</CodeLine>
  <CodeLine>            "id": "104301",</CodeLine>
  <CodeLine>            "status": "completed",</CodeLine>
  <CodeLine>            "code": {</CodeLine>
  <CodeLine>              "coding": [</CodeLine>
  <CodeLine>                {</CodeLine>
  <CodeLine>                  "system": "https://api.dental4web.com.au/fhir/codes/procedure-codes",</CodeLine>
  <CodeLine>                  "code": "114",</CodeLine>
  <CodeLine>                  "display": "Removal Of Calculus - first appointment"</CodeLine>
  <CodeLine>                }</CodeLine>
  <CodeLine>              ]</CodeLine>
  <CodeLine>            },</CodeLine>
  <CodeLine>            "subject": { "reference": "Patient/72" },</CodeLine>
  <CodeLine>            "performedDateTime": "2018-02-26",</CodeLine>
  <CodeLine>            "performer": [</CodeLine>
  <CodeLine>              { "actor": { "reference": "Practitioner/69", "display": "Dr Wing Gillespie" } }</CodeLine>
  <CodeLine>            ],</CodeLine>
  <CodeLine>            "location": { "reference": "Location/1", "display": "Crown Jewels Dental" },</CodeLine>
  <CodeLine>            "bodySite": null,</CodeLine>
  <CodeLine>            "extension": [</CodeLine>
  <CodeLine>              { "url": "https://api.dental4web.com.au/fhir/extensions/procedure-fee", "valueMoney": { "value": 0.0, "currency": "AUD" } },</CodeLine>
  <CodeLine>              { "url": "https://api.dental4web.com.au/fhir/extensions/procedure-quantity", "valueInteger": 1 }</CodeLine>
  <CodeLine>            ],</CodeLine>
  <CodeLine>            "meta": { "lastUpdated": "2026-06-11T17:09:33.955000Z" }</CodeLine>
  <CodeLine>          }</CodeLine>
  <CodeLine>        },</CodeLine>
  <CodeLine>        {</CodeLine>
  <CodeLine>          "resource": {</CodeLine>
  <CodeLine>            "resourceType": "Practitioner",</CodeLine>
  <CodeLine>            "id": "69",</CodeLine>
  <CodeLine>            "identifier": [</CodeLine>
  <CodeLine>              { "system": "https://api.dental4web.com.au/fhir/codes/practitioner-codes", "value": "WGI" }</CodeLine>
  <CodeLine>            ],</CodeLine>
  <CodeLine>            "name": [ { "text": "Dr Wing Gillespie", "family": "Gillespie", "given": ["Wing"], "prefix": ["Dr"] } ],</CodeLine>
  <CodeLine>            "active": false,</CodeLine>
  <CodeLine>            "qualification": [],</CodeLine>
  <CodeLine>            "meta": { "lastUpdated": "2026-06-04T17:07:33.706005Z" }</CodeLine>
  <CodeLine>          }</CodeLine>
  <CodeLine>        },</CodeLine>
  <CodeLine>        {</CodeLine>
  <CodeLine>          "resource": {</CodeLine>
  <CodeLine>            "resourceType": "Location",</CodeLine>
  <CodeLine>            "id": "1",</CodeLine>
  <CodeLine>            "name": "Crown Jewels Dental",</CodeLine>
  <CodeLine>            "status": "active",</CodeLine>
  <CodeLine>            "address": { "text": "Level 5 The Plaque Chambers 100 Root Canal Avenue CORELLA QLD 4570", "country": "Australia" },</CodeLine>
  <CodeLine>            "telecom": [ { "system": "phone", "value": "05 1234 5678" } ],</CodeLine>
  <CodeLine>            "meta": { "lastUpdated": "2026-06-04T17:07:33.745000Z" }</CodeLine>
  <CodeLine>          }</CodeLine>
  <CodeLine>        },</CodeLine>
  <CodeLine>        {</CodeLine>
  <CodeLine>          "search": { "mode": "outcome" },</CodeLine>
  <CodeLine>          "resource": {</CodeLine>
  <CodeLine>            "resourceType": "OperationOutcome",</CodeLine>
  <CodeLine>            "issue": [</CodeLine>
  <CodeLine>              { "severity": "warning", "code": "incomplete", "diagnostics": "Relation 'patients' was not expanded: filter_required — A filter value is required to expand this related data." }</CodeLine>
  <CodeLine>            ]</CodeLine>
  <CodeLine>          }</CodeLine>
  <CodeLine>        }</CodeLine>
  <CodeLine>      ],</CodeLine>
  <CodeLine>      "meta": { "lastUpdated": "2026-06-09T09:17:56.128213Z" }</CodeLine>
  <CodeLine>    },</CodeLine>
  <CodeLine>    "pagination": { "page": 1, "per_page": 10, "total_rows": 21, "total_pages": 3 }</CodeLine>
  <CodeLine>  }</CodeLine>
</CodeBlock>

Important notes
---------------

*   **Required filters:** at least one filter parameter is required.
    
*   **Date filtering:** supports the `mode` parameter: see [Filtering & Date Ranges](/filtering-and-date-ranges).
    
*   **Wildcard values:** use `practitioner_id=-1` for all practitioners and `location_id=-1` for all locations.
    

Note: FHIR endpoints return `Content-Type: application/json`, not the FHIR-standard `application/fhir+json`. Bundles are wrapped inside the standard Dental API response envelope.

GET Treatments - FHIR

Retrieves patient records as FHIR R4 `Patient` resources. The response is a searchset `Bundle` containing `Patient` resources, with related `Practitioner` and `Location` resources included. Parameters and constraints match `GET /patients`, plus an optional `date_of_birth` filter (`YYYY-MM-DD`) that counts as a narrowing filter.

Resource mapping
----------------

<Table style="width:100%;min-width:100%" colSizes='["180px","135px","585px"]' isHeaderAdded='true' tableHeader='[{"id":"4eea46d6-6b79-4c97-b069-3636d98a1996","title":"Source field"},{"id":"c68c123d-bb35-4de2-90c5-d6de71ea4a85","title":"FHIR element"},{"id":"d80da620-7b30-405e-883d-b76a2e697954","title":"Notes"}]'>
  <table-row>
    <table-cell><p class="slate-p ">Patient ID</p></table-cell>
    <table-cell><p class="slate-p "><code class="slate-code">Patient.id</code> and <code class="slate-code">Patient.identifier</code></p></table-cell>
    <table-cell><p class="slate-p ">Identifier system is <code class="slate-code">https://api.dental4web.com.au/fhir/identifier/patient-card</code>.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p ">Active status</p></table-cell>
    <table-cell><p class="slate-p "><code class="slate-code">Patient.active</code></p></table-cell>
    <table-cell><p class="slate-p ">Mapped from <code class="slate-code">patient_status</code>; <code class="slate-code">true</code> if status is "Active".</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p ">Name</p></table-cell>
    <table-cell><p class="slate-p "><code class="slate-code">Patient.name</code></p></table-cell>
    <table-cell><p class="slate-p ">Mapped to <code class="slate-code">family</code>, <code class="slate-code">given</code>, and <code class="slate-code">prefix</code> with <code class="slate-code">use: official</code>.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p ">Phone numbers</p></table-cell>
    <table-cell><p class="slate-p "><code class="slate-code">Patient.telecom</code></p></table-cell>
    <table-cell><p class="slate-p ">Home and mobile numbers as <code class="slate-code">phone</code> entries.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p ">Gender</p></table-cell>
    <table-cell><p class="slate-p "><code class="slate-code">Patient.gender</code></p></table-cell>
    <table-cell><p class="slate-p ">FHIR administrative gender.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p ">Date of birth</p></table-cell>
    <table-cell><p class="slate-p "><code class="slate-code">Patient.birthDate</code></p></table-cell>
    <table-cell><p class="slate-p ">Format <code class="slate-code">YYYY-MM-DD</code>.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p ">Address</p></table-cell>
    <table-cell><p class="slate-p "><code class="slate-code">Patient.address</code></p></table-cell>
    <table-cell><p class="slate-p ">Mapped to <code class="slate-code">line</code>, <code class="slate-code">city</code>, <code class="slate-code">state</code>, <code class="slate-code">postalCode</code>, and <code class="slate-code">country</code>.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p ">Treating practitioner</p></table-cell>
    <table-cell><p class="slate-p "><code class="slate-code">Patient.generalPractitioner</code></p></table-cell>
    <table-cell><p class="slate-p ">Reference to a <code class="slate-code">Practitioner</code> resource included in the bundle.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p ">Last-modified timestamp</p></table-cell>
    <table-cell><p class="slate-p "><code class="slate-code">Patient.meta.lastUpdated</code></p></table-cell>
    <table-cell><p class="slate-p ">Record's last-modified timestamp.</p></table-cell>
  </table-row>
</Table>

Response envelope
------------------

Every response also includes top-level `metadata` and `pagination` objects alongside the FHIR `Bundle` in `data`. See [API response formats](/api-response-formats) for the full field list.

<Table style="width:100%;min-width:100%" colSizes='["180px","135px","585px"]' isHeaderAdded='true' tableHeader='[{"id":"bf489f83-5e8c-418c-bae1-c84cba15c6bc","title":"Field"},{"id":"7c518090-a3d2-45dd-9d65-b5ac87de3db7","title":"Type"},{"id":"11344501-6bcc-4319-bdf7-a490a3e60adf","title":"Description"}]'>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">metadata</code></p></table-cell>
    <table-cell><p class="slate-p ">object</p></table-cell>
    <table-cell><p class="slate-p ">Response envelope metadata. See <a href="/api-response-formats">API response formats</a> for the full field list.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">pagination</code></p></table-cell>
    <table-cell><p class="slate-p ">object</p></table-cell>
    <table-cell><p class="slate-p ">Pagination for the result set. See <a href="/api-response-formats">API response formats</a> for the full field list.</p></table-cell>
  </table-row>
</Table>

Sample bundle
-------------

<CodeBlock attributes='{"isFitToPage":true,"style":{},"lang":"json","label":"JSON"}'>
  <CodeLine></CodeLine>
  <CodeLine>  {</CodeLine>
  <CodeLine>    "status": true,</CodeLine>
  <CodeLine>    "message": "Success",</CodeLine>
  <CodeLine>    "data": {</CodeLine>
  <CodeLine>      "resourceType": "Bundle",</CodeLine>
  <CodeLine>      "id": "uuid",</CodeLine>
  <CodeLine>      "type": "searchset",</CodeLine>
  <CodeLine>      "total": 11,</CodeLine>
  <CodeLine>      "entry": [</CodeLine>
  <CodeLine>        {</CodeLine>
  <CodeLine>          "resource": {</CodeLine>
  <CodeLine>            "resourceType": "Patient",</CodeLine>
  <CodeLine>            "id": "6570",</CodeLine>
  <CodeLine>            "identifier": [</CodeLine>
  <CodeLine>              {</CodeLine>
  <CodeLine>                "system": "https://api.dental4web.com.au/fhir/identifier/patient-card",</CodeLine>
  <CodeLine>                "value": "6570"</CodeLine>
  <CodeLine>              }</CodeLine>
  <CodeLine>            ],</CodeLine>
  <CodeLine>            "active": true,</CodeLine>
  <CodeLine>            "name": [</CodeLine>
  <CodeLine>              {</CodeLine>
  <CodeLine>                "use": "official",</CodeLine>
  <CodeLine>                "family": "Burris",</CodeLine>
  <CodeLine>                "given": ["John", "Christian"],</CodeLine>
  <CodeLine>                "prefix": ["Mr"]</CodeLine>
  <CodeLine>              }</CodeLine>
  <CodeLine>            ],</CodeLine>
  <CodeLine>            "telecom": [</CodeLine>
  <CodeLine>              {"system": "phone", "value": "(01) 8015 6714", "use": "home"},</CodeLine>
  <CodeLine>              {"system": "phone", "value": "0412 345 678", "use": "mobile"}</CodeLine>
  <CodeLine>            ],</CodeLine>
  <CodeLine>            "gender": "male",</CodeLine>
  <CodeLine>            "birthDate": "1922-03-11",</CodeLine>
  <CodeLine>            "address": [</CodeLine>
  <CodeLine>              {</CodeLine>
  <CodeLine>                "line": ["Ap #231-6175 Luctus. Rd.", "ADDRESS"],</CodeLine>
  <CodeLine>                "city": "FLORENTINE",</CodeLine>
  <CodeLine>                "state": "TAS",</CodeLine>
  <CodeLine>                "postalCode": "7140",</CodeLine>
  <CodeLine>                "country": "Australia"</CodeLine>
  <CodeLine>              }</CodeLine>
  <CodeLine>            ],</CodeLine>
  <CodeLine>            "generalPractitioner": [</CodeLine>
  <CodeLine>              {"reference": "Practitioner/22", "display": "Dr Quintessa Ayala"}</CodeLine>
  <CodeLine>            ],</CodeLine>
  <CodeLine>            "meta": {"lastUpdated": "2025-11-19T23:34:55.407178Z"}</CodeLine>
  <CodeLine>          }</CodeLine>
  <CodeLine>        },</CodeLine>
  <CodeLine>        {</CodeLine>
  <CodeLine>          "resource": {</CodeLine>
  <CodeLine>            "resourceType": "Location",</CodeLine>
  <CodeLine>            "id": "1",</CodeLine>
  <CodeLine>            "name": "Smile Til You Drop Melbourne",</CodeLine>
  <CodeLine>            "status": "active"</CodeLine>
  <CodeLine>          }</CodeLine>
  <CodeLine>        },</CodeLine>
  <CodeLine>        {</CodeLine>
  <CodeLine>          "resource": {</CodeLine>
  <CodeLine>            "resourceType": "Practitioner",</CodeLine>
  <CodeLine>            "id": "22",</CodeLine>
  <CodeLine>            "identifier": [...],</CodeLine>
  <CodeLine>            "name": [...],</CodeLine>
  <CodeLine>            "active": true</CodeLine>
  <CodeLine>          }</CodeLine>
  <CodeLine>        }</CodeLine>
  <CodeLine>      ],</CodeLine>
  <CodeLine>      "meta": {"lastUpdated": "2026-02-11T11:00:09.276112Z"}</CodeLine>
  <CodeLine>    },</CodeLine>
  <CodeLine>    "pagination": {...}</CodeLine>
  <CodeLine>  }</CodeLine>
</CodeBlock>

Note: FHIR endpoints return `Content-Type: application/json`, not the FHIR-standard `application/fhir+json`. Bundles are wrapped inside the standard Dental API response envelope.

GET Patients - FHIR

Retrieves a single patient as a FHIR R4 `Patient` resource. The response is a searchset `Bundle` containing one `Patient` resource. Parameters and constraints match `GET /patients/{patient_id}`.

Resource mapping
----------------

<Table style="width:100%;min-width:100%" colSizes='["180px","135px","585px"]' isHeaderAdded='true' tableHeader='[{"id":"e8c4a2e6-fe2e-4026-a364-0920d5a245e4","title":"Source field"},{"id":"cd95b582-6c68-46b3-937c-2d1163f4579a","title":"FHIR element"},{"id":"cc1eca52-f919-4597-8d16-c7123f2f62bf","title":"Notes"}]'>
  <table-row>
    <table-cell><p class="slate-p ">Patient ID</p></table-cell>
    <table-cell><p class="slate-p "><code class="slate-code">Patient.id</code> and <code class="slate-code">Patient.identifier</code></p></table-cell>
    <table-cell><p class="slate-p ">Identifier system is <code class="slate-code">https://api.dental4web.com.au/fhir/identifier/patient-card</code>.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p ">Active status</p></table-cell>
    <table-cell><p class="slate-p "><code class="slate-code">Patient.active</code></p></table-cell>
    <table-cell><p class="slate-p ">Mapped from <code class="slate-code">patient_status</code>; <code class="slate-code">true</code> if status is "Active".</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p ">Name</p></table-cell>
    <table-cell><p class="slate-p "><code class="slate-code">Patient.name</code></p></table-cell>
    <table-cell><p class="slate-p ">Mapped to <code class="slate-code">family</code>, <code class="slate-code">given</code>, and <code class="slate-code">prefix</code> with <code class="slate-code">use: official</code>.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p ">Phone numbers</p></table-cell>
    <table-cell><p class="slate-p "><code class="slate-code">Patient.telecom</code></p></table-cell>
    <table-cell><p class="slate-p ">Home and mobile numbers as <code class="slate-code">phone</code> entries.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p ">Gender</p></table-cell>
    <table-cell><p class="slate-p "><code class="slate-code">Patient.gender</code></p></table-cell>
    <table-cell><p class="slate-p ">FHIR administrative gender.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p ">Date of birth</p></table-cell>
    <table-cell><p class="slate-p "><code class="slate-code">Patient.birthDate</code></p></table-cell>
    <table-cell><p class="slate-p ">Format <code class="slate-code">YYYY-MM-DD</code>.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p ">Address</p></table-cell>
    <table-cell><p class="slate-p "><code class="slate-code">Patient.address</code></p></table-cell>
    <table-cell><p class="slate-p ">Mapped to <code class="slate-code">line</code>, <code class="slate-code">city</code>, <code class="slate-code">state</code>, <code class="slate-code">postalCode</code>, and <code class="slate-code">country</code>.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p ">Treating practitioner</p></table-cell>
    <table-cell><p class="slate-p "><code class="slate-code">Patient.generalPractitioner</code></p></table-cell>
    <table-cell><p class="slate-p ">Reference to a <code class="slate-code">Practitioner</code> resource included in the bundle.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p ">Last-modified timestamp</p></table-cell>
    <table-cell><p class="slate-p "><code class="slate-code">Patient.meta.lastUpdated</code></p></table-cell>
    <table-cell><p class="slate-p ">Record's last-modified timestamp.</p></table-cell>
  </table-row>
</Table>

Response envelope
------------------

Every response also includes top-level `metadata` and `pagination` objects alongside the FHIR `Bundle` in `data`. See [API response formats](/api-response-formats) for the full field list.

<Table style="width:100%;min-width:100%" colSizes='["180px","135px","585px"]' isHeaderAdded='true' tableHeader='[{"id":"9d6025f5-316f-4612-a26c-e060709ba866","title":"Field"},{"id":"e62f659c-ad41-4acd-94ff-79e7c707ec52","title":"Type"},{"id":"db61a14c-95e2-452c-8dff-4e938d111779","title":"Description"}]'>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">metadata</code></p></table-cell>
    <table-cell><p class="slate-p ">object</p></table-cell>
    <table-cell><p class="slate-p ">Response envelope metadata. See <a href="/api-response-formats">API response formats</a> for the full field list.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">pagination</code></p></table-cell>
    <table-cell><p class="slate-p ">object</p></table-cell>
    <table-cell><p class="slate-p ">Pagination for the result set. See <a href="/api-response-formats">API response formats</a> for the full field list.</p></table-cell>
  </table-row>
</Table>

Sample bundle
-------------

<CodeBlock attributes='{"isFitToPage":true,"style":{},"lang":"json","label":"JSON"}'>
  <CodeLine></CodeLine>
  <CodeLine>  {</CodeLine>
  <CodeLine>    "status": true,</CodeLine>
  <CodeLine>    "message": "Success",</CodeLine>
  <CodeLine>    "data": {</CodeLine>
  <CodeLine>      "resourceType": "Bundle",</CodeLine>
  <CodeLine>      "id": "uuid",</CodeLine>
  <CodeLine>      "type": "searchset",</CodeLine>
  <CodeLine>      "total": 11,</CodeLine>
  <CodeLine>      "entry": [</CodeLine>
  <CodeLine>        {</CodeLine>
  <CodeLine>          "resource": {</CodeLine>
  <CodeLine>            "resourceType": "Patient",</CodeLine>
  <CodeLine>            "id": "6570",</CodeLine>
  <CodeLine>            "identifier": [</CodeLine>
  <CodeLine>              {</CodeLine>
  <CodeLine>                "system": "https://api.dental4web.com.au/fhir/identifier/patient-card",</CodeLine>
  <CodeLine>                "value": "6570"</CodeLine>
  <CodeLine>              }</CodeLine>
  <CodeLine>            ],</CodeLine>
  <CodeLine>            "active": true,</CodeLine>
  <CodeLine>            "name": [</CodeLine>
  <CodeLine>              {</CodeLine>
  <CodeLine>                "use": "official",</CodeLine>
  <CodeLine>                "family": "Burris",</CodeLine>
  <CodeLine>                "given": ["John", "Christian"],</CodeLine>
  <CodeLine>                "prefix": ["Mr"]</CodeLine>
  <CodeLine>              }</CodeLine>
  <CodeLine>            ],</CodeLine>
  <CodeLine>            "telecom": [</CodeLine>
  <CodeLine>              {"system": "phone", "value": "(01) 8015 6714", "use": "home"},</CodeLine>
  <CodeLine>              {"system": "phone", "value": "0412 345 678", "use": "mobile"}</CodeLine>
  <CodeLine>            ],</CodeLine>
  <CodeLine>            "gender": "male",</CodeLine>
  <CodeLine>            "birthDate": "1922-03-11",</CodeLine>
  <CodeLine>            "address": [</CodeLine>
  <CodeLine>              {</CodeLine>
  <CodeLine>                "line": ["Ap #231-6175 Luctus. Rd.", "ADDRESS"],</CodeLine>
  <CodeLine>                "city": "FLORENTINE",</CodeLine>
  <CodeLine>                "state": "TAS",</CodeLine>
  <CodeLine>                "postalCode": "7140",</CodeLine>
  <CodeLine>                "country": "Australia"</CodeLine>
  <CodeLine>              }</CodeLine>
  <CodeLine>            ],</CodeLine>
  <CodeLine>            "generalPractitioner": [</CodeLine>
  <CodeLine>              {"reference": "Practitioner/22", "display": "Dr Quintessa Ayala"}</CodeLine>
  <CodeLine>            ],</CodeLine>
  <CodeLine>            "meta": {"lastUpdated": "2025-11-19T23:34:55.407178Z"}</CodeLine>
  <CodeLine>          }</CodeLine>
  <CodeLine>        },</CodeLine>
  <CodeLine>        {</CodeLine>
  <CodeLine>          "resource": {</CodeLine>
  <CodeLine>            "resourceType": "Location",</CodeLine>
  <CodeLine>            "id": "1",</CodeLine>
  <CodeLine>            "name": "Smile Til You Drop Melbourne",</CodeLine>
  <CodeLine>            "status": "active"</CodeLine>
  <CodeLine>          }</CodeLine>
  <CodeLine>        },</CodeLine>
  <CodeLine>        {</CodeLine>
  <CodeLine>          "resource": {</CodeLine>
  <CodeLine>            "resourceType": "Practitioner",</CodeLine>
  <CodeLine>            "id": "22",</CodeLine>
  <CodeLine>            "identifier": [...],</CodeLine>
  <CodeLine>            "name": [...],</CodeLine>
  <CodeLine>            "active": true</CodeLine>
  <CodeLine>          }</CodeLine>
  <CodeLine>        }</CodeLine>
  <CodeLine>      ],</CodeLine>
  <CodeLine>      "meta": {"lastUpdated": "2026-02-11T11:00:09.276112Z"}</CodeLine>
  <CodeLine>    },</CodeLine>
  <CodeLine>    "pagination": {...}</CodeLine>
  <CodeLine>  }</CodeLine>
</CodeBlock>

Note: FHIR endpoints return `Content-Type: application/json`, not the FHIR-standard `application/fhir+json`. Bundles are wrapped inside the standard Dental API response envelope.

GET Patient By ID - FHIR

Retrieves appointments as FHIR R4 `Appointment` resources. The response is a searchset `Bundle` containing `Appointment` resources, with `Patient`, `Practitioner`, and `Location` participants included. Parameters and constraints match `GET /appointments`.

Resource mapping
----------------

<Table style="width:100%;min-width:100%" colSizes='["180px","135px","585px"]' isHeaderAdded='true' tableHeader='[{"id":"e30c05a3-9c89-4578-ad3f-ec50285f52a8","title":"Source field"},{"id":"4881c62d-9f77-4f96-897a-affe8cb67fdb","title":"FHIR element"},{"id":"de756f47-9fa9-4a90-a483-4ea5b1d4a213","title":"Notes"}]'>
  <table-row>
    <table-cell><p class="slate-p ">Appointment ID</p></table-cell>
    <table-cell><p class="slate-p "><code class="slate-code">Appointment.id</code></p></table-cell>
    <table-cell><p class="slate-p ">Source appointment identifier.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p ">Status</p></table-cell>
    <table-cell><p class="slate-p "><code class="slate-code">Appointment.status</code></p></table-cell>
    <table-cell><p class="slate-p ">FHIR appointment status, for example <code class="slate-code">booked</code>.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p ">Start / end time</p></table-cell>
    <table-cell><p class="slate-p "><code class="slate-code">Appointment.start</code> and <code class="slate-code">Appointment.end</code></p></table-cell>
    <table-cell><p class="slate-p ">ISO 8601 instants in UTC.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p ">Patient</p></table-cell>
    <table-cell><p class="slate-p "><code class="slate-code">Appointment.participant[].actor</code> (<code class="slate-code">Patient</code>)</p></table-cell>
    <table-cell><p class="slate-p ">Reference to a <code class="slate-code">Patient</code> resource included in the bundle.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p ">Practitioner</p></table-cell>
    <table-cell><p class="slate-p "><code class="slate-code">Appointment.participant[].actor</code> (<code class="slate-code">Practitioner</code>)</p></table-cell>
    <table-cell><p class="slate-p ">Reference to a <code class="slate-code">Practitioner</code> resource included in the bundle.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p ">Location</p></table-cell>
    <table-cell><p class="slate-p "><code class="slate-code">Appointment.participant[].actor</code> (<code class="slate-code">Location</code>)</p></table-cell>
    <table-cell><p class="slate-p ">Reference to a <code class="slate-code">Location</code> resource included in the bundle.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p ">Last-modified timestamp</p></table-cell>
    <table-cell><p class="slate-p "><code class="slate-code">Appointment.meta.lastUpdated</code></p></table-cell>
    <table-cell><p class="slate-p ">Record's last-modified timestamp.</p></table-cell>
  </table-row>
</Table>

Response envelope
------------------

Every response also includes top-level `metadata` and `pagination` objects alongside the FHIR `Bundle` in `data`. See [API response formats](/api-response-formats) for the full field list.

<Table style="width:100%;min-width:100%" colSizes='["180px","135px","585px"]' isHeaderAdded='true' tableHeader='[{"id":"e5ab89f5-532d-4c06-a821-ea29164eb35d","title":"Field"},{"id":"00b3ec40-534c-47ff-9cbc-d98182386d8f","title":"Type"},{"id":"523c9825-863e-4d37-a11b-4175a5a9d92f","title":"Description"}]'>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">metadata</code></p></table-cell>
    <table-cell><p class="slate-p ">object</p></table-cell>
    <table-cell><p class="slate-p ">Response envelope metadata. See <a href="/api-response-formats">API response formats</a> for the full field list.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">pagination</code></p></table-cell>
    <table-cell><p class="slate-p ">object</p></table-cell>
    <table-cell><p class="slate-p ">Pagination for the result set. See <a href="/api-response-formats">API response formats</a> for the full field list.</p></table-cell>
  </table-row>
</Table>

Sample bundle
-------------

<CodeBlock attributes='{"isFitToPage":true,"style":{},"lang":"json","label":"JSON"}'>
  <CodeLine></CodeLine>
  <CodeLine>  {</CodeLine>
  <CodeLine>    "status": true,</CodeLine>
  <CodeLine>    "message": "Success",</CodeLine>
  <CodeLine>    "data": {</CodeLine>
  <CodeLine>      "resourceType": "Bundle",</CodeLine>
  <CodeLine>      "id": "uuid",</CodeLine>
  <CodeLine>      "type": "searchset",</CodeLine>
  <CodeLine>      "total": 7724,</CodeLine>
  <CodeLine>      "entry": [</CodeLine>
  <CodeLine>        {</CodeLine>
  <CodeLine>          "resource": {</CodeLine>
  <CodeLine>            "resourceType": "Appointment",</CodeLine>
  <CodeLine>            "id": "76878",</CodeLine>
  <CodeLine>            "status": "booked",</CodeLine>
  <CodeLine>            "start": "2025-07-17T09:00:00Z",</CodeLine>
  <CodeLine>            "end": "2025-07-17T10:00:00Z",</CodeLine>
  <CodeLine>            "participant": [</CodeLine>
  <CodeLine>              {</CodeLine>
  <CodeLine>                "actor": {"reference": "Patient/2", "display": "Emerie Snyder"},</CodeLine>
  <CodeLine>                "status": "accepted"</CodeLine>
  <CodeLine>              },</CodeLine>
  <CodeLine>              {</CodeLine>
  <CodeLine>                "actor": {"reference": "Practitioner/23", "display": "Dr Blake Castro"},</CodeLine>
  <CodeLine>                "status": "accepted"</CodeLine>
  <CodeLine>              },</CodeLine>
  <CodeLine>              {</CodeLine>
  <CodeLine>                "actor": {"reference": "Location/1", "display": "Smile Til You Drop Melbourne"},</CodeLine>
  <CodeLine>                "status": "accepted"</CodeLine>
  <CodeLine>              }</CodeLine>
  <CodeLine>            ],</CodeLine>
  <CodeLine>            "meta": {"lastUpdated": "2026-01-08T11:02:01.319007Z"}</CodeLine>
  <CodeLine>          }</CodeLine>
  <CodeLine>        },</CodeLine>
  <CodeLine>        {"resource": {"resourceType": "Location", ...}},</CodeLine>
  <CodeLine>        {"resource": {"resourceType": "Practitioner", ...}},</CodeLine>
  <CodeLine>        {"resource": {"resourceType": "Patient", ...}}</CodeLine>
  <CodeLine>      ]</CodeLine>
  <CodeLine>    },</CodeLine>
  <CodeLine>    "pagination": {...}</CodeLine>
  <CodeLine>  }</CodeLine>
</CodeBlock>

Note: FHIR endpoints return `Content-Type: application/json`, not the FHIR-standard `application/fhir+json`. Bundles are wrapped inside the standard Dental API response envelope.

GET Appointments - FHIR

Retrieves a single appointment as a FHIR R4 `Appointment` resource. The response is a searchset `Bundle` containing one `Appointment` resource, with `Patient`, `Practitioner`, and `Location` participants included. Parameters and constraints match `GET /appointments/{appointment_id}`.

Resource mapping
----------------

<Table style="width:100%;min-width:100%" colSizes='["180px","135px","585px"]' isHeaderAdded='true' tableHeader='[{"id":"73380368-ebf6-46c5-a7f7-b8c93c793da3","title":"Source field"},{"id":"32f7bc91-e314-4332-a437-c678b23c07bb","title":"FHIR element"},{"id":"1bbcc96a-efe7-495e-bf42-326fe7e5167d","title":"Notes"}]'>
  <table-row>
    <table-cell><p class="slate-p ">Appointment ID</p></table-cell>
    <table-cell><p class="slate-p "><code class="slate-code">Appointment.id</code></p></table-cell>
    <table-cell><p class="slate-p ">Source appointment identifier.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p ">Status</p></table-cell>
    <table-cell><p class="slate-p "><code class="slate-code">Appointment.status</code></p></table-cell>
    <table-cell><p class="slate-p ">FHIR appointment status, for example <code class="slate-code">booked</code>.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p ">Start / end time</p></table-cell>
    <table-cell><p class="slate-p "><code class="slate-code">Appointment.start</code> and <code class="slate-code">Appointment.end</code></p></table-cell>
    <table-cell><p class="slate-p ">ISO 8601 instants in UTC.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p ">Patient</p></table-cell>
    <table-cell><p class="slate-p "><code class="slate-code">Appointment.participant[].actor</code> (<code class="slate-code">Patient</code>)</p></table-cell>
    <table-cell><p class="slate-p ">Reference to a <code class="slate-code">Patient</code> resource included in the bundle.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p ">Practitioner</p></table-cell>
    <table-cell><p class="slate-p "><code class="slate-code">Appointment.participant[].actor</code> (<code class="slate-code">Practitioner</code>)</p></table-cell>
    <table-cell><p class="slate-p ">Reference to a <code class="slate-code">Practitioner</code> resource included in the bundle.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p ">Location</p></table-cell>
    <table-cell><p class="slate-p "><code class="slate-code">Appointment.participant[].actor</code> (<code class="slate-code">Location</code>)</p></table-cell>
    <table-cell><p class="slate-p ">Reference to a <code class="slate-code">Location</code> resource included in the bundle.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p ">Last-modified timestamp</p></table-cell>
    <table-cell><p class="slate-p "><code class="slate-code">Appointment.meta.lastUpdated</code></p></table-cell>
    <table-cell><p class="slate-p ">Record's last-modified timestamp.</p></table-cell>
  </table-row>
</Table>

Response envelope
------------------

Every response also includes top-level `metadata` and `pagination` objects alongside the FHIR `Bundle` in `data`. See [API response formats](/api-response-formats) for the full field list.

<Table style="width:100%;min-width:100%" colSizes='["180px","135px","585px"]' isHeaderAdded='true' tableHeader='[{"id":"08e4ffc8-e044-44d7-9b45-4c8e3e54c6d6","title":"Field"},{"id":"d49951ae-cfe7-4b52-bef1-d135cc9daa02","title":"Type"},{"id":"fce5b203-ebc7-424f-aeb4-90aadb6798be","title":"Description"}]'>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">metadata</code></p></table-cell>
    <table-cell><p class="slate-p ">object</p></table-cell>
    <table-cell><p class="slate-p ">Response envelope metadata. See <a href="/api-response-formats">API response formats</a> for the full field list.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">pagination</code></p></table-cell>
    <table-cell><p class="slate-p ">object</p></table-cell>
    <table-cell><p class="slate-p ">Pagination for the result set. See <a href="/api-response-formats">API response formats</a> for the full field list.</p></table-cell>
  </table-row>
</Table>

Sample bundle
-------------

<CodeBlock attributes='{"isFitToPage":true,"style":{},"lang":"json","label":"JSON"}'>
  <CodeLine></CodeLine>
  <CodeLine>  {</CodeLine>
  <CodeLine>    "status": true,</CodeLine>
  <CodeLine>    "message": "Success",</CodeLine>
  <CodeLine>    "data": {</CodeLine>
  <CodeLine>      "resourceType": "Bundle",</CodeLine>
  <CodeLine>      "id": "uuid",</CodeLine>
  <CodeLine>      "type": "searchset",</CodeLine>
  <CodeLine>      "total": 7724,</CodeLine>
  <CodeLine>      "entry": [</CodeLine>
  <CodeLine>        {</CodeLine>
  <CodeLine>          "resource": {</CodeLine>
  <CodeLine>            "resourceType": "Appointment",</CodeLine>
  <CodeLine>            "id": "76878",</CodeLine>
  <CodeLine>            "status": "booked",</CodeLine>
  <CodeLine>            "start": "2025-07-17T09:00:00Z",</CodeLine>
  <CodeLine>            "end": "2025-07-17T10:00:00Z",</CodeLine>
  <CodeLine>            "participant": [</CodeLine>
  <CodeLine>              {</CodeLine>
  <CodeLine>                "actor": {"reference": "Patient/2"},</CodeLine>
  <CodeLine>                "status": "accepted"</CodeLine>
  <CodeLine>              },</CodeLine>
  <CodeLine>              {</CodeLine>
  <CodeLine>                "actor": {"reference": "Practitioner/23", "display": "Dr Blake Castro"},</CodeLine>
  <CodeLine>                "status": "accepted"</CodeLine>
  <CodeLine>              },</CodeLine>
  <CodeLine>              {</CodeLine>
  <CodeLine>                "actor": {"reference": "Location/1", "display": "Smile Til You Drop Melbourne"},</CodeLine>
  <CodeLine>                "status": "accepted"</CodeLine>
  <CodeLine>              }</CodeLine>
  <CodeLine>            ],</CodeLine>
  <CodeLine>            "meta": {"lastUpdated": "2026-01-08T11:02:01.319007Z"}</CodeLine>
  <CodeLine>          }</CodeLine>
  <CodeLine>        },</CodeLine>
  <CodeLine>        {"resource": {"resourceType": "Location", ...}},</CodeLine>
  <CodeLine>        {"resource": {"resourceType": "Practitioner", ...}},</CodeLine>
  <CodeLine>        {</CodeLine>
  <CodeLine>          "resource": {</CodeLine>
  <CodeLine>            "resourceType": "OperationOutcome",</CodeLine>
  <CodeLine>            "issue": [</CodeLine>
  <CodeLine>              {</CodeLine>
  <CodeLine>                "severity": "warning",</CodeLine>
  <CodeLine>                "code": "incomplete",</CodeLine>
  <CodeLine>                "diagnostics": "Relation 'patients' was not expanded: filter_required — A filter value is required to expand this related data."</CodeLine>
  <CodeLine>              }</CodeLine>
  <CodeLine>            ]</CodeLine>
  <CodeLine>          }</CodeLine>
  <CodeLine>        }</CodeLine>
  <CodeLine>      ]</CodeLine>
  <CodeLine>    },</CodeLine>
  <CodeLine>    "pagination": {...}</CodeLine>
  <CodeLine>  }</CodeLine>
</CodeBlock>

Note: FHIR endpoints return `Content-Type: application/json`, not the FHIR-standard `application/fhir+json`. Bundles are wrapped inside the standard Dental API response envelope.

**Patient detail is not always embedded.** With only `appointment_id` supplied, the `Patient` participant carries no `display` name, and the bundle's `entry[]` includes an `OperationOutcome` resource explaining that the `patients` relation was not expanded because a filter value is required. `patient_id` is not an accepted query parameter on this route; passing it returns `400 "Unexpected parameters: patient_id"`. To retrieve full patient detail, look up the `patient_id` referenced in the `Patient` participant against [Get patient by ID](/patient-resources/get-patient-by-id).

GET Appointment By ID - FHIR

Retrieves clinical notes as FHIR R4 `Observation` resources. Each note is mapped to an `Observation` with LOINC coding. Parameters and constraints match `GET /clinical-notes`.

Resource mapping
----------------

<Table style="width:100%;min-width:100%" colSizes='["180px","135px","585px"]' isHeaderAdded='true' tableHeader='[{"id":"f96e3428-b13e-406e-b6f6-e70d718b8d7a","title":"Source field"},{"id":"7b9b7db8-995a-4ffe-b44b-64f615a7c509","title":"FHIR element"},{"id":"b9f61ecf-eb28-4ad3-a3a5-7c581e763356","title":"Notes"}]'>
  <table-row>
    <table-cell><p class="slate-p ">Note ID</p></table-cell>
    <table-cell><p class="slate-p "><code class="slate-code">Observation.id</code></p></table-cell>
    <table-cell><p class="slate-p ">Source note identifier.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p ">Status</p></table-cell>
    <table-cell><p class="slate-p "><code class="slate-code">Observation.status</code></p></table-cell>
    <table-cell><p class="slate-p ">Always <code class="slate-code">final</code>.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p ">Category</p></table-cell>
    <table-cell><p class="slate-p "><code class="slate-code">Observation.category</code></p></table-cell>
    <table-cell><p class="slate-p ">Coded <code class="slate-code">procedure</code> from the HL7 observation-category code system.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p ">Item code</p></table-cell>
    <table-cell><p class="slate-p "><code class="slate-code">Observation.code</code></p></table-cell>
    <table-cell><p class="slate-p ">Dual-coded: primary LOINC code <code class="slate-code">34109-9</code> ("Note"), and the original dental item code under <code class="slate-code">https://api.dental4web.com.au/codes/dental-item-codes</code>.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p ">Patient</p></table-cell>
    <table-cell><p class="slate-p "><code class="slate-code">Observation.subject</code></p></table-cell>
    <table-cell><p class="slate-p ">Reference to the <code class="slate-code">Patient</code> resource.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p ">Practitioner</p></table-cell>
    <table-cell><p class="slate-p "><code class="slate-code">Observation.performer</code></p></table-cell>
    <table-cell><p class="slate-p ">Reference to the authoring <code class="slate-code">Practitioner</code> resource.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p ">Note date</p></table-cell>
    <table-cell><p class="slate-p "><code class="slate-code">Observation.effectiveDateTime</code></p></table-cell>
    <table-cell><p class="slate-p ">FHIR <code class="slate-code">dateTime</code>, date precision only (<code class="slate-code">YYYY-MM-DD</code>); no time component is returned.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p ">Note content</p></table-cell>
    <table-cell><p class="slate-p "><code class="slate-code">Observation.valueString</code></p></table-cell>
    <table-cell><p class="slate-p ">Free-text note content.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p ">Tooth / surface</p></table-cell>
    <table-cell><p class="slate-p "><code class="slate-code">Observation.bodySite</code></p></table-cell>
    <table-cell><p class="slate-p ">Carried as text, for example <code class="slate-code">48, OB</code>.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p ">Last-modified timestamp</p></table-cell>
    <table-cell><p class="slate-p "><code class="slate-code">Observation.meta.lastUpdated</code></p></table-cell>
    <table-cell><p class="slate-p ">Record's last-modified timestamp.</p></table-cell>
  </table-row>
</Table>

Response envelope
------------------

Every response also includes top-level `metadata` and `pagination` objects alongside the FHIR `Bundle` in `data`. See [API response formats](/api-response-formats) for the full field list.

<Table style="width:100%;min-width:100%" colSizes='["180px","135px","585px"]' isHeaderAdded='true' tableHeader='[{"id":"ca80ce9c-59c9-4d2b-98bc-3dc35cbc39c3","title":"Field"},{"id":"31c62eb1-4637-4d4d-aeb4-bd21b01fd418","title":"Type"},{"id":"f88865fe-d3f8-4279-b098-28bbab317115","title":"Description"}]'>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">metadata</code></p></table-cell>
    <table-cell><p class="slate-p ">object</p></table-cell>
    <table-cell><p class="slate-p ">Response envelope metadata. See <a href="/api-response-formats">API response formats</a> for the full field list.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">pagination</code></p></table-cell>
    <table-cell><p class="slate-p ">object</p></table-cell>
    <table-cell><p class="slate-p ">Pagination for the result set. See <a href="/api-response-formats">API response formats</a> for the full field list.</p></table-cell>
  </table-row>
</Table>

Sample bundle
-------------

<CodeBlock attributes='{"isFitToPage":true,"style":{},"lang":"json","label":"JSON"}'>
  <CodeLine></CodeLine>
  <CodeLine>  {</CodeLine>
  <CodeLine>    "status": true,</CodeLine>
  <CodeLine>    "message": "Success",</CodeLine>
  <CodeLine>    "data": {</CodeLine>
  <CodeLine>      "resourceType": "Bundle",</CodeLine>
  <CodeLine>      "id": "uuid",</CodeLine>
  <CodeLine>      "type": "searchset",</CodeLine>
  <CodeLine>      "total": 70,</CodeLine>
  <CodeLine>      "entry": [</CodeLine>
  <CodeLine>        {</CodeLine>
  <CodeLine>          "resource": {</CodeLine>
  <CodeLine>            "resourceType": "Observation",</CodeLine>
  <CodeLine>            "id": "6051607",</CodeLine>
  <CodeLine>            "status": "final",</CodeLine>
  <CodeLine>            "category": [</CodeLine>
  <CodeLine>              {</CodeLine>
  <CodeLine>                "coding": [</CodeLine>
  <CodeLine>                  {</CodeLine>
  <CodeLine>                    "system": "http://terminology.hl7.org/CodeSystem/observation-category",</CodeLine>
  <CodeLine>                    "code": "procedure",</CodeLine>
  <CodeLine>                    "display": "Procedure"</CodeLine>
  <CodeLine>                  }</CodeLine>
  <CodeLine>                ]</CodeLine>
  <CodeLine>              }</CodeLine>
  <CodeLine>            ],</CodeLine>
  <CodeLine>            "code": {</CodeLine>
  <CodeLine>              "coding": [</CodeLine>
  <CodeLine>                {</CodeLine>
  <CodeLine>                  "system": "http://loinc.org",</CodeLine>
  <CodeLine>                  "code": "34109-9",</CodeLine>
  <CodeLine>                  "display": "Note"</CodeLine>
  <CodeLine>                },</CodeLine>
  <CodeLine>                {</CodeLine>
  <CodeLine>                  "system": "https://api.dental4web.com.au/codes/dental-item-codes",</CodeLine>
  <CodeLine>                  "code": "114",</CodeLine>
  <CodeLine>                  "display": "Dental item code"</CodeLine>
  <CodeLine>                }</CodeLine>
  <CodeLine>              ]</CodeLine>
  <CodeLine>            },</CodeLine>
  <CodeLine>            "subject": {"reference": "Patient/2", "display": "Emerie Snyder"},</CodeLine>
  <CodeLine>            "performer": [{"reference": "Practitioner/29", "display": "Dr Blake Castro"}],</CodeLine>
  <CodeLine>            "effectiveDateTime": "2019-12-09",</CodeLine>
  <CodeLine>            "valueString": "Clinical note completed",</CodeLine>
  <CodeLine>            "bodySite": {"text": "48, OB"},</CodeLine>
  <CodeLine>            "meta": {"lastUpdated": "2026-02-12T11:38:14.369000Z"}</CodeLine>
  <CodeLine>          }</CodeLine>
  <CodeLine>        }</CodeLine>
  <CodeLine>      ]</CodeLine>
  <CodeLine>    },</CodeLine>
  <CodeLine>    "pagination": {...}</CodeLine>
  <CodeLine>  }</CodeLine>
</CodeBlock>

Note: The primary coding is the real LOINC clinical-note code. The secondary coding carries the original dental item code from the source system.

Note: FHIR endpoints return `Content-Type: application/json`, not the FHIR-standard `application/fhir+json`. Bundles are wrapped inside the standard Dental API response envelope.

GET Clinical Notes - FHIR

Retrieves practitioners as FHIR R4 `Practitioner` resources. The response is a searchset `Bundle` containing `Practitioner` resources. Parameters and constraints match `GET /practitioners`.

Resource mapping
----------------

<Table style="width:100%;min-width:100%" colSizes='["180px","135px","585px"]' isHeaderAdded='true' tableHeader='[{"id":"76991990-68a2-4a80-ab4e-6766b8c02948","title":"Source field"},{"id":"19ea0a0b-9c0c-4bfe-b16d-53ac1b7b2341","title":"FHIR element"},{"id":"935d8a7c-fbfe-406a-846d-e23fb85976fd","title":"Notes"}]'>
  <table-row>
    <table-cell><p class="slate-p ">Practitioner ID</p></table-cell>
    <table-cell><p class="slate-p "><code class="slate-code">Practitioner.id</code></p></table-cell>
    <table-cell><p class="slate-p ">Source practitioner identifier.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p ">Practitioner code</p></table-cell>
    <table-cell><p class="slate-p "><code class="slate-code">Practitioner.identifier</code></p></table-cell>
    <table-cell><p class="slate-p ">Code under <code class="slate-code">https://api.dental4web.com.au/fhir/codes/practitioner-codes</code>; Medicare provider number under <code class="slate-code">http://ns.electronichealth.net.au/id/medicare-provider-number</code>.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p ">Name</p></table-cell>
    <table-cell><p class="slate-p "><code class="slate-code">Practitioner.name</code></p></table-cell>
    <table-cell><p class="slate-p ">Mapped to <code class="slate-code">text</code>, <code class="slate-code">family</code>, <code class="slate-code">given</code>, and <code class="slate-code">prefix</code>.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p ">Active flag</p></table-cell>
    <table-cell><p class="slate-p "><code class="slate-code">Practitioner.active</code></p></table-cell>
    <table-cell><p class="slate-p ">Whether the practitioner is currently active.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p ">Qualifications</p></table-cell>
    <table-cell><p class="slate-p "><code class="slate-code">Practitioner.qualification</code></p></table-cell>
    <table-cell><p class="slate-p ">Present as an array; may be empty.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p ">Last-modified timestamp</p></table-cell>
    <table-cell><p class="slate-p "><code class="slate-code">Practitioner.meta.lastUpdated</code></p></table-cell>
    <table-cell><p class="slate-p ">Record's last-modified timestamp.</p></table-cell>
  </table-row>
</Table>

Response envelope
------------------

Every response also includes top-level `metadata` and `pagination` objects alongside the FHIR `Bundle` in `data`. See [API response formats](/api-response-formats) for the full field list.

<Table style="width:100%;min-width:100%" colSizes='["180px","135px","585px"]' isHeaderAdded='true' tableHeader='[{"id":"6d1cfad6-a2c4-4abb-9746-0dbcba78fd91","title":"Field"},{"id":"14be76d8-df59-4555-b0f0-0ff0268caedc","title":"Type"},{"id":"bbb509e3-9057-49b1-911a-121aff2a12a6","title":"Description"}]'>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">metadata</code></p></table-cell>
    <table-cell><p class="slate-p ">object</p></table-cell>
    <table-cell><p class="slate-p ">Response envelope metadata. See <a href="/api-response-formats">API response formats</a> for the full field list.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">pagination</code></p></table-cell>
    <table-cell><p class="slate-p ">object</p></table-cell>
    <table-cell><p class="slate-p ">Pagination for the result set. See <a href="/api-response-formats">API response formats</a> for the full field list.</p></table-cell>
  </table-row>
</Table>

Sample bundle
-------------

<CodeBlock attributes='{"isFitToPage":true,"style":{},"lang":"json","label":"JSON"}'>
  <CodeLine></CodeLine>
  <CodeLine>  {</CodeLine>
  <CodeLine>    "status": true,</CodeLine>
  <CodeLine>    "message": "Success",</CodeLine>
  <CodeLine>    "data": {</CodeLine>
  <CodeLine>      "resourceType": "Bundle",</CodeLine>
  <CodeLine>      "id": "uuid",</CodeLine>
  <CodeLine>      "type": "searchset",</CodeLine>
  <CodeLine>      "total": 168,</CodeLine>
  <CodeLine>      "entry": [</CodeLine>
  <CodeLine>        {</CodeLine>
  <CodeLine>          "resource": {</CodeLine>
  <CodeLine>            "resourceType": "Practitioner",</CodeLine>
  <CodeLine>            "id": "1",</CodeLine>
  <CodeLine>            "identifier": [</CodeLine>
  <CodeLine>              {"system": "https://api.dental4web.com.au/fhir/codes/practitioner-codes", "value": "MHA"},</CodeLine>
  <CodeLine>              {"system": "http://ns.electronichealth.net.au/id/medicare-provider-number", "value": "1"}</CodeLine>
  <CodeLine>            ],</CodeLine>
  <CodeLine>            "name": [</CodeLine>
  <CodeLine>              {</CodeLine>
  <CodeLine>                "text": "Dr Marshall Holman",</CodeLine>
  <CodeLine>                "family": "Holman",</CodeLine>
  <CodeLine>                "given": ["Marshall"],</CodeLine>
  <CodeLine>                "prefix": ["Dr"]</CodeLine>
  <CodeLine>              }</CodeLine>
  <CodeLine>            ],</CodeLine>
  <CodeLine>            "active": false,</CodeLine>
  <CodeLine>            "qualification": [],</CodeLine>
  <CodeLine>            "meta": {"lastUpdated": "2026-01-13T12:50:55.135001Z"}</CodeLine>
  <CodeLine>          }</CodeLine>
  <CodeLine>        },</CodeLine>
  <CodeLine>        {"resource": {"resourceType": "Location", ...}}</CodeLine>
  <CodeLine>      ]</CodeLine>
  <CodeLine>    },</CodeLine>
  <CodeLine>    "pagination": {...}</CodeLine>
  <CodeLine>  }</CodeLine>
</CodeBlock>

Note: FHIR endpoints return `Content-Type: application/json`, not the FHIR-standard `application/fhir+json`. Bundles are wrapped inside the standard Dental API response envelope.

GET Practitioners - FHIR

Retrieves practice locations as FHIR R4 `Location` resources. The response is a searchset `Bundle` containing `Location` resources. Parameters and constraints match `GET /locations`.

Resource mapping
----------------

<Table style="width:100%;min-width:100%" colSizes='["180px","135px","585px"]' isHeaderAdded='true' tableHeader='[{"id":"b6ba4ebd-d973-4b8d-8504-a905156ee262","title":"Source field"},{"id":"b412caaf-a7f5-4749-91df-39b256c0ee67","title":"FHIR element"},{"id":"93fc8ae4-6863-49a9-b2f2-3bab123d69ba","title":"Notes"}]'>
  <table-row>
    <table-cell><p class="slate-p ">Location ID</p></table-cell>
    <table-cell><p class="slate-p "><code class="slate-code">Location.id</code></p></table-cell>
    <table-cell><p class="slate-p ">Source location identifier.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p ">Name</p></table-cell>
    <table-cell><p class="slate-p "><code class="slate-code">Location.name</code></p></table-cell>
    <table-cell><p class="slate-p ">Practice location name.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p ">Status</p></table-cell>
    <table-cell><p class="slate-p "><code class="slate-code">Location.status</code></p></table-cell>
    <table-cell><p class="slate-p ">FHIR location status, for example <code class="slate-code">active</code>.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p ">Address</p></table-cell>
    <table-cell><p class="slate-p "><code class="slate-code">Location.address</code></p></table-cell>
    <table-cell><p class="slate-p ">Mapped to <code class="slate-code">text</code> and <code class="slate-code">country</code>.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p ">Phone and email</p></table-cell>
    <table-cell><p class="slate-p "><code class="slate-code">Location.telecom</code></p></table-cell>
    <table-cell><p class="slate-p ">Phone and email entries.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p ">Last-modified timestamp</p></table-cell>
    <table-cell><p class="slate-p "><code class="slate-code">Location.meta.lastUpdated</code></p></table-cell>
    <table-cell><p class="slate-p ">Record's last-modified timestamp.</p></table-cell>
  </table-row>
</Table>

Response envelope
------------------

Every response also includes top-level `metadata` and `pagination` objects alongside the FHIR `Bundle` in `data`. See [API response formats](/api-response-formats) for the full field list.

<Table style="width:100%;min-width:100%" colSizes='["180px","135px","585px"]' isHeaderAdded='true' tableHeader='[{"id":"5a9da733-7748-4130-b4ea-c8ec303bd706","title":"Field"},{"id":"fe52f2d4-ffff-41da-9a04-2546bc15c5b1","title":"Type"},{"id":"0fc27219-dafb-4234-b80c-365efe9bb079","title":"Description"}]'>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">metadata</code></p></table-cell>
    <table-cell><p class="slate-p ">object</p></table-cell>
    <table-cell><p class="slate-p ">Response envelope metadata. See <a href="/api-response-formats">API response formats</a> for the full field list.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">pagination</code></p></table-cell>
    <table-cell><p class="slate-p ">object</p></table-cell>
    <table-cell><p class="slate-p ">Pagination for the result set. See <a href="/api-response-formats">API response formats</a> for the full field list.</p></table-cell>
  </table-row>
</Table>

Sample bundle
-------------

<CodeBlock attributes='{"isFitToPage":true,"style":{},"lang":"json","label":"JSON"}'>
  <CodeLine></CodeLine>
  <CodeLine>  {</CodeLine>
  <CodeLine>      "status": true,</CodeLine>
  <CodeLine>      "message": "Success",</CodeLine>
  <CodeLine>      "data": {</CodeLine>
  <CodeLine>          "resourceType": "Bundle",</CodeLine>
  <CodeLine>          "id": "8777948c-7b12-4c54-ab85-17793b94bbb8",</CodeLine>
  <CodeLine>          "type": "searchset",</CodeLine>
  <CodeLine>          "total": 3,</CodeLine>
  <CodeLine>          "entry": [</CodeLine>
  <CodeLine>              {</CodeLine>
  <CodeLine>                  "resource": {</CodeLine>
  <CodeLine>                      "resourceType": "Location",</CodeLine>
  <CodeLine>                      "id": "1",</CodeLine>
  <CodeLine>                      "name": "Ridiculous Smiles Cbd",</CodeLine>
  <CodeLine>                      "status": "active",</CodeLine>
  <CodeLine>                      "meta": {</CodeLine>
  <CodeLine>                          "lastUpdated": "2025-04-11T12:24:20.074000Z"</CodeLine>
  <CodeLine>                      },</CodeLine>
  <CodeLine>                      "address": {</CodeLine>
  <CodeLine>                          "text": "Level 5 The Plaque Chambers 100 Root Canal Avenue SYDNEY NSW 2000",</CodeLine>
  <CodeLine>                          "country": "Australia"</CodeLine>
  <CodeLine>                      },</CodeLine>
  <CodeLine>                      "telecom": [</CodeLine>
  <CodeLine>                          {</CodeLine>
  <CodeLine>                              "system": "phone",</CodeLine>
  <CodeLine>                              "value": "05 1234 5678"</CodeLine>
  <CodeLine>                          },</CodeLine>
  <CodeLine>                          {</CodeLine>
  <CodeLine>                              "system": "email",</CodeLine>
  <CodeLine>                              "value": "tooth@mccavityandmcplaque.com.au"</CodeLine>
  <CodeLine>                          }</CodeLine>
  <CodeLine>                      ]</CodeLine>
  <CodeLine>                  }</CodeLine>
  <CodeLine>              },</CodeLine>
  <CodeLine>              {</CodeLine>
  <CodeLine>                  "resource": {</CodeLine>
  <CodeLine>                      "resourceType": "Location",</CodeLine>
  <CodeLine>                      "id": "4",</CodeLine>
  <CodeLine>                      "name": "Ridiculous Smiles Randwick",</CodeLine>
  <CodeLine>                      "status": "active",</CodeLine>
  <CodeLine>                      "meta": {</CodeLine>
  <CodeLine>                          "lastUpdated": "2025-04-11T12:25:18.430000Z"</CodeLine>
  <CodeLine>                      },</CodeLine>
  <CodeLine>                      "address": {</CodeLine>
  <CodeLine>                          "text": "Level 5 The Plaque Chambers 100 Root Canal Avenue RANDWICK NSW 2031",</CodeLine>
  <CodeLine>                          "country": "Australia"</CodeLine>
  <CodeLine>                      },</CodeLine>
  <CodeLine>                      "telecom": [</CodeLine>
  <CodeLine>                          {</CodeLine>
  <CodeLine>                              "system": "phone",</CodeLine>
  <CodeLine>                              "value": "05 1234 5678"</CodeLine>
  <CodeLine>                          },</CodeLine>
  <CodeLine>                          {</CodeLine>
  <CodeLine>                              "system": "email",</CodeLine>
  <CodeLine>                              "value": "tooth@mccavityandmcplaque.com.au"</CodeLine>
  <CodeLine>                          }</CodeLine>
  <CodeLine>                      ]</CodeLine>
  <CodeLine>                  }</CodeLine>
  <CodeLine>              },</CodeLine>
  <CodeLine>              {</CodeLine>
  <CodeLine>                  "resource": {</CodeLine>
  <CodeLine>                      "resourceType": "Location",</CodeLine>
  <CodeLine>                      "id": "5",</CodeLine>
  <CodeLine>                      "name": "Ridiculous Smiles Surry Hills",</CodeLine>
  <CodeLine>                      "status": "active",</CodeLine>
  <CodeLine>                      "meta": {</CodeLine>
  <CodeLine>                          "lastUpdated": "2025-04-11T12:26:37.921000Z"</CodeLine>
  <CodeLine>                      },</CodeLine>
  <CodeLine>                      "address": {</CodeLine>
  <CodeLine>                          "text": "Level 5 The Plaque Chambers 100 Root Canal Avenue SURRY HILLS NSW 2010",</CodeLine>
  <CodeLine>                          "country": "Australia"</CodeLine>
  <CodeLine>                      },</CodeLine>
  <CodeLine>                      "telecom": [</CodeLine>
  <CodeLine>                          {</CodeLine>
  <CodeLine>                              "system": "phone",</CodeLine>
  <CodeLine>                              "value": "05 1234 5678"</CodeLine>
  <CodeLine>                          },</CodeLine>
  <CodeLine>                          {</CodeLine>
  <CodeLine>                              "system": "email",</CodeLine>
  <CodeLine>                              "value": "tooth@mccavityandmcplaque.com.au"</CodeLine>
  <CodeLine>                          }</CodeLine>
  <CodeLine>                      ]</CodeLine>
  <CodeLine>                  }</CodeLine>
  <CodeLine>              }</CodeLine>
  <CodeLine>          ],</CodeLine>
  <CodeLine>          "meta": {</CodeLine>
  <CodeLine>              "lastUpdated": "2026-02-18T03:04:47.922629Z"</CodeLine>
  <CodeLine>          }</CodeLine>
  <CodeLine>      },</CodeLine>
  <CodeLine>      "pagination": {</CodeLine>
  <CodeLine>          "page": 1,</CodeLine>
  <CodeLine>          "per_page": 10,</CodeLine>
  <CodeLine>          "total_rows": 3,</CodeLine>
  <CodeLine>          "total_pages": 1</CodeLine>
  <CodeLine>      }</CodeLine>
  <CodeLine>  }</CodeLine>
</CodeBlock>

Note: FHIR endpoints return `Content-Type: application/json`, not the FHIR-standard `application/fhir+json`. Bundles are wrapped inside the standard Dental API response envelope.

GET Locations - FHIR

D4WEB API - Swagger

Dental API (UAT)

apiKey

orgId

Pre-production docs for the Centaur Software Dental API. Use developer.dental4web.com.au for production unless explicitly testing.

Centaur Dental API (UAT) - Pre-Production Documentation

Production

Sandbox

<p class="slate-p " >The Dental API provides secure, programmatic access to dental practice management data. Built for third-party integrators, healthcare platforms, and custom applications, it lets you integrate with practice data while maintaining strict security and privacy controls.</p><h2 class="slate-h2 " >Connectivity beyond the cloud</h2><p class="slate-p " >While designed for Dental4Web (cloud) and MediaWeb PACS, this API is not limited to cloud deployments. Practices running <strong class="slate-bold">Dental4Windows on-premise</strong> can also connect via secure data pipelines provided by <a href="https://haloconnect.io" target="_self">Halo Connect</a>. This gives you a unified API experience regardless of whether your practice data resides in the cloud or on local servers.</p><h2 class="slate-h2 " >What you can do</h2><p class="slate-p " >The API provides read access to core practice data across five resource domains. Write access is available for three core domains.</p><div class="published-table"><div class="table-container" style="padding-left: 0px;"><div class="published-table-header" style="width:100%;min-width:100%;"><div data-column-id="8063fd5f-a16d-4fa3-99ae-00d682bbe6a3" style="width:270px;">Resource domain</div><div data-column-id="e564492f-1455-4dbc-8ef2-fc82e46a7548" style="width:630px;">Description</div></div><table class="slate-table" style="width:900px;min-width:900px;table-layout:fixed;"><colgroup ><col style="width:270px"><col style="width:630px"></colgroup><tbody class="slate-TableElement-tbody"><tr class="slate-tr " ><td class="slate-td" data-column-id="8063fd5f-a16d-4fa3-99ae-00d682bbe6a3"><p class="slate-p " ><strong class="slate-bold">Patient Records</strong></p></td><td class="slate-td" data-column-id="e564492f-1455-4dbc-8ef2-fc82e46a7548"><p class="slate-p " >Read demographics, contact details, health fund information, and recall schedules. Create and update patient records.</p></td></tr><tr class="slate-tr " ><td class="slate-td" data-column-id="8063fd5f-a16d-4fa3-99ae-00d682bbe6a3"><p class="slate-p " ><strong class="slate-bold">Appointments</strong></p></td><td class="slate-td" data-column-id="e564492f-1455-4dbc-8ef2-fc82e46a7548"><p class="slate-p " >Read scheduled, confirmed, cancelled, and attended appointments with full status tracking. Create, update, cancel and reschedule appointments.</p></td></tr><tr class="slate-tr " ><td class="slate-td" data-column-id="8063fd5f-a16d-4fa3-99ae-00d682bbe6a3"><p class="slate-p " ><strong class="slate-bold">Financial Transactions</strong></p></td><td class="slate-td" data-column-id="e564492f-1455-4dbc-8ef2-fc82e46a7548"><p class="slate-p " >Invoices, payments, discounts, refunds, and health fund rebates</p></td></tr><tr class="slate-tr " ><td class="slate-td" data-column-id="8063fd5f-a16d-4fa3-99ae-00d682bbe6a3"><p class="slate-p " ><strong class="slate-bold">Treatments &amp; Clinical</strong></p></td><td class="slate-td" data-column-id="e564492f-1455-4dbc-8ef2-fc82e46a7548"><p class="slate-p " >Read completed treatments, treatment plans, and clinical notes. Create clinical notes.</p></td></tr><tr class="slate-tr " ><td class="slate-td" data-column-id="8063fd5f-a16d-4fa3-99ae-00d682bbe6a3"><p class="slate-p " ><strong class="slate-bold">Dental Imaging</strong></p></td><td class="slate-td" data-column-id="e564492f-1455-4dbc-8ef2-fc82e46a7548"><p class="slate-p " >DICOM images via MediaWeb PACS integration (online deployments only)</p></td></tr></tbody></table></div></div><h2 class="slate-h2 " >Key features</h2><h3 class="slate-h3 " >Multi-organisation access</h3><p class="slate-p " >Access data from multiple dental practices using a single API key. Each request specifies the target organisation via the <code class="slate-code">org-id</code> header, which ensures complete data isolation between organisations.</p><h3 class="slate-h3 " >FHIR R4 support</h3><p class="slate-p " >Selected endpoints support HL7® FHIR® R4 output for healthcare interoperability. Add <code class="slate-code">/fhir/</code> to supported endpoint paths to receive data formatted as FHIR resources. See FHIR Capabilities for details.</p><h3 class="slate-h3 " >Incremental sync</h3><p class="slate-p " >Use the <code class="slate-code">mode=1</code> parameter to filter by modification timestamp instead of business date. This enables efficient delta synchronisation: you fetch only records that have changed since your last sync.</p><h3 class="slate-h3 " >Flexible filtering</h3><p class="slate-p " >All list endpoints support filtering by patient, practitioner, location, and date range. Use the <code class="slate-code">include</code> parameter to embed related resources and reduce API calls.</p><h2 class="slate-h2 " >API access</h2><div class="published-table"><div class="table-container" style="padding-left: 0px;"><div class="published-table-header" style="width:100%;min-width:100%;"><div data-column-id="9200ea78-7f87-426e-af59-ba8fd055418b" style="width:270px;">Title</div><div data-column-id="ef91bc1c-9632-4ce7-b19b-74d161e7b793" style="width:630px;">Details</div></div><table class="slate-table" style="width:900px;min-width:900px;table-layout:fixed;"><colgroup ><col style="width:270px"><col style="width:630px"></colgroup><tbody class="slate-TableElement-tbody"><tr class="slate-tr " ><td class="slate-td" data-column-id="9200ea78-7f87-426e-af59-ba8fd055418b"><p class="slate-p " ><strong class="slate-bold">Base URL</strong></p></td><td class="slate-td" data-column-id="ef91bc1c-9632-4ce7-b19b-74d161e7b793"><p class="slate-p " ><a href="https://api-uat.dental4web.com.au" target="_self"><a href="https://api-uat.dental4web.com.au" target="_self">https://api-uat.dental4web.com.au</a></a></p></td></tr><tr class="slate-tr " ><td class="slate-td" data-column-id="9200ea78-7f87-426e-af59-ba8fd055418b"><p class="slate-p " ><strong class="slate-bold">Protocol</strong></p></td><td class="slate-td" data-column-id="ef91bc1c-9632-4ce7-b19b-74d161e7b793"><p class="slate-p " >HTTPS only (TLS 1.2+)</p></td></tr><tr class="slate-tr " ><td class="slate-td" data-column-id="9200ea78-7f87-426e-af59-ba8fd055418b"><p class="slate-p " ><strong class="slate-bold">Format</strong></p></td><td class="slate-td" data-column-id="ef91bc1c-9632-4ce7-b19b-74d161e7b793"><p class="slate-p " >JSON (with optional FHIR R4 output)</p></td></tr><tr class="slate-tr " ><td class="slate-td" data-column-id="9200ea78-7f87-426e-af59-ba8fd055418b"><p class="slate-p " ><strong class="slate-bold">Authentication</strong></p></td><td class="slate-td" data-column-id="ef91bc1c-9632-4ce7-b19b-74d161e7b793"><p class="slate-p " >API key + organisation ID headers</p></td></tr><tr class="slate-tr " ><td class="slate-td" data-column-id="9200ea78-7f87-426e-af59-ba8fd055418b"><p class="slate-p " ><strong class="slate-bold">Rate Limit</strong></p></td><td class="slate-td" data-column-id="ef91bc1c-9632-4ce7-b19b-74d161e7b793"><p class="slate-p " >10,000 requests per day per integrator, plus per-minute limits: see <a href="/rate-limits" target="_self">Rate limits</a>. Contact us if you need a higher daily limit.</p></td></tr></tbody></table></div></div><h2 class="slate-h2 " >Current capabilities</h2><div class="published-table"><div class="table-container" style="padding-left: 0px;"><div class="published-table-header" style="width:100%;min-width:100%;"><div data-column-id="34fad0e6-67d0-4597-a2d4-772fbbdcbeec" style="width:270px;">Capability</div><div data-column-id="cefb6b77-1e59-4f1d-a2c9-7450aad057ff" style="width:630px;">Status</div></div><table class="slate-table" style="width:900px;min-width:900px;table-layout:fixed;"><colgroup ><col style="width:270px"><col style="width:630px"></colgroup><tbody class="slate-TableElement-tbody"><tr class="slate-tr " ><td class="slate-td" data-column-id="34fad0e6-67d0-4597-a2d4-772fbbdcbeec"><p class="slate-p " >Read patient demographics &amp; recalls</p></td><td class="slate-td" data-column-id="cefb6b77-1e59-4f1d-a2c9-7450aad057ff"><p class="slate-p " >✅ Available</p></td></tr><tr class="slate-tr " ><td class="slate-td" data-column-id="34fad0e6-67d0-4597-a2d4-772fbbdcbeec"><p class="slate-p " >Read patient extended (custom fields)</p></td><td class="slate-td" data-column-id="cefb6b77-1e59-4f1d-a2c9-7450aad057ff"><p class="slate-p " >✅ Available</p></td></tr><tr class="slate-tr " ><td class="slate-td" data-column-id="34fad0e6-67d0-4597-a2d4-772fbbdcbeec"><p class="slate-p " >Write access (patients, appointments and clinical notes)</p></td><td class="slate-td" data-column-id="cefb6b77-1e59-4f1d-a2c9-7450aad057ff"><p class="slate-p " >✅ Available</p></td></tr><tr class="slate-tr " ><td class="slate-td" data-column-id="34fad0e6-67d0-4597-a2d4-772fbbdcbeec"><p class="slate-p " >Read appointments (incl. cancelled)</p></td><td class="slate-td" data-column-id="cefb6b77-1e59-4f1d-a2c9-7450aad057ff"><p class="slate-p " >✅ Available</p></td></tr><tr class="slate-tr " ><td class="slate-td" data-column-id="34fad0e6-67d0-4597-a2d4-772fbbdcbeec"><p class="slate-p " >Find available appointment slots</p></td><td class="slate-td" data-column-id="cefb6b77-1e59-4f1d-a2c9-7450aad057ff"><p class="slate-p " >✅ Available</p></td></tr><tr class="slate-tr " ><td class="slate-td" data-column-id="34fad0e6-67d0-4597-a2d4-772fbbdcbeec"><p class="slate-p " >Read treatments, treatment plans, clinical notes</p></td><td class="slate-td" data-column-id="cefb6b77-1e59-4f1d-a2c9-7450aad057ff"><p class="slate-p " >✅ Available</p></td></tr><tr class="slate-tr " ><td class="slate-td" data-column-id="34fad0e6-67d0-4597-a2d4-772fbbdcbeec"><p class="slate-p " >Read financial transactions &amp; receipts</p></td><td class="slate-td" data-column-id="cefb6b77-1e59-4f1d-a2c9-7450aad057ff"><p class="slate-p " >✅ Available</p></td></tr><tr class="slate-tr " ><td class="slate-td" data-column-id="34fad0e6-67d0-4597-a2d4-772fbbdcbeec"><p class="slate-p " >Read reference data (practitioners, locations, books, items, payment types, classes, cancel reasons, slot types, titles, users, recalls)</p></td><td class="slate-td" data-column-id="cefb6b77-1e59-4f1d-a2c9-7450aad057ff"><p class="slate-p " >✅ Available</p></td></tr><tr class="slate-tr " ><td class="slate-td" data-column-id="34fad0e6-67d0-4597-a2d4-772fbbdcbeec"><p class="slate-p " >Read DICOM images &amp; metadata via MediaWeb PACS</p></td><td class="slate-td" data-column-id="cefb6b77-1e59-4f1d-a2c9-7450aad057ff"><p class="slate-p " >✅ Available</p></td></tr><tr class="slate-tr " ><td class="slate-td" data-column-id="34fad0e6-67d0-4597-a2d4-772fbbdcbeec"><p class="slate-p " >FHIR R4 reads (Patient, Appointment, Practitioner, Location, Observation, Procedure)</p></td><td class="slate-td" data-column-id="cefb6b77-1e59-4f1d-a2c9-7450aad057ff"><p class="slate-p " >✅ Available</p></td></tr><tr class="slate-tr " ><td class="slate-td" data-column-id="34fad0e6-67d0-4597-a2d4-772fbbdcbeec"><p class="slate-p " >Create / update Patient</p></td><td class="slate-td" data-column-id="cefb6b77-1e59-4f1d-a2c9-7450aad057ff"><p class="slate-p " >✅ Available</p></td></tr><tr class="slate-tr " ><td class="slate-td" data-column-id="34fad0e6-67d0-4597-a2d4-772fbbdcbeec"><p class="slate-p " >Create / update Appointment, Cancel, Reschedule</p></td><td class="slate-td" data-column-id="cefb6b77-1e59-4f1d-a2c9-7450aad057ff"><p class="slate-p " >✅ Available</p></td></tr><tr class="slate-tr " ><td class="slate-td" data-column-id="34fad0e6-67d0-4597-a2d4-772fbbdcbeec"><p class="slate-p " >Create Clinical Note</p></td><td class="slate-td" data-column-id="cefb6b77-1e59-4f1d-a2c9-7450aad057ff"><p class="slate-p " >✅ Available</p></td></tr><tr class="slate-tr " ><td class="slate-td" data-column-id="34fad0e6-67d0-4597-a2d4-772fbbdcbeec"><p class="slate-p " >OAuth 2.0 authentication and authorisation</p></td><td class="slate-td" data-column-id="cefb6b77-1e59-4f1d-a2c9-7450aad057ff"><p class="slate-p " >🔜 Planned for future releases</p></td></tr><tr class="slate-tr " ><td class="slate-td" data-column-id="34fad0e6-67d0-4597-a2d4-772fbbdcbeec"><p class="slate-p " >Webhook notifications</p></td><td class="slate-td" data-column-id="cefb6b77-1e59-4f1d-a2c9-7450aad057ff"><p class="slate-p " >🔜 Planned for future releases</p></td></tr></tbody></table></div></div><h2 class="slate-h2 " >Prerequisites</h2><p class="slate-p " >Before integrating with the Dental API, you should have:</p><ul class="slate-ul " ><li class="slate-li " ><div style="position:relative"><strong class="slate-bold">Technical knowledge</strong>: Understanding of REST APIs, HTTP methods, and JSON format</div></li><li class="slate-li " ><div style="position:relative"><strong class="slate-bold">Healthcare context</strong>: Familiarity with dental practice workflows and healthcare data standards</div></li><li class="slate-li " ><div style="position:relative"><strong class="slate-bold">Credentials</strong>: A valid API key and organisation ID(s) from Centaur Software</div></li></ul><h2 class="slate-h2 " >Getting help</h2><ul class="slate-ul " ><li class="slate-li " ><div style="position:relative"><strong class="slate-bold">Integration support</strong>: Contact <a href="mailto:dentalapi@centaursoftware.com" target="_self">Centaur Software</a> for API access and integration assistance</div></li><li class="slate-li " ><div style="position:relative"><strong class="slate-bold">Documentation feedback</strong>: Report issues or suggest improvements via<a href="mailto:dentalapi@centaursoftware.com" target="_self">dentalapi@centaursoftware.com</a></div></li></ul><h2 class="slate-h2 " >Quick links</h2><div class="published-table"><div class="table-container" style="padding-left: 0px;"><div class="published-table-header" style="width:100%;min-width:100%;"><div data-column-id="2cd77fdc-0a8d-4b2f-95da-01f17765f604" style="width:270px;">I want to...</div><div data-column-id="40b3976a-bded-4476-86b2-cdbbee13fdc6" style="width:630px;">Go to...</div></div><table class="slate-table" style="width:900px;min-width:900px;table-layout:fixed;"><colgroup ><col style="width:270px"><col style="width:630px"></colgroup><tbody class="slate-TableElement-tbody"><tr class="slate-tr " ><td class="slate-td" data-column-id="2cd77fdc-0a8d-4b2f-95da-01f17765f604"><p class="slate-p " >Set up authentication</p></td><td class="slate-td" data-column-id="40b3976a-bded-4476-86b2-cdbbee13fdc6"><p class="slate-p " ><a href="/getting-started" target="_self">Getting Started</a></p></td></tr><tr class="slate-tr " ><td class="slate-td" data-column-id="2cd77fdc-0a8d-4b2f-95da-01f17765f604"><p class="slate-p " >Understand the response format</p></td><td class="slate-td" data-column-id="40b3976a-bded-4476-86b2-cdbbee13fdc6"><p class="slate-p " ><a href="/api-response-formats" target="_self">API Response Formats</a></p></td></tr><tr class="slate-tr " ><td class="slate-td" data-column-id="2cd77fdc-0a8d-4b2f-95da-01f17765f604"><p class="slate-p " >Find the right endpoint for my use case</p></td><td class="slate-td" data-column-id="40b3976a-bded-4476-86b2-cdbbee13fdc6"><p class="slate-p " ><a href="/find-your-use-case" target="_self">Find Your Use Case</a></p></td></tr><tr class="slate-tr " ><td class="slate-td" data-column-id="2cd77fdc-0a8d-4b2f-95da-01f17765f604"><p class="slate-p " >Learn about FHIR support</p></td><td class="slate-td" data-column-id="40b3976a-bded-4476-86b2-cdbbee13fdc6"><p class="slate-p " ><a href="/fhir-capabilities" target="_self">FHIR Capabilities</a></p></td></tr><tr class="slate-tr " ><td class="slate-td" data-column-id="2cd77fdc-0a8d-4b2f-95da-01f17765f604"><p class="slate-p " >See all available endpoints</p></td><td class="slate-td" data-column-id="40b3976a-bded-4476-86b2-cdbbee13fdc6"><p class="slate-p " ><a href="/appointment-resources" target="_self">Appointment Resources</a>, <a href="/patient-resources" target="_self">Patient Resources</a>, <a href="/financial-resources" target="_self">Financial Resources</a>, <a href="/treatment-and-clinical-resources" target="_self">Treatment Resources</a>, <a href="/reference-data-resources" target="_self">Reference Data</a></p></td></tr></tbody></table></div></div><p class="slate-p " ></p>

The Dental API provides secure, programmatic access to dental practice management data. Built for third-party integrators, healthcare platforms, and custom applications, it lets you integrate with practice data while maintaining strict security and privacy controls.

While designed for Dental4Web (cloud) and MediaWeb PACS, this API is not limited to cloud deployments. Practices running 

 can also connect via secure data pipelines provided by 

. This gives you a unified API experience regardless of whether your practice data resides in the cloud or on local servers.

The API provides read access to core practice data across five resource domains. Write access is available for three core domains.

Resource domain

Description

Access data from multiple dental practices using a single API key. Each request specifies the target organisation via the 

 header, which ensures complete data isolation between organisations.

Selected endpoints support HL7® FHIR® R4 output for healthcare interoperability. Add 

 to supported endpoint paths to receive data formatted as FHIR resources. See FHIR Capabilities for details.

 parameter to filter by modification timestamp instead of business date. This enables efficient delta synchronisation: you fetch only records that have changed since your last sync.

All list endpoints support filtering by patient, practitioner, location, and date range. Use the 

 parameter to embed related resources and reduce API calls.

Title

Details

Capability

Status

Before integrating with the Dental API, you should have:

I want to...

Go to...

The Dental API provides secure, programmatic access to dental practice management data. Built for third-party integrators, healthcare platforms, and…

<div class="steps-widget" style="width:100%;
  	min-width:100%;"><div class="steps-wrapper"><div class="steps-content"><h6 class="slate-h6 " >1</h6><h3 class="slate-h3 " >Obtain credentials</h3><p class="slate-p " ><span class="slate-color" style="background-color:transparent;color:#434343">To gain API access, an integrator must contact </span><a href="mailto:dentalapi@centaursoftware.com" target="_self">Centaur Software</a><span class="slate-color" style="background-color:transparent;color:#434343"> to set up an integration account. This request should state the intended use case, the scope of required data, and the organisation(s) for which access is being sought.</span></p><p class="slate-p " ><span class="slate-color" style="background-color:transparent;color:#434343">Once the account is created, the integrator will be provided with an API key and given access to Dental4Web/Dental4Windows organisations. E</span>very request must carry an <code class="slate-code">org-id</code> header identifying the organisation<span class="slate-color" style="background-color:transparent;color:#434343">.</span></p></div></div><div class="steps-wrapper"><div class="steps-content"><h6 class="slate-h6 " >2</h6><h3 class="slate-h3 " >Add authentication</h3><p class="slate-p " ><span class="slate-color" style="background-color:transparent;color:#434343">All HTTP requests should include the following headers. </span><span class="slate-color" style="background-color:transparent;color:#434343"><code class="slate-code" style="color:#434343">x-api-key</code></span><span class="slate-color" style="background-color:transparent;color:#434343"> and </span><span class="slate-color" style="background-color:transparent;color:#434343"><code class="slate-code" style="color:#434343">org-id</code></span><span class="slate-color" style="background-color:transparent;color:#434343"> are required; </span><span class="slate-color" style="background-color:transparent;color:#434343"><code class="slate-code" style="color:#434343">Accept</code></span><span class="slate-color" style="background-color:transparent;color:#434343"> is recommended but not currently enforced:</span></p><ul class="slate-ul " ><li class="slate-li " ><div style="position:relative">x-api-key</div></li></ul><p class="slate-p " ><span class="slate-color" style="background-color:transparent;color:#434343"><em class="slate-italic">This is the integrator’s API key.</em></span></p><ul class="slate-ul " ><li class="slate-li " ><div style="position:relative">org-id</div></li></ul><p class="slate-p " ><span class="slate-color" style="background-color:transparent;color:#434343">The organisation ID identifies a specific organisation within Dental4Web/Dental4Windows. Note that an integrator&apos;s API key can be used to access multiple organisations, so both the organisation ID and the API key are required for all requests.</span></p><p class="slate-p " ><span class="slate-color" style="background-color:transparent;color:#434343">The API token grants access only to the data of the mapped org-id. Any attempt to retrieve information for an organisation other than the current one will be rejected by the API.</span></p><ul class="slate-ul " ><li class="slate-li " ><div style="position:relative">Accept: application/json</div></li></ul><p class="slate-p " ><span class="slate-color" style="background-color:transparent;color:#434343"><em class="slate-italic">Recommended, not required. All responses are JSON regardless of this header; sending </em></span><span class="slate-color" style="background-color:transparent;color:#434343"><em class="slate-italic"><code class="slate-code" style="color:#434343">Accept: application/json</code></em></span><span class="slate-color" style="background-color:transparent;color:#434343"><em class="slate-italic"> is recommended for forward compatibility, but it is not currently enforced: requests without it, or with a different value, still succeed.</em></span></p></div></div><div class="steps-wrapper"><div class="steps-content"><h6 class="slate-h6 " >3</h6><h3 class="slate-h3 " >Try it out</h3><p class="slate-p " ><span class="slate-color" style="background-color:transparent;color:#434343">Once you have all the required details, you can test your connection using the curl example below.</span></p><div class="code-block-wrapper"  style="width:100%" ><div class="code-block-header">Plain text</div><pre class="slate-CodeBlockElement slate-code_block"><textarea id="publishedPageCodeblock" style="display:none !important; visibility: hidden; opacity: 0; width: 1px; height: 1px;" type="hidden">curl -X GET &quot;https://api-uat.dental4web.com.au/api/v1/practitioners&quot; \
        -H &quot;org-id: YOUR_ORG_ID&quot; \
        -H &quot;x-api-key: YOUR_API_KEY&quot; \
        -H &quot;Accept: application/json&quot; </textarea><code class="language-plainText keep-markup drop-tokens">curl -X GET &quot;https://api-uat.dental4web.com.au/api/v1/practitioners&quot; \
        -H &quot;org-id: YOUR_ORG_ID&quot; \
        -H &quot;x-api-key: YOUR_API_KEY&quot; \
        -H &quot;Accept: application/json&quot; </code></pre></div></div></div></div><h3 class="slate-h3 " >Troubleshooting your first call</h3><div class="published-table"><div class="table-container" style="padding-left: 0px;"><div class="published-table-header" style="width:100%;min-width:100%;"><div data-column-id="b4ff02d6-c8c5-4302-963d-c80c4e0f5a30" style="width:180px;">Error</div><div data-column-id="61de544a-d3f1-4097-bcc4-42562b618305" style="width:135px;">Cause</div><div data-column-id="071a0c42-ff7f-41ba-b29c-4f7ee5ac4323" style="width:585px;">Fix</div></div><table class="slate-table" style="width:900px;min-width:900px;table-layout:fixed;"><colgroup ><col style="width:180px"><col style="width:135px"><col style="width:585px"></colgroup><tbody class="slate-TableElement-tbody"><tr class="slate-tr " ><td class="slate-td" data-column-id="b4ff02d6-c8c5-4302-963d-c80c4e0f5a30"><p class="slate-p " >HTTP 403</p></td><td class="slate-td" data-column-id="61de544a-d3f1-4097-bcc4-42562b618305"><p class="slate-p " >Missing or invalid <code class="slate-code">x-api-key</code> header</p></td><td class="slate-td" data-column-id="071a0c42-ff7f-41ba-b29c-4f7ee5ac4323"><p class="slate-p " >Check the header is present and the key matches Sandbox</p></td></tr><tr class="slate-tr " ><td class="slate-td" data-column-id="b4ff02d6-c8c5-4302-963d-c80c4e0f5a30"><p class="slate-p " >HTTP 400 &quot;Missing Organisation ID&quot;</p></td><td class="slate-td" data-column-id="61de544a-d3f1-4097-bcc4-42562b618305"><p class="slate-p " >Missing <code class="slate-code">org-id</code> header</p></td><td class="slate-td" data-column-id="071a0c42-ff7f-41ba-b29c-4f7ee5ac4323"><p class="slate-p " >Add <code class="slate-code">org-id: Sandbox</code></p></td></tr><tr class="slate-tr " ><td class="slate-td" data-column-id="b4ff02d6-c8c5-4302-963d-c80c4e0f5a30"><p class="slate-p " >HTTP 400</p></td><td class="slate-td" data-column-id="61de544a-d3f1-4097-bcc4-42562b618305"><p class="slate-p " >API key valid but not authorised for this organisation</p></td><td class="slate-td" data-column-id="071a0c42-ff7f-41ba-b29c-4f7ee5ac4323"><p class="slate-p " >Contact <a href="mailto:dentalapi@centaursoftware.com" target="_self">Centaur Software</a> to map your key to the org</p></td></tr><tr class="slate-tr " ><td class="slate-td" data-column-id="b4ff02d6-c8c5-4302-963d-c80c4e0f5a30"><p class="slate-p " >HTTP 429</p></td><td class="slate-td" data-column-id="61de544a-d3f1-4097-bcc4-42562b618305"><p class="slate-p " >Rate limit exceeded</p></td><td class="slate-td" data-column-id="071a0c42-ff7f-41ba-b29c-4f7ee5ac4323"><p class="slate-p " >Wait the seconds indicated in <code class="slate-code">retry_after_seconds</code> (per-integrator limit, hit first in most cases) or <code class="slate-code">retry_after</code> (per-organisation limit) and try again. Check <code class="slate-code">support_code</code> to tell which layer applied. See <a href="/rate-limits" target="_self">Rate Limits</a>.</p></td></tr><tr class="slate-tr " ><td class="slate-td" data-column-id="b4ff02d6-c8c5-4302-963d-c80c4e0f5a30"><p class="slate-p " >Timeout</p></td><td class="slate-td" data-column-id="61de544a-d3f1-4097-bcc4-42562b618305"><p class="slate-p " >Slow connection or a temporary service slowdown</p></td><td class="slate-td" data-column-id="071a0c42-ff7f-41ba-b29c-4f7ee5ac4323"><p class="slate-p " >Increase client timeout to 60 s and retry</p></td></tr></tbody></table></div></div>

Error

Cause

1 Obtain credentials To gain API access, an integrator must contact Centaur Software to set up an integration account. This request should state the…

<p class="slate-p " >This page tracks customer-facing changes to the Dental API: new endpoints, new parameters, new response fields, and changes to existing behaviour. Entries are grouped by version, newest first. The version number for each entry is the Dental API data model version; use <a href="/admin-resources/get-data-model-version" target="_self">GET Data Model Version</a> to check which version an organisation is currently running.</p><h2 class="slate-h2 " >V18</h2><h3 class="slate-h3 " >Added</h3><ul class="slate-ul " ><li class="slate-li " ><div style="position:relative"><strong class="slate-bold">GET Patients Lite</strong>: a lightweight, multi-field patient search returning up to 7 core fields, for when you don’t need the full patient record.</div></li></ul><h3 class="slate-h3 " >Updated</h3><ul class="slate-ul " ><li class="slate-li " ><div style="position:relative"><strong class="slate-bold">GET Patient Extended By ID</strong>: added a <code class="slate-code">patient_category</code> field, the practice-defined category name for the patient. Not the same thing as <code class="slate-code">patient_status</code>: a patient can carry any category regardless of active/inactive status.</div></li><li class="slate-li " ><div style="position:relative"><strong class="slate-bold">GET Appointment Slots</strong>: <code class="slate-code">slotmode</code> now supports two additional modes (all-presets-only, online-presets-only), and slot rows now include a <code class="slate-code">slot_type_id</code> field linking back to GET Slot Types.</div></li></ul><h2 class="slate-h2 " >V17</h2><h3 class="slate-h3 " >Added</h3><ul class="slate-ul " ><li class="slate-li " ><div style="position:relative"><strong class="slate-bold">GET Appointments</strong>: new <code class="slate-code">deleted</code> parameter to include deleted appointments in results (off by default), with a new <code class="slate-code">is_deleted</code> field on each row.</div></li></ul><h3 class="slate-h3 " >Updated</h3><ul class="slate-ul " ><li class="slate-li " ><div style="position:relative"><strong class="slate-bold">GET Debtors</strong>: added <code class="slate-code">has_line_items</code>, so you can tell upfront whether a debtor row has itemised detail available via GET Invoice Details before calling it.</div></li></ul><h2 class="slate-h2 " >V16</h2><h3 class="slate-h3 " >Added</h3><ul class="slate-ul " ><li class="slate-li " ><div style="position:relative"><strong class="slate-bold">GET Third Parties</strong>: list of configured third-party payer accounts (health funds and other external payers).</div></li><li class="slate-li " ><div style="position:relative"><strong class="slate-bold">GET Debtors</strong>: practice-wide outstanding-debtor list.</div></li><li class="slate-li " ><div style="position:relative"><strong class="slate-bold">GET Patient Balance</strong>: per-patient outstanding balance summary.</div></li><li class="slate-li " ><div style="position:relative"><strong class="slate-bold">GET Invoice Details</strong>: itemised line-item detail for a single invoice.</div></li></ul><h3 class="slate-h3 " >Updated</h3><ul class="slate-ul " ><li class="slate-li " ><div style="position:relative"><strong class="slate-bold">GET Financials</strong>: added a <code class="slate-code">trans_type</code> filter (invoice, discount, refund, payment) and corrected several edge cases in how deposits and mixed health-fund/patient payments were split.</div></li><li class="slate-li " ><div style="position:relative"><strong class="slate-bold">GET Receipts</strong>: added an <code class="slate-code">is_insurance</code> flag on each payment line.</div></li></ul><h2 class="slate-h2 " >V15</h2><h3 class="slate-h3 " >Fixed</h3><ul class="slate-ul " ><li class="slate-li " ><div style="position:relative"><strong class="slate-bold">GET Financials</strong>: corrected patient filtering on shared receipts, so payments now return correctly for a given patient regardless of whether the receipt is sole or shared with a family member.</div></li></ul><h3 class="slate-h3 " >Updated</h3><ul class="slate-ul " ><li class="slate-li " ><div style="position:relative"><strong class="slate-bold">GET Cancelled Appointments</strong>: added a <code class="slate-code">cancel_reason_id</code> field.</div></li><li class="slate-li " ><div style="position:relative"><strong class="slate-bold">GET Items</strong> and <strong class="slate-bold">GET Users</strong>: minor field-naming corrections for consistency (<code class="slate-code">ada_code</code>, <code class="slate-code">first_name</code>).</div></li></ul><h2 class="slate-h2 " >V14</h2><p class="slate-p " >No public-facing changes. This version optimised internal logic for speed improvements.</p><h2 class="slate-h2 " >V13</h2><h3 class="slate-h3 " >Fixed</h3><ul class="slate-ul " ><li class="slate-li " ><div style="position:relative"><strong class="slate-bold">POST Appointment (update)</strong>: guarded against a data-integrity edge case that could otherwise silently corrupt an appointment record.</div></li><li class="slate-li " ><div style="position:relative"><strong class="slate-bold">POST Appointment Cancel</strong>: now correctly rejects cancelling an appointment that’s already been marked as attended.</div></li></ul><h3 class="slate-h3 " >Breaking changes</h3><ul class="slate-ul " ><li class="slate-li " ><div style="position:relative"><strong class="slate-bold">GET Patients, GET Patients Extended</strong>: the date-of-birth filter parameter was renamed from <code class="slate-code">dob</code> to <code class="slate-code">date_of_birth</code> for consistency with patient create/update.</div></li></ul><h2 class="slate-h2 " >V12</h2><h3 class="slate-h3 " >Added</h3><ul class="slate-ul " ><li class="slate-li " ><div style="position:relative">Write access: create, update, cancel and reschedule appointments.</div></li><li class="slate-li " ><div style="position:relative">Create and update patients.</div></li><li class="slate-li " ><div style="position:relative">Find available appointment slots.</div></li><li class="slate-li " ><div style="position:relative">New reference-data endpoints: cancellation reasons, appointment classes, slot types, and patient titles.</div></li></ul><h2 class="slate-h2 " >V11</h2><h3 class="slate-h3 " >Fixed</h3><ul class="slate-ul " ><li class="slate-li " ><div style="position:relative"><strong class="slate-bold">GET Cancelled Appointments</strong>: fixed date-window filtering so it correctly matches on appointment date or cancellation date depending on the <code class="slate-code">mode</code> parameter.</div></li></ul><h3 class="slate-h3 " >Added</h3><ul class="slate-ul " ><li class="slate-li " ><div style="position:relative"><strong class="slate-bold">GET Patients, GET Patients Extended</strong>: added an exact date-of-birth filter.</div></li></ul><h2 class="slate-h2 " >V10</h2><h3 class="slate-h3 " >Updated</h3><ul class="slate-ul " ><li class="slate-li " ><div style="position:relative"><strong class="slate-bold">GET Locations</strong>: added address, phone and email fields, and improved FHIR compatibility.</div></li></ul><h2 class="slate-h2 " >V9</h2><h3 class="slate-h3 " >Fixed</h3><ul class="slate-ul " ><li class="slate-li " ><div style="position:relative"><strong class="slate-bold">GET Patients, GET Patients Extended</strong>: mobile number search is now space-insensitive (matches regardless of how the number is formatted).</div></li></ul><h2 class="slate-h2 " >V8</h2><h3 class="slate-h3 " >Added</h3><ul class="slate-ul " ><li class="slate-li " ><div style="position:relative"><strong class="slate-bold">GET Patients, GET Patients Extended</strong>: added email and mobile number search filters, and support for delta/incremental sync by modification timestamp.</div></li></ul><h2 class="slate-h2 " >V7</h2><h3 class="slate-h3 " >Added</h3><ul class="slate-ul " ><li class="slate-li " ><div style="position:relative"><strong class="slate-bold">GET Patients Extended</strong>: new endpoint providing extended patient information: family role, ethnicity, work address, communication preferences, and custom fields.</div></li><li class="slate-li " ><div style="position:relative"><strong class="slate-bold">GET Appointment Books, GET Users, GET Practitioners</strong>: added a location filter.</div></li></ul><h2 class="slate-h2 " >V1 to V6, initial release</h2><p class="slate-p " >Initial launch of the Dental API’s read-only endpoint surface, covering patients, appointments, treatments, and reference data.</p>

This page tracks customer-facing changes to the Dental API: new endpoints, new parameters, new response fields, and changes to existing behaviour. Entries are grouped by version, newest first. The version number for each entry is the Dental API data model version; use 

 to check which version an organisation is currently running.

No public-facing changes. This version optimised internal logic for speed improvements.

Initial launch of the Dental API’s read-only endpoint surface, covering patients, appointments, treatments, and reference data.

This page tracks customer-facing changes to the Dental API: new endpoints, new parameters, new response fields, and changes to existing behaviour.…

<p class="slate-p " >All requests to Dental API require authentication via API keys. Authentication credentials are provided when your integration account is created by Centaur Software.</p><h2 class="slate-h2 " >Required headers</h2><p class="slate-p " >Every API request should include these headers.</p><p class="slate-p " >x-api-key</p><p class="slate-p " >and</p><p class="slate-p " >org-id</p><p class="slate-p " >are required;</p><p class="slate-p " >Accept</p><p class="slate-p " >is recommended but not currently enforced:</p><div class="published-table"><div class="table-container" style="padding-left: 0px;"><div class="published-table-header" style="width:100%;min-width:100%;"><div data-column-id="fc4278ce-8082-4542-ae52-12e51efac4ea" style="width:180px;">Header</div><div data-column-id="7af9b7b5-b390-43d6-9a99-326bcbc02d4b" style="width:135px;">Value</div><div data-column-id="cda80c46-25c8-4b40-a9b4-de3868a69caf" style="width:585px;">Description</div></div><table class="slate-table" style="width:900px;min-width:900px;table-layout:fixed;"><colgroup ><col style="width:180px"><col style="width:135px"><col style="width:585px"></colgroup><tbody class="slate-TableElement-tbody"><tr class="slate-tr " ><td class="slate-td" data-column-id="fc4278ce-8082-4542-ae52-12e51efac4ea"><p class="slate-p " ><span class="slate-color" style="color:#434343"><code class="slate-code" style="color:#434343">x-api-key</code></span></p></td><td class="slate-td" data-column-id="7af9b7b5-b390-43d6-9a99-326bcbc02d4b"><p class="slate-p " >Your API key</p></td><td class="slate-td" data-column-id="cda80c46-25c8-4b40-a9b4-de3868a69caf"><p class="slate-p " >Authenticates the integrator. Provided by Centaur Software during account setup.</p></td></tr><tr class="slate-tr " ><td class="slate-td" data-column-id="fc4278ce-8082-4542-ae52-12e51efac4ea"><p class="slate-p " ><span class="slate-color" style="color:#434343"><code class="slate-code" style="color:#434343">org-id</code></span></p></td><td class="slate-td" data-column-id="7af9b7b5-b390-43d6-9a99-326bcbc02d4b"><p class="slate-p " >Organisation ID</p></td><td class="slate-td" data-column-id="cda80c46-25c8-4b40-a9b4-de3868a69caf"><p class="slate-p " >Identifies which Dental4Web/Dental4Windows organisation to access. A single API key can be mapped to multiple organisations.</p></td></tr><tr class="slate-tr " ><td class="slate-td" data-column-id="fc4278ce-8082-4542-ae52-12e51efac4ea"><p class="slate-p " ><code class="slate-code">Accept</code></p></td><td class="slate-td" data-column-id="7af9b7b5-b390-43d6-9a99-326bcbc02d4b"><p class="slate-p " ><code class="slate-code">application/json</code></p></td><td class="slate-td" data-column-id="cda80c46-25c8-4b40-a9b4-de3868a69caf"><p class="slate-p " >All responses are JSON regardless of this header. Sending it is recommended for forward compatibility, but it is not currently enforced: requests without it, or with a different value, still succeed.</p></td></tr></tbody></table></div></div><h2 class="slate-h2 " >Multi-organisation model</h2><p class="slate-p " >Dental API isolates each organisation’s data, so a single API key can be authorised for several organisations without their data ever mixing:</p><ul class="slate-ul " ><li class="slate-li " ><div style="position:relative"><strong class="slate-bold">One API key, multiple organisations</strong>: A single integrator API key can be authorised to access data from multiple dental practices.</div></li><li class="slate-li " ><div style="position:relative"><strong class="slate-bold">Organisation isolation</strong>: The <code class="slate-code">org-id</code> header in each request determines which organisation’s data is returned. The API strictly enforces organisation isolation; you cannot access data for an organisation your key isn’t mapped to.</div></li><li class="slate-li " ><div style="position:relative"><strong class="slate-bold">Request scoping</strong>: All data returned is scoped to the specified organisation only.</div></li></ul><h2 class="slate-h2 " >Sandbox environment</h2><p class="slate-p " >A sandbox environment is available for development and testing:</p><ul class="slate-ul " ><li class="slate-li " ><div style="position:relative"><strong class="slate-bold">Sandbox org-id</strong>: Use <code class="slate-code">Sandbox</code> as your <code class="slate-code">org-id</code> value to route requests to the sandbox environment</div></li><li class="slate-li " ><div style="position:relative"><strong class="slate-bold">Like-for-like</strong>: The sandbox environment mirrors production functionality (endpoints, response shapes, business rules). Rate limiting is the one exception: Sandbox currently runs with an elevated per-organisation override for test traffic, so it does not represent production rate-limit thresholds. See <a href="/rate-limits" target="_self">Rate Limits</a> for details</div></li><li class="slate-li " ><div style="position:relative"><strong class="slate-bold">Test data</strong>: Contains realistic sample patient, appointment, and treatment records</div></li><li class="slate-li " ><div style="position:relative"><strong class="slate-bold">Safe testing</strong>: Ideal for developing and testing integrations before switching to production credentials</div></li></ul><h3 class="slate-h3 " >Example sandbox request</h3><div class="code-block-wrapper"  style="width:100%" ><div class="code-block-header">Plain text</div><pre class="slate-CodeBlockElement slate-code_block"><textarea id="publishedPageCodeblock" style="display:none !important; visibility: hidden; opacity: 0; width: 1px; height: 1px;" type="hidden">curl -X GET &quot;https://api-uat.dental4web.com.au/api/v1/practitioners&quot; \
        -H &quot;org-id: Sandbox&quot; \
        -H &quot;x-api-key: YOUR_API_KEY&quot; \
        -H &quot;Accept: application/json&quot; </textarea><code class="language-plainText keep-markup drop-tokens">curl -X GET &quot;https://api-uat.dental4web.com.au/api/v1/practitioners&quot; \
        -H &quot;org-id: Sandbox&quot; \
        -H &quot;x-api-key: YOUR_API_KEY&quot; \
        -H &quot;Accept: application/json&quot; </code></pre></div><h2 class="slate-h2 " >Security best practices</h2><ul class="slate-ul " ><li class="slate-li " ><div style="position:relative"><strong class="slate-bold">Keep credentials confidential</strong>: Never embed API keys in client-side code, mobile apps, or public repositories</div></li><li class="slate-li " ><div style="position:relative"><strong class="slate-bold">Use HTTPS only</strong>: All API traffic must use HTTPS. HTTP requests will be rejected</div></li><li class="slate-li " ><div style="position:relative"><strong class="slate-bold">Rotate keys periodically</strong>: Contact <a href="mailto:dentalapi@centaursoftware.com" target="_self">Centaur Software</a> to rotate API keys if you suspect a compromise</div></li><li class="slate-li " ><div style="position:relative"><strong class="slate-bold">Minimal scope</strong>: Request access only to the organisations you need</div></li></ul><h2 class="slate-h2 " >API key lifecycle</h2><ul class="slate-ul " ><li class="slate-li " ><div style="position:relative">Keys do not expire on a fixed schedule. They remain valid until revoked.</div></li><li class="slate-li " ><div style="position:relative"><strong class="slate-bold">Rotation</strong>: contact <a href="mailto:dentalapi@centaursoftware.com" target="_self">Centaur Software</a> to issue a new key. The old key remains valid for 24 hours after rotation.</div></li><li class="slate-li " ><div style="position:relative"><strong class="slate-bold">Revocation</strong>: keys can be revoked immediately on request. Revoked keys return HTTP 403 on the next request (see Authentication errors below).</div></li><li class="slate-li " ><div style="position:relative"><strong class="slate-bold">Storage</strong>: store keys in environment variables or a secrets manager. Never commit them to source control.</div></li></ul><h2 class="slate-h2 " >Authentication errors</h2><div class="published-table"><div class="table-container" style="padding-left: 0px;"><div class="published-table-header" style="width:100%;min-width:100%;"><div data-column-id="de96ca6a-19eb-4bfd-b03e-228cc577818a" style="width:270px;">Status code</div><div data-column-id="c1d73d56-c5c6-488b-a6e9-429d85c71242" style="width:630px;">Meaning</div><div data-column-id="a7150c3d-c816-42f5-a963-c3d6942f4c33" style="width:initial;">What to check</div></div><table class="slate-table" style="min-width:100%;"><colgroup ><col style="width:270px"><col style="width:630px"><col style="width:initial"></colgroup><tbody class="slate-TableElement-tbody"><tr class="slate-tr " ><td class="slate-td" data-column-id="de96ca6a-19eb-4bfd-b03e-228cc577818a"><p class="slate-p " >403 Forbidden</p></td><td class="slate-td" data-column-id="c1d73d56-c5c6-488b-a6e9-429d85c71242"><p class="slate-p " >Your <code class="slate-code">x-api-key</code> is missing or invalid</p></td><td class="slate-td" data-column-id="a7150c3d-c816-42f5-a963-c3d6942f4c33"><p class="slate-p " >Confirmed live: the response body is the literal <code class="slate-code">{&quot;message&quot;:&quot;Forbidden&quot;}</code>. Unlike other Dental API errors, it does not use the usual <code class="slate-code">status</code>/<code class="slate-code">message</code>/<code class="slate-code">data</code> shape. Verify the API key value is correct and has not been revoked</p></td></tr><tr class="slate-tr " ><td class="slate-td" data-column-id="de96ca6a-19eb-4bfd-b03e-228cc577818a"><p class="slate-p " >400 Bad Request</p></td><td class="slate-td" data-column-id="c1d73d56-c5c6-488b-a6e9-429d85c71242"><p class="slate-p " >Your API key does not have access to the specified <code class="slate-code">org-id</code></p></td><td class="slate-td" data-column-id="a7150c3d-c816-42f5-a963-c3d6942f4c33"><p class="slate-p " >Confirmed live: <code class="slate-code">{&quot;data&quot;:[],&quot;status&quot;:false,&quot;message&quot;:&quot;Given Organisation &lt;org&gt; is not associated with provided token.&quot;}</code>. Confirm your key is mapped to this organisation. Contact <a href="mailto:dentalapi@centaursoftware.com" target="_self">Centaur Software</a> if needed</p></td></tr></tbody></table></div></div><h2 class="slate-h2 " >Example request</h2><div class="code-block-wrapper"  style="width:100%" ><div class="code-block-header">Plain text</div><pre class="slate-CodeBlockElement slate-code_block"><textarea id="publishedPageCodeblock" style="display:none !important; visibility: hidden; opacity: 0; width: 1px; height: 1px;" type="hidden">curl -X GET &quot;https://api-uat.dental4web.com.au/api/v1/patients?patient_id=12345&quot; \
        -H &quot;org-id: YOUR_ORG_ID&quot; \
        -H &quot;x-api-key: YOUR_API_KEY&quot; \
        -H &quot;Accept: application/json&quot; </textarea><code class="language-plainText keep-markup drop-tokens">curl -X GET &quot;https://api-uat.dental4web.com.au/api/v1/patients?patient_id=12345&quot; \
        -H &quot;org-id: YOUR_ORG_ID&quot; \
        -H &quot;x-api-key: YOUR_API_KEY&quot; \
        -H &quot;Accept: application/json&quot; </code></pre></div>

All requests to Dental API require authentication via API keys. Authentication credentials are provided when your integration account is created by Centaur Software.

Every API request should include these headers.

is recommended but not currently enforced:

Header

Value

Dental API isolates each organisation’s data, so a single API key can be authorised for several organisations without their data ever mixing:

A sandbox environment is available for development and testing:

Status code

Meaning

What to check

All requests to Dental API require authentication via API keys. Authentication credentials are provided when your integration account is created by…

<p class="slate-p " >Choose your primary integration scenario to jump to the most relevant sections.</p><ul class="slate-ul " ><li class="slate-li " ><div style="position:relative"><strong class="slate-bold">Patient Data Integration</strong>: synchronise patient demographics, contact info, and medical history into your system. →<a href="/patient-resources" target="_self">Patient Resources</a></div></li><li class="slate-li " ><div style="position:relative"><strong class="slate-bold">Appointment Synchronisation</strong>: pull appointment schedules, status updates, and practitioner assignments for calendar apps. →<a href="/appointment-resources" target="_self">Appointment Resources</a></div></li><li class="slate-li " ><div style="position:relative"><strong class="slate-bold">Billing &amp; Payment Systems</strong>: extract transaction data, payment records, and financial reports for accounting software. →<a href="/financial-resources" target="_self">Financial Resources</a></div></li><li class="slate-li " ><div style="position:relative"><strong class="slate-bold">EHR/EMR Connectivity</strong>: FHIR R4 endpoints for healthcare interoperability and clinical data exchange. →<a href="/fhir-capabilities" target="_self">FHIR Capabilities</a></div></li><li class="slate-li " ><div style="position:relative"><strong class="slate-bold">Development &amp; Testing</strong>: quick authentication setup and endpoint testing for proof-of-concept builds. →<a href="/getting-started" target="_self">Getting Started</a></div></li><li class="slate-li " ><div style="position:relative"><strong class="slate-bold">Booking Automation</strong>: create appointments via online forms, voice agents, or chatbots. → <a href="/appointment-resources/post-appointment" target="_self">POST Appointment</a>, <a href="/appointment-resources/post-appointment-reschedule" target="_self">POST Appointment Reschedule</a>,<a href="/appointment-resources/post-appointment-cancel" target="_self">POST Appointment Cancel</a></div></li><li class="slate-li " ><div style="position:relative"><strong class="slate-bold">CRM-to-PMS Patient Sync</strong>: push patient demographics and updates into Dental4Web. → <a href="/patient-resources/post-patient" target="_self">POST Patient</a>,<a href="/patient-resources/patch-patient" target="_self">PATCH Patient</a></div></li><li class="slate-li " ><div style="position:relative"><strong class="slate-bold">Clinical Note Capture</strong>: record notes from dictation, telehealth, or device integrations. →<a href="/treatment-and-clinical-resources/post-clinical-notes" target="_self">POST Clinical Notes</a></div></li><li class="slate-li " ><div style="position:relative"><strong class="slate-bold">Imaging Integration</strong>: embed DICOM or JPEG dental imagery in patient portals or AI diagnostic tools. →<a href="/mediaweb-pacs-resources" target="_self">MediaWeb PACS Resources</a></div></li></ul>

Choose your primary integration scenario to jump to the most relevant sections.

Choose your primary integration scenario to jump to the most relevant sections. Patient Data Integration : synchronise patient demographics, contact…

Every endpoint in the Dental API returns JSON in a consistent envelope, so your integration can parse success and failure the same way across the whole surface. This page describes the request headers, the standard response envelope, pagination, and the FHIR response format. For the full list of HTTP status codes and 

Every request must include the following headers:

Required

Notes

Successful responses share a single shape. 

 is an array for non-FHIR endpoints. FHIR endpoints place a single FHIR Bundle object under 

Every endpoint in the Dental API returns JSON in a consistent envelope, so your integration can parse success and failure the same way across the…

Sections