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='["initial","initial"]' isHeaderAdded='true' tableHeader='[{"id":"a851bf63-2d74-4e6a-a410-576211ce594b","title":"Resource domain"},{"id":"d8448d6f-a1d3-4150-b888-b63af4f798a7","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='["initial","initial"]' isHeaderAdded='true' tableHeader='[{"id":"0068b62d-717c-4001-87a8-1453d7eb2d3b","title":"Title"},{"id":"f0185fab-dfcb-480f-a886-bd21e641c61f","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 ">100,000 requests per day per integrator</p></table-cell>
  </table-row>
</Table>

## Current capabilities

<Table style="width:100%;min-width:100%" colSizes='["initial","initial"]' isHeaderAdded='true' tableHeader='[{"id":"86732e14-0b6d-414c-acc0-0e68f2659342","title":"Capability"},{"id":"864f832c-2fff-4976-b2c3-5b2c07bda9ca","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='["initial","initial"]' isHeaderAdded='true' tableHeader='[{"id":"d57d981e-0474-4fea-ac4a-6b7916961c14","title":"I want to..."},{"id":"9eebcb7a-d557-4851-a629-0a81b2a5b608","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 must include the following headers:</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">Required. All requests must include this header to specify the expected response format. Requests sent without <code class="slate-code">Accept: application/json</code> are rejected.</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='["initial","initial","initial"]' isHeaderAdded='true' tableHeader='[{"id":"d6a1f001-0001-4001-9001-000000000001","title":"Error"},{"id":"d6a1f001-0002-4001-9001-000000000002","title":"Cause"},{"id":"d6a1f001-0003-4001-9001-000000000003","title":"Fix"}]'>
  <table-row>
    <table-cell><p class="slate-p ">HTTP 401</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 403</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">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 <code class="slate-code">retry_after</code> seconds and try again</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

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 must include these three headers:

<Table style="width:100%;min-width:100%" colSizes='["initial","initial","initial"]' isHeaderAdded='true' tableHeader='[{"id":"b1459f42-3690-4544-91d8-f2940e0ae54b","title":"Header"},{"id":"0a5497ea-5d5a-4cf5-905c-032370a0867d","title":"Value"},{"id":"998ece18-34d9-4239-8094-17eaa6a01472","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 ">Specifies the expected response format.</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
    
*   **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 401 on the next request.
    
*   **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='["initial","initial"]' isHeaderAdded='true' tableHeader='[{"id":"fb7bc225-a43b-4e7d-9ba8-bd7074215c76","title":"Status code"},{"id":"9c886df8-2473-49fd-ad24-ba9ec2c9a70e","title":"Meaning"},{"id":"382b9382-f131-46c4-ab6d-2a9c6d8bc310","title":"What to check"}]'>
  <table-row>
    <table-cell><p class="slate-p ">401 Unauthorized</p></table-cell>
    <table-cell><p class="slate-p ">Your <code class="slate-code">x-api-key</code> is missing, invalid, or expired</p></table-cell>
    <table-cell><p class="slate-p ">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 ">403 Forbidden</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 ">Confirm your key is mapped to this organisation. Contact <a href="mailto:dentalapi@centaursoftware.com">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](/post-appointment), [POST Appointment Reschedule](/post-appointment-reschedule), [POST Appointment Cancel](/post-appointment-cancel)
    
*   **CRM-to-PMS Patient Sync** — push patient demographics and updates into Dental4Web. → [POST Patient](/post-patient), [PATCH Patient](/patch-patient)
    
*   **Clinical Note Capture** — record notes from dictation, telehealth, or device integrations. → [POST Clinical Notes](/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

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 `support_code` values, see [Validation, Limits & Character Handling](/validation-limits-and-character-handling).

## Required headers

Every request must include the following headers:

<Table style="width:100%;min-width:100%" colSizes='["initial","initial"]' isHeaderAdded='true' tableHeader='[{"id":"5b8ce7c6-4cba-49d3-9eef-a5656b1e81c9","title":"Header"},{"id":"8c07883c-2ce7-4095-b4bf-e3e5e866198d","title":"Required"},{"id":"42eba96b-ba49-497b-863e-f7f94e5382ea","title":"Value"},{"id":"f3ab7447-42f4-4b3e-9eba-37031727d201","title":"Notes"}]'>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">org-id</code></p></table-cell>
    <table-cell><p class="slate-p ">Yes</p></table-cell>
    <table-cell><p class="slate-p ">Your organisation identifier (for example <code class="slate-code">Sandbox</code>)</p></table-cell>
    <table-cell><p class="slate-p ">Identifies the practice database to route to.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">x-api-key</code></p></table-cell>
    <table-cell><p class="slate-p ">Yes</p></table-cell>
    <table-cell><p class="slate-p ">Your API key</p></table-cell>
    <table-cell><p class="slate-p ">Issued per organisation. Keep it secret; never embed it in client-side code.</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 ">Yes</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. Send this header on every request.</p></table-cell>
  </table-row>
</Table>

## Standard response envelope

Successful responses share a single shape. `data` is an array for non-FHIR endpoints. FHIR endpoints place a single FHIR Bundle object under `data`.

<CodeBlock attributes='{"isFitToPage":true,"style":{},"lang":"json","label":"JSON"}'>
  <CodeLine>  {</CodeLine>
  <CodeLine>    "status": true,</CodeLine>
  <CodeLine>    "message": "Success",</CodeLine>
  <CodeLine>    "data": [</CodeLine>
  <CodeLine>      { "...": "one or more records" }</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>

*   `status` — `true` on success, `false` on error.
    
*   `message` — a short human-readable summary (`"Success"` on the happy path).
    
*   `data` — an array of records. Empty (`[]`) when there is nothing to return.
    
*   `pagination` — present on list endpoints (see below). Single-record and write responses may return an empty object (`{}`) or omit it.
    

## Pagination

List endpoints accept `page` and `per_page` query parameters and echo a `pagination` block:

<Table style="width:100%;min-width:100%" colSizes='["initial","initial"]' isHeaderAdded='true' tableHeader='[{"id":"3b46abe5-3378-4cfa-80c5-e64167bad959","title":"Field"},{"id":"8f30c6e8-bf8a-4888-aa22-de747f00ed97","title":"Meaning"}]'>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">page</code></p></table-cell>
    <table-cell><p class="slate-p ">The page returned (1-based).</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 ">Records per page.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">total_rows</code></p></table-cell>
    <table-cell><p class="slate-p ">Total matching records across all pages.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">total_pages</code></p></table-cell>
    <table-cell><p class="slate-p ">Total number of pages available.</p></table-cell>
  </table-row>
</Table>

`per_page` has an upper bound; values above the maximum are rejected with a validation error. See [Validation, Limits & Character Handling](/validation-limits-and-character-handling) for the exact limit.

## Error responses

Errors use the same envelope with `status: false` and an empty `data` array. Where the platform can attribute the failure to a specific cause, it includes a stable `support_code` you can quote to Centaur Software support:

<CodeBlock attributes='{"isFitToPage":true,"style":{},"lang":"json","label":"JSON"}'>
  <CodeLine>  {</CodeLine>
  <CodeLine>    "data": [],</CodeLine>
  <CodeLine>    "status": false,</CodeLine>
  <CodeLine>    "message": "postcode must be a valid Australian postcode (4 digits, range 0200-9999; got 'ABCD').",</CodeLine>
  <CodeLine>    "support_code": "PW-6020"</CodeLine>
  <CodeLine>  }</CodeLine>
</CodeBlock>

*   `message` is human-readable and, where possible, field-specific.
    
*   `support_code` is a stable identifier. **Treat it as optional** — many ordinary 4xx responses (authentication, organisation mismatch, not-found, request-schema validation) are message-only and carry no `support_code`. Always read `message` as the fallback.
    

The complete reference — HTTP status code conventions, every `support_code`, field limits, character handling, and the message-only responses — lives on the [Validation, Limits & Character Handling](/validation-limits-and-character-handling) page. It is the single source of truth; this page does not duplicate it.

## Date and time

*   **Timezone:** all date and datetime values are interpreted as **Australian Eastern Time** (AEST/AEDT, with daylight savings applied automatically). The rate-limit window boundaries are anchored on this timezone.
    
*   **Format for date values:** `YYYY-MM-DD` (ISO 8601 date). Example: `2026-06-09`.
    
*   **Format for datetime values:** `YYYY-MM-DDTHH:MM:SS` (ISO 8601). Example: `2026-06-09T14:30:00`.
    
*   **Inclusive bounds:** date range filters are inclusive on both ends.
    

## Warnings

Many responses carry a top-level `warnings[]` array. Each entry signals that the request succeeded but with a side-effect the caller should be aware of (capping, sanitisation, default-range injection, transformation).

<CodeBlock attributes='{"isFitToPage":true,"style":{},"lang":"json","label":"JSON"}'>
  <CodeLine>  {</CodeLine>
  <CodeLine>    "status": true,</CodeLine>
  <CodeLine>    "message": "Success",</CodeLine>
  <CodeLine>    "data": [],</CodeLine>
  <CodeLine>    "pagination": {},</CodeLine>
  <CodeLine>    "metadata": {},</CodeLine>
  <CodeLine>    "warnings": [</CodeLine>
  <CodeLine>      {</CodeLine>
  <CodeLine>        "type": "patient_recency_window_injected",</CodeLine>
  <CodeLine>        "message": "Auto-injected 90-day recency window because no narrowing filter was supplied",</CodeLine>
  <CodeLine>        "details": { "window_days": 90, "from_date": "2026-03-11", "to_date": "2026-06-09" }</CodeLine>
  <CodeLine>      }</CodeLine>
  <CodeLine>    ]</CodeLine>
  <CodeLine>  }</CodeLine>
</CodeBlock>

Warning types currently emitted:

<Table style="width:100%;min-width:100%" colSizes='["initial","initial","initial"]' isHeaderAdded='true' tableHeader='[{"id":"e1a1b2c3-0001-4a01-8a01-warn00000001","title":"Type"},{"id":"e1a1b2c3-0002-4a01-8a01-warn00000002","title":"Emitted by"},{"id":"e1a1b2c3-0003-4a01-8a01-warn00000003","title":"Meaning"}]'>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">patient_recency_window_injected</code></p></table-cell>
    <table-cell><p class="slate-p "><code class="slate-code">/patients</code></p></table-cell>
    <table-cell><p class="slate-p ">Broad call had no narrowing filter; a 90-day window was auto-applied.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">patient_fanout_cap_applied</code></p></table-cell>
    <table-cell><p class="slate-p "><code class="slate-code">/patients</code></p></table-cell>
    <table-cell><p class="slate-p ">Result set was truncated to the cap (10,000 broad / 1,000 DOB).</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">notes_html_stripped</code></p></table-cell>
    <table-cell><p class="slate-p "><code class="slate-code">POST /appointments</code>, <code class="slate-code">PATCH /appointments</code>, <code class="slate-code">POST /clinical-notes</code></p></table-cell>
    <table-cell><p class="slate-p ">HTML/script content was removed from a notes field before saving.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">notes_ascii_folded</code></p></table-cell>
    <table-cell><p class="slate-p "><code class="slate-code">POST /patients</code>, <code class="slate-code">PATCH /patients</code>, <code class="slate-code">POST /appointments</code>, etc.</p></table-cell>
    <table-cell><p class="slate-p ">Non-ASCII characters were folded to ASCII equivalents before saving.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">gender_sanitised</code></p></table-cell>
    <table-cell><p class="slate-p "><code class="slate-code">POST /patients</code>, <code class="slate-code">PATCH /patients</code></p></table-cell>
    <table-cell><p class="slate-p ">An invalid <code class="slate-code">gender_code</code> was sanitised to NULL.</p></table-cell>
  </table-row>
</Table>

`warnings[]` is omitted (or empty) when nothing notable happened.

## Metadata

The `/patients` endpoint carries a top-level `metadata` object with informational fields callers can read to detect capping and window-injection:

<Table style="width:100%;min-width:100%" colSizes='["initial","initial","initial"]' isHeaderAdded='true' tableHeader='[{"id":"e2a1b2c3-0001-4a01-8a01-meta00000001","title":"Field"},{"id":"e2a1b2c3-0002-4a01-8a01-meta00000002","title":"Type"},{"id":"e2a1b2c3-0003-4a01-8a01-meta00000003","title":"Meaning"}]'>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">patients_default_window_injected</code></p></table-cell>
    <table-cell><p class="slate-p ">boolean</p></table-cell>
    <table-cell><p class="slate-p "><code class="slate-code">true</code> when an auto 90-day recency window was injected.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">patients_default_window_days</code></p></table-cell>
    <table-cell><p class="slate-p ">int | null</p></table-cell>
    <table-cell><p class="slate-p "><code class="slate-code">90</code> when injected, <code class="slate-code">null</code> otherwise.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">patient_fanout_cap_applied</code></p></table-cell>
    <table-cell><p class="slate-p ">boolean</p></table-cell>
    <table-cell><p class="slate-p "><code class="slate-code">true</code> when either patient cap fired.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">patient_fanout_cap_value</code></p></table-cell>
    <table-cell><p class="slate-p ">int | null</p></table-cell>
    <table-cell><p class="slate-p "><code class="slate-code">1000</code> (DOB cap) or <code class="slate-code">10000</code> (broad cap) when fired, <code class="slate-code">null</code> otherwise.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">parameter_fallback_applied</code></p></table-cell>
    <table-cell><p class="slate-p ">boolean</p></table-cell>
    <table-cell><p class="slate-p "><code class="slate-code">true</code> when an optional parameter fell back to its default.</p></table-cell>
  </table-row>
</Table>

Internal telemetry fields (request timing, routing, and similar) are not exposed in the public response.

## Idempotency

The `POST /patients` and `POST /appointments` endpoints support idempotent retries via the `Idempotency-Key` header.

*   **Header:** `Idempotency-Key: <8–128 URL-safe characters>`
    
*   **Lifetime:** the key reserves a slot for 15 minutes (in-flight) and stores the result for 24 hours (replayable).
    
*   **Replay:** within 24 hours, retrying the same key with the same body returns the original response.
    
*   **Body mismatch:** retrying with a different body and the same key returns `400 RP-4221`.
    
*   **Concurrent reservation:** two simultaneous requests with the same key return `400 RP-4091` to the later caller.
    
*   **Invalid format:** keys outside the length / character set return `400 RP-4000`.
    

The PATCH, Cancel, and Reschedule endpoints do NOT support idempotency keys — sending the header returns `400 RP-4003`.

## FHIR response format

HL7 FHIR R4 output is served from dedicated endpoints under `/api/v1/fhir/...` — there is no `fhir=true` query parameter. Passing `fhir=true` to a normal read returns `400` with "Unexpected parameters: fhir, Please try again."; on a write endpoint an unknown `fhir` parameter is simply ignored.

Each FHIR endpoint returns the standard envelope with an HL7 FHIR R4 `Bundle` (type `searchset`) inside `data`. The bundle's `entry[]` contains the primary resource plus any referenced resources (for a Patient, the referenced `Practitioner` and `Location` are included).

<CodeBlock attributes='{"isFitToPage":true,"style":{},"lang":"json","label":"JSON"}'>
  <CodeLine>  {</CodeLine>
  <CodeLine>    "status": true,</CodeLine>
  <CodeLine>    "message": "Success",</CodeLine>
  <CodeLine>    "data": {</CodeLine>
  <CodeLine>      "resourceType": "Bundle",</CodeLine>
  <CodeLine>      "type": "searchset",</CodeLine>
  <CodeLine>      "total": 1,</CodeLine>
  <CodeLine>      "entry": [</CodeLine>
  <CodeLine>        {</CodeLine>
  <CodeLine>          "resource": {</CodeLine>
  <CodeLine>            "resourceType": "Patient",</CodeLine>
  <CodeLine>            "id": "72",</CodeLine>
  <CodeLine>            "name": [ { "use": "official", "family": "Citizen", "given": ["Jane"], "prefix": ["Ms"] } ]</CodeLine>
  <CodeLine>          }</CodeLine>
  <CodeLine>        }</CodeLine>
  <CodeLine>      ]</CodeLine>
  <CodeLine>    },</CodeLine>
  <CodeLine>    "pagination": { "page": 1, "per_page": 100, "total_rows": 1, "total_pages": 1 }</CodeLine>
  <CodeLine>  }</CodeLine>
</CodeBlock>

Resource mapping:

<Table style="width:100%;min-width:100%" colSizes='["initial","initial"]' isHeaderAdded='true' tableHeader='[{"id":"69fd0bc2-5ed1-43d6-9d7a-9b4777fca94a","title":"Endpoint"},{"id":"041da8fb-51cb-408a-afd1-74a5d7efc559","title":"FHIR resource"}]'>
  <table-row>
    <table-cell><p class="slate-p ">GET Patients / Patient By ID</p></table-cell>
    <table-cell><p class="slate-p "><code class="slate-code">Patient</code></p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p ">GET Appointments / Appointment By ID</p></table-cell>
    <table-cell><p class="slate-p "><code class="slate-code">Appointment</code></p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p ">GET Practitioners</p></table-cell>
    <table-cell><p class="slate-p "><code class="slate-code">Practitioner</code></p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p ">GET Locations</p></table-cell>
    <table-cell><p class="slate-p "><code class="slate-code">Location</code></p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p ">GET Clinical Notes</p></table-cell>
    <table-cell><p class="slate-p "><code class="slate-code">Observation</code></p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p ">GET Treatments</p></table-cell>
    <table-cell><p class="slate-p "><code class="slate-code">Procedure</code></p></table-cell>
  </table-row>
</Table>

FHIR is read-only; there are no FHIR write endpoints. Write endpoints always return the standard envelope, and any `fhir` parameter on a write is ignored.

API Response Formats

FHIR Capabilities

To ensure fair usage and system stability, Dental API enforces rate limits on all requests.

## Daily limits

In addition to the per-minute rate limits documented below, each integrator account is subject to a daily aggregate cap of **100,000 requests across all endpoints** (24-hour rolling window). Exceeding the daily cap returns HTTP 429 with `support_code: "RL-002"`.

## Current limits

<Table style="width:100%;min-width:100%" colSizes='["initial","initial"]' isHeaderAdded='true' tableHeader='[{"id":"20e1f913-dec2-472b-972f-11021668d604","title":"Limit Type"},{"id":"0570c339-f0fc-4b69-bb1d-6b797f962bc0","title":"Threshold"},{"id":"5f842227-2449-45b2-ad91-f75541a63683","title":"Window"}]'>
  <table-row>
    <table-cell><p class="slate-p ">Per Integrator</p></table-cell>
    <table-cell><p class="slate-p ">100,000 requests</p></table-cell>
    <table-cell><p class="slate-p ">Per day (24 hours, 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 ">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>

## Rate limit behaviour

When you exceed the rate limit:

1.  The API returns a `429 Too Many Requests` response
    
2.  The response includes a `Retry-After` header indicating seconds to wait
    
3.  Requests resume normally after the rate limit window resets
    

## What counts as a request

*   Every successful (2xx) response counts as one request.
    
*   HTTP 4xx responses (including validation errors and `RL-*` 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 peak / off-peak windows shift with Australian Eastern Time daylight savings. During AEDT (October–April), the peak window runs 8:00 AM – 8:00 PM AEDT; during AEST (April–October) it runs 8:00 AM – 8:00 PM AEST. Configure clients to interpret times in Australia/Sydney rather than fixed UTC offsets.

## Rate limit response example

<CodeBlock attributes='{"isFitToPage":true,"style":{},"lang":"json","label":"JSON"}'>
  <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>    "data": []</CodeLine>
  <CodeLine>  }</CodeLine>
</CodeBlock>

## 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

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.
    

## Response fields

<Table style="width:100%;min-width:100%" colSizes='["initial","initial","initial"]' isHeaderAdded='true' tableHeader='[{"id":"appt-fld-0001-field","title":"Field"},{"id":"appt-fld-0002-type","title":"Type"},{"id":"appt-fld-0003-desc","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">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>

## Important notes

*   **Date filtering:** supports the `mode` parameter — see [Filtering & Date Ranges](/filtering-and-date-ranges).
    
*   **Required filters:** at least one of `patient_id`, `appointment_id`, `appt_book_id`, `practitioner_id`, `location_id`, `from_date`, or `to_date` is required. A call with no filter returns 400 `RP-4000`.
    
*   **Wildcard values:** use `practitioner_id=-1` for all practitioners and `location_id=-1` for all locations.
    
*   **Include relations:** use `include=practitioners,locations,appt_books` to embed related data. `patients` has been removed as an include option — see the `include` parameter below for details.
    

## 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.
    

## Response fields

<Table style="width:100%;min-width:100%" colSizes='["initial","initial","initial"]' isHeaderAdded='true' tableHeader='[{"id":"apptid-fld-0001-field","title":"Field"},{"id":"apptid-fld-0002-type","title":"Type"},{"id":"apptid-fld-0003-desc","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>

## 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.
    

## Response fields

<Table style="width:100%;min-width:100%" colSizes='["initial","initial","initial"]' isHeaderAdded='true' tableHeader='[{"id":"cancel-fld-0001-field","title":"Field"},{"id":"cancel-fld-0002-type","title":"Type"},{"id":"cancel-fld-0003-desc","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>

## Important notes

*   **Mode behaviour:** `mode=0` filters by original appointment date; `mode=1` filters by cancellation date.
    
*   **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:** last 60 days when no `from_date`/`to_date` is supplied.
    
*   ⚠️ **Deprecation notice (April 2026):** `patients` is no longer a supported include value and has been removed from this endpoint.
    
*   **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/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.
    

## Response fields

<Table style="width:100%;min-width:100%" colSizes='["initial","initial","initial"]' isHeaderAdded='true' tableHeader='[{"id":"slot-fld-0001-field","title":"Field"},{"id":"slot-fld-0002-type","title":"Type"},{"id":"slot-fld-0003-desc","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_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>

## Important notes

*   Returns one record per available slot, per book, per day.
    
*   Books are selected with `appt_book_ids` (comma-separated). The date range you can search depends on the selection: a single book allows up to 90 days; all books (`appt_book_ids=-1`) allow up to 14 days. Exceeding the cap returns `400 SLT-001`.
    
*   `slotmode` selects which slots are returned: `0` returns empty slots only (default), `1` returns empty slots plus all presets, `2` returns empty slots plus online-bookable presets.
    
*   Pagination is required for large practices; `per_page` is capped at 500.
    
*   Only the parameters listed below 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='["initial","initial","initial"]' isHeaderAdded='true' tableHeader='[{"id":"abb874cd-35f3-4819-a5fd-b6b2afd3f447","title":"Status"},{"id":"35b66b6f-4c03-463f-9b75-1b2e8baf2be6","title":"support_code"},{"id":"cdfceed3-6860-4cdb-801e-bb6003bce719","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-001</code></p></table-cell>
    <table-cell><p class="slate-p ">Date span exceeds the cap (90 days single book, 14 days all books).</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-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 2).</p></table-cell>
  </table-row>
</Table>

### Example error responses

Date span exceeds the cap (`400`):

<CodeBlock attributes='{"isFitToPage":true,"style":{},"lang":"json","label":"JSON"}'>
  <CodeLine>  { "data": [], "status": false, "message": "All-books range exceeds the 14 day cap (requested 120 days). Specify a single appt_book_ids value to allow up to 90 days.", "support_code": "SLT-001" }</CodeLine>
</CodeBlock>

When a single book is queried beyond its larger cap, the same code is returned with the message `Single-book range exceeds the 90 day cap (requested 120 days).`

`to_date` in the past (`400`):

<CodeBlock attributes='{"isFitToPage":true,"style":{},"lang":"json","label":"JSON"}'>
  <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>  { "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>  { "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>  { "data": [], "status": false, "message": "No records found matching your search criteria." }</CodeLine>
</CodeBlock>

Parameter out of range (`422`):

<CodeBlock attributes='{"isFitToPage":true,"style":{},"lang":"json","label":"JSON"}'>
  <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='["initial","initial","initial"]' isHeaderAdded='true' tableHeader='[{"id":"postappt-req-0001-field","title":"Field"},{"id":"postappt-req-0002-type","title":"Type"},{"id":"postappt-req-0003-desc","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 (0 or greater).</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 1000 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='["initial","initial","initial"]' isHeaderAdded='true' tableHeader='[{"id":"592d7c44-507f-4aae-a243-abeb0c52e445","title":"Status"},{"id":"f1c9c873-9a77-4409-a077-289f3ba180ec","title":"support_code"},{"id":"cdcd5dcf-13b0-46f2-a4fa-eb3cba063bb3","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 ">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>  { "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>  { "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>  { "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>  { "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>  { "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>  { "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>  { "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>  { "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>  { "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>  { "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>  { "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>  { "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 1000 characters; accented characters are converted to their plain-letter equivalent; HTML and script content is removed before saving (disclosed via `warnings[]`). The `notes` value is stored but is not echoed back in the appointment response.
    

### Notes-transformation warnings

When `notes` contains HTML/script content, the API removes it before saving. The response carries a `warnings[]` entry like:

<CodeBlock attributes='{"isFitToPage":true,"style":{},"lang":"json","label":"JSON"}'>
  <CodeLine>"warnings": [{</CodeLine>
  <CodeLine>  "type": "notes_html_stripped",</CodeLine>
  <CodeLine>  "message": "HTML/script content removed from notes",</CodeLine>
  <CodeLine>  "details": {"original_length": 245, "stripped_length": 198}</CodeLine>
  <CodeLine>}]</CodeLine>
</CodeBlock>

See [API Response Formats](/api-response-formats) for the full envelope structure.

## 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='["initial","initial","initial"]' isHeaderAdded='true' tableHeader='[{"id":"patchappt-req-0001-field","title":"Field"},{"id":"patchappt-req-0002-type","title":"Type"},{"id":"patchappt-req-0003-desc","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 (0 or greater).</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 1000 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='["initial","initial","initial"]' isHeaderAdded='true' tableHeader='[{"id":"73fa9cd1-9507-4b6a-b401-6b110f8ef7dc","title":"Status"},{"id":"0bcac501-155c-48f6-995d-228d20a956f9","title":"support_code"},{"id":"a65b9069-e84b-4f98-84e3-5a659661686c","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 ">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`.

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>  { "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>  { "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>  { "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>  { "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>  { "data": [], "status": false, "message": "Practitioner 99999 not found.", "support_code": "AW-6052" }</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.
    
*   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='["initial","initial","initial"]' isHeaderAdded='true' tableHeader='[{"id":"cancelappt-req-0001-field","title":"Field"},{"id":"cancelappt-req-0002-type","title":"Type"},{"id":"cancelappt-req-0003-desc","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 1000 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='["initial","initial","initial"]' isHeaderAdded='true' tableHeader='[{"id":"3ab3ca19-3e43-41a8-8d86-144c23d398c4","title":"Status"},{"id":"98defc43-6dc1-4d7b-bd37-4a9efb65190d","title":"support_code"},{"id":"29bab2e1-3109-4505-9148-f92b2ce23411","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-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

Appointment not found or already cancelled (`404`):

<CodeBlock attributes='{"isFitToPage":true,"style":{},"lang":"json","label":"JSON"}'>
  <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>  { "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>  { "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`.
    
*   `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 1000 characters.
    
*   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='["initial","initial","initial"]' isHeaderAdded='true' tableHeader='[{"id":"reschappt-req-0001-field","title":"Field"},{"id":"reschappt-req-0002-type","title":"Type"},{"id":"reschappt-req-0003-desc","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='["initial","initial","initial"]' isHeaderAdded='true' tableHeader='[{"id":"2798bbe6-dc89-4ef9-a497-34c24778913c","title":"Status"},{"id":"04d64314-faaa-4cad-bd23-6da1abe76f45","title":"support_code"},{"id":"f343aa62-6fc5-476c-a6fe-05dbcced0dcc","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>  { "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>  { "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>  { "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>  { "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>  { "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>  { "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>  { "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.
    

## Response fields

<Table style="width:100%;min-width:100%" colSizes='["initial","initial","initial"]' isHeaderAdded='true' tableHeader='[{"id":"fin-fld-0001-field","title":"Field"},{"id":"fin-fld-0002-type","title":"Type"},{"id":"fin-fld-0003-desc","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>

## Important notes

*   **Required parameters:** `from_date` is mandatory.
    
*   **Transaction types:** `1` = Invoice, `2` = Discount, `3` = Refund, `4` = Payment.
    
*   **Wildcard values:** use `practitioner_id=-1` for all practitioners and `location_id=-1` for all locations.
    
*   **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.
    
*   **Default range:** last 365 days when no `from_date`/`to_date` is supplied.
    

## 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.
    

## Response fields

<Table style="width:100%;min-width:100%" colSizes='["initial","initial","initial"]' isHeaderAdded='true' tableHeader='[{"id":"rcpt-fld-0001-field","title":"Field"},{"id":"rcpt-fld-0002-type","title":"Type"},{"id":"rcpt-fld-0003-desc","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">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>

## Important notes

*   **Path parameter:** `receipt_id` is required.
    
*   **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

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.
    

## Response fields

<Table style="width:100%;min-width:100%" colSizes='["initial","initial","initial"]' isHeaderAdded='true' tableHeader='[{"id":"pat-fld-0001-field","title":"Field"},{"id":"pat-fld-0002-type","title":"Type"},{"id":"pat-fld-0003-desc","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">medical_conditions_recorded</code></p></table-cell>
    <table-cell><p class="slate-p ">string | null</p></table-cell>
    <table-cell><p class="slate-p ">Comma-separated conditions.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">patient_alerts</code></p></table-cell>
    <table-cell><p class="slate-p ">string | null</p></table-cell>
    <table-cell><p class="slate-p ">Alert flags.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">patient_alert_notes</code></p></table-cell>
    <table-cell><p class="slate-p ">string | null</p></table-cell>
    <table-cell><p class="slate-p ">Alert notes.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">allergies_recorded</code></p></table-cell>
    <table-cell><p class="slate-p ">string | null</p></table-cell>
    <table-cell><p class="slate-p ">Comma-separated allergies.</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>

## Important notes

*   **Auto-injected recency window:** when called without `patient_id`, `patient_card`, 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.
    
*   The response carries `metadata.patients_default_window_injected: true`, `metadata.patient_fanout_cap_applied: true`, `metadata.patient_fanout_cap_value: 10000`, plus a `warnings[]` entry. Check these fields on broad calls to detect silent capping.
    
*   To bypass the cap, supply both `from_date` and `to_date` spanning 370 days or fewer (the sync-window path), or a `patient_id` / `patient_card` lookup.
    
*   **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.
    
*   **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='["initial","initial","initial"]' isHeaderAdded='true' tableHeader='[{"id":"pbi-fld-0001-field","title":"Field"},{"id":"pbi-fld-0002-type","title":"Type"},{"id":"pbi-fld-0003-desc","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">medical_conditions_recorded</code></p></table-cell>
    <table-cell><p class="slate-p ">string | null</p></table-cell>
    <table-cell><p class="slate-p ">Comma-separated conditions.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">patient_alerts</code></p></table-cell>
    <table-cell><p class="slate-p ">string | null</p></table-cell>
    <table-cell><p class="slate-p ">Alert flags.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">patient_alert_notes</code></p></table-cell>
    <table-cell><p class="slate-p ">string | null</p></table-cell>
    <table-cell><p class="slate-p ">Alert notes.</p></table-cell>
  </table-row>
  <table-row>
    <table-cell><p class="slate-p "><code class="slate-code">allergies_recorded</code></p></table-cell>
    <table-cell><p class="slate-p ">string | null</p></table-cell>
    <table-cell><p class="slate-p ">Comma-separated allergies.</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>

## 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.
    

## Response fields

<Table style="width:100%;min-width:100%" colSizes='["initial","initial","initial"]' isHeaderAdded='true' tableHeader='[{"id":"rcl-fld-0001-field","title":"Field"},{"id":"rcl-fld-0002-type","title":"Type"},{"id":"rcl-fld-0003-desc","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>

## 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.
    

## 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='["initial","initial","initial"]' isHeaderAdded='true' tableHeader='[{"id":"pex-fld-0001-field","title":"Field"},{"id":"pex-fld-0002-type","title":"Type"},{"id":"pex-fld-0003-desc","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">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>

## 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='["initial","initial","initial"]' isHeaderAdded='true' tableHeader='[{"id":"pcr-bdy-0001-field","title":"Field"},{"id":"pcr-bdy-0002-type","title":"Type"},{"id":"pcr-bdy-0003-desc","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 `warnings[]` entry of type `gender_sanitised` 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.</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.</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='["initial","initial","initial"]' isHeaderAdded='true' tableHeader='[{"id":"a3a5b499-7e15-4726-a00a-5f08f13b85ba","title":"Status"},{"id":"a316b1d0-f9a5-41a7-b41b-51a75975aeda","title":"support_code"},{"id":"de2e732b-07ab-4995-8fb9-055f0baa6a0a","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>  { "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>  { "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>  { "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>  { "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>  { "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>  { "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>  { "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>  { "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>  { "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>  { "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).
    

## 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='["initial","initial","initial"]' isHeaderAdded='true' tableHeader='[{"id":"pup-bdy-0001-field","title":"Field"},{"id":"pup-bdy-0002-type","title":"Type"},{"id":"pup-bdy-0003-desc","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 (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 `warnings[]` entry of type `gender_sanitised` 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.</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.</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='["initial","initial","initial"]' isHeaderAdded='true' tableHeader='[{"id":"7644a9b1-ac03-4bfa-a69a-945ddd09471a","title":"Status"},{"id":"b85b10e5-7bf5-4a4a-8b16-3f8f69961248","title":"support_code"},{"id":"4bb3ebaf-54ff-41aa-812b-e6c1f1c0f0a1","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>  { "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>  { "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>  { "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>  { "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>  { "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>  { "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>  { "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` (0 or greater).
    
*   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

<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.
    

## Response fields

<Table style="width:100%;min-width:100%" colSizes='["initial","initial","initial"]' isHeaderAdded='true' tableHeader='[{"id":"trt-fld-0001-field","title":"Field"},{"id":"trt-fld-0002-type","title":"Type"},{"id":"trt-fld-0003-desc","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:** last 90 days when no `from_date` / `to_date` is supplied.
    
*   **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.
    

## Response fields

<Table style="width:100%;min-width:100%" colSizes='["initial","initial","initial"]' isHeaderAdded='true' tableHeader='[{"id":"tp-fld-0001-field","title":"Field"},{"id":"tp-fld-0002-type","title":"Type"},{"id":"tp-fld-0003-desc","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:** last 180 days when no `from_date` / `to_date` is supplied.
    
*   **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.
    

## Response fields

<Table style="width:100%;min-width:100%" colSizes='["initial","initial","initial"]' isHeaderAdded='true' tableHeader='[{"id":"cn-fld-0001-field","title":"Field"},{"id":"cn-fld-0002-type","title":"Type"},{"id":"cn-fld-0003-desc","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:** last 90 days when no `from_date` / `to_date` is supplied.
    
*   **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='["initial","initial","initial"]' isHeaderAdded='true' tableHeader='[{"id":"pcn-fld-0001-field","title":"Field"},{"id":"pcn-fld-0002-type","title":"Type"},{"id":"pcn-fld-0003-desc","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, including its `treatment_id` (not a separate "note id"), the resolved `practitioner_id` and `location_id`, and a `pagination` block.

<CodeBlock attributes='{"isFitToPage":true,"style":{},"lang":"json","label":"JSON"}'>
  <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='["initial","initial","initial"]' isHeaderAdded='true' tableHeader='[{"id":"pcn-err-0001-status","title":"Status"},{"id":"pcn-err-0002-code","title":"support_code"},{"id":"pcn-err-0003-meaning","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 ">—</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 ">—</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 ">—</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 ">—</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 ">—</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 ">—</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 ">—</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>{ "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>{ "data": [], "status": false, "message": "patient_id must be an INTEGER; got non-numeric value", "support_code": "TYP-INT" }</CodeLine>
</CodeBlock>

Patient not found (`404`):

<CodeBlock attributes='{"isFitToPage":true,"style":{},"lang":"json","label":"JSON"}'>
  <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>{ "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>{ "message": "Forbidden" }</CodeLine>
</CodeBlock>

Organisation not associated with the key (`400`):

<CodeBlock attributes='{"isFitToPage":true,"style":{},"lang":"json","label":"JSON"}'>
  <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>{ "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 its `treatment_id` (not a separate "note id").
    
*   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='["initial","initial"]' isHeaderAdded='true' tableHeader='[{"id":"0dab0523-b56b-4b81-9d8b-48354d578a74","title":"Group"},{"id":"af590750-8c29-4dad-a405-06aacf5f99cf","title":"Endpoint"},{"id":"b4d43149-bd6c-4864-9b0d-2e38a929a1ac","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='["initial","initial","initial"]' isHeaderAdded='true' tableHeader='[{"id":"book-fld-0001-field","title":"Field"},{"id":"book-fld-0002-type","title":"Type"},{"id":"book-fld-0003-desc","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.

## 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='["initial","initial","initial"]' isHeaderAdded='true' tableHeader='[{"id":"apc-fld-0001-field","title":"Field"},{"id":"apc-fld-0002-type","title":"Type"},{"id":"apc-fld-0003-desc","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='["initial","initial","initial"]' isHeaderAdded='true' tableHeader='[{"id":"cnl-fld-0001-field","title":"Field"},{"id":"cnl-fld-0002-type","title":"Type"},{"id":"cnl-fld-0003-desc","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='["initial","initial","initial"]' isHeaderAdded='true' tableHeader='[{"id":"loc-fld-0001-field","title":"Field"},{"id":"loc-fld-0002-type","title":"Type"},{"id":"loc-fld-0003-desc","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 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/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='["initial","initial","initial"]' isHeaderAdded='true' tableHeader='[{"id":"pay-fld-0001-field","title":"Field"},{"id":"pay-fld-0002-type","title":"Type"},{"id":"pay-fld-0003-desc","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 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/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='["initial","initial","initial"]' isHeaderAdded='true' tableHeader='[{"id":"prc-fld-0001-field","title":"Field"},{"id":"prc-fld-0002-type","title":"Type"},{"id":"prc-fld-0003-desc","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">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='["initial","initial","initial"]' isHeaderAdded='true' tableHeader='[{"id":"proc-fld-0001-field","title":"Field"},{"id":"proc-fld-0002-type","title":"Type"},{"id":"proc-fld-0003-desc","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 and, where applicable, the `location_id` / `include` filters. 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.

## Response fields

<Table style="width:100%;min-width:100%" colSizes='["initial","initial","initial"]' isHeaderAdded='true' tableHeader='[{"id":"rcl-fld-0001-field","title":"Field"},{"id":"rcl-fld-0002-type","title":"Type"},{"id":"rcl-fld-0003-desc","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.

## 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='["initial","initial","initial"]' isHeaderAdded='true' tableHeader='[{"id":"slt-fld-0001-field","title":"Field"},{"id":"slt-fld-0002-type","title":"Type"},{"id":"slt-fld-0003-desc","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='["initial","initial","initial"]' isHeaderAdded='true' tableHeader='[{"id":"ttl-fld-0001-field","title":"Field"},{"id":"ttl-fld-0002-type","title":"Type"},{"id":"ttl-fld-0003-desc","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='["initial","initial","initial"]' isHeaderAdded='true' tableHeader='[{"id":"usr-fld-0001-field","title":"Field"},{"id":"usr-fld-0002-type","title":"Type"},{"id":"usr-fld-0003-desc","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

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='["initial","initial"]' isHeaderAdded='true' tableHeader='[{"id":"e30dc831-1725-457b-a4d7-fa67fa107a33","title":"Operation"},{"id":"411bf72c-519f-4735-b2fc-60d9122f4f7b","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.

## Response fields

<Table style="width:100%;min-width:100%" colSizes='["initial","initial","initial"]' isHeaderAdded='true' tableHeader='[{"id":"mwp-srch-0001-field","title":"Field"},{"id":"mwp-srch-0002-type","title":"Type"},{"id":"mwp-srch-0003-desc","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>

## Important notes

- MWP-enabled only: available only for organisations with MediaWeb PACS integration.
- Metadata only: returns image references, not the image data itself.
- Date defaults: when both `start_date` and `end_date` are omitted, the search defaults to the past 365 days (no future dates).

## 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" \</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='["initial","initial","initial"]' isHeaderAdded='true' tableHeader='[{"id":"mwp-img-prm-0001-field","title":"Field"},{"id":"mwp-img-prm-0002-type","title":"Type"},{"id":"mwp-img-prm-0003-desc","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='["initial","initial","initial"]' isHeaderAdded='true' tableHeader='[{"id":"mwp-img-0001-field","title":"Field"},{"id":"mwp-img-0002-type","title":"Type"},{"id":"mwp-img-0003-desc","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>

## 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='["initial","initial","initial"]' isHeaderAdded='true' tableHeader='[{"id":"mwp-blk-0001-field","title":"Field"},{"id":"mwp-blk-0002-type","title":"Type"},{"id":"mwp-blk-0003-desc","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>

## Important notes

- URL expiry: the pre-signed URLs expire after 10 minutes (600 seconds).
- Large responses: the endpoint may return many images — use pagination.
- 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?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 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='["initial","initial","initial"]' isHeaderAdded='true' tableHeader='[{"id":"ftrt-map-0001-src","title":"Source field"},{"id":"ftrt-map-0002-fhir","title":"FHIR element"},{"id":"ftrt-map-0003-notes","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.

## Sample bundle

<CodeBlock attributes='{"isFitToPage":true,"style":{},"lang":"json","label":"JSON"}'>
  <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: not_supported." }</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='["initial","initial","initial"]' isHeaderAdded='true' tableHeader='[{"id":"fp-map-0001-src","title":"Source field"},{"id":"fp-map-0002-fhir","title":"FHIR element"},{"id":"fp-map-0003-notes","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 ">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>

## Sample bundle

<CodeBlock attributes='{"isFitToPage":true,"style":{},"lang":"json","label":"JSON"}'>
  <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='["initial","initial","initial"]' isHeaderAdded='true' tableHeader='[{"id":"fpid-map-0001-src","title":"Source field"},{"id":"fpid-map-0002-fhir","title":"FHIR element"},{"id":"fpid-map-0003-notes","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 ">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>

## Sample bundle

<CodeBlock attributes='{"isFitToPage":true,"style":{},"lang":"json","label":"JSON"}'>
  <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='["initial","initial","initial"]' isHeaderAdded='true' tableHeader='[{"id":"fa-map-0001-src","title":"Source field"},{"id":"fa-map-0002-fhir","title":"FHIR element"},{"id":"fa-map-0003-notes","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>

## Sample bundle

<CodeBlock attributes='{"isFitToPage":true,"style":{},"lang":"json","label":"JSON"}'>
  <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='["initial","initial","initial"]' isHeaderAdded='true' tableHeader='[{"id":"faid-map-0001-src","title":"Source field"},{"id":"faid-map-0002-fhir","title":"FHIR element"},{"id":"faid-map-0003-notes","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>

## Sample bundle

<CodeBlock attributes='{"isFitToPage":true,"style":{},"lang":"json","label":"JSON"}'>
  <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 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='["initial","initial","initial"]' isHeaderAdded='true' tableHeader='[{"id":"fcn-map-0001-src","title":"Source field"},{"id":"fcn-map-0002-fhir","title":"FHIR element"},{"id":"fcn-map-0003-notes","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 ">ISO 8601 instant in UTC.</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>

## Sample bundle

<CodeBlock attributes='{"isFitToPage":true,"style":{},"lang":"json","label":"JSON"}'>
  <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 Frank Papadopoulos"}],</CodeLine>
  <CodeLine>          "effectiveDateTime": "2019-12-09T00:00:00Z",</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='["initial","initial","initial"]' isHeaderAdded='true' tableHeader='[{"id":"fpr-map-0001-src","title":"Source field"},{"id":"fpr-map-0002-fhir","title":"FHIR element"},{"id":"fpr-map-0003-notes","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/identifier/practitioner-code</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>

## Sample bundle

<CodeBlock attributes='{"isFitToPage":true,"style":{},"lang":"json","label":"JSON"}'>
  <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/identifier/practitioner-code", "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='["initial","initial","initial"]' isHeaderAdded='true' tableHeader='[{"id":"floc-map-0001-src","title":"Source field"},{"id":"floc-map-0002-fhir","title":"FHIR element"},{"id":"floc-map-0003-notes","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>

## Sample bundle

<CodeBlock attributes='{"isFitToPage":true,"style":{},"lang":"json","label":"JSON"}'>
  <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;"><table class="slate-table" style="min-width:100%;"><div class="published-table-header" style="width:100%;min-width:100%;"><div style="width:100%;">Resource domain</div><div style="width:100%;">Description</div></div><colgroup ><col style="width:initial"><col style="width:initial"></colgroup><tbody class="slate-TableElement-tbody"><tr class="slate-tr " ><td class="slate-td"><p class="slate-p " ><strong class="slate-bold">Patient Records</strong></p></td><td class="slate-td"><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"><p class="slate-p " ><strong class="slate-bold">Appointments</strong></p></td><td class="slate-td"><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"><p class="slate-p " ><strong class="slate-bold">Financial Transactions</strong></p></td><td class="slate-td"><p class="slate-p " >Invoices, payments, discounts, refunds, and health fund rebates</p></td></tr><tr class="slate-tr " ><td class="slate-td"><p class="slate-p " ><strong class="slate-bold">Treatments &amp; Clinical</strong></p></td><td class="slate-td"><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"><p class="slate-p " ><strong class="slate-bold">Dental Imaging</strong></p></td><td class="slate-td"><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;"><table class="slate-table" style="min-width:100%;"><div class="published-table-header" style="width:100%;min-width:100%;"><div style="width:100%;">Title</div><div style="width:100%;">Details</div></div><colgroup ><col style="width:initial"><col style="width:initial"></colgroup><tbody class="slate-TableElement-tbody"><tr class="slate-tr " ><td class="slate-td"><p class="slate-p " ><strong class="slate-bold">Base URL</strong></p></td><td class="slate-td"><p class="slate-p " ><a href="https://api-uat.dental4web.com.au" target="_self">https://api-uat.dental4web.com.au</a></p></td></tr><tr class="slate-tr " ><td class="slate-td"><p class="slate-p " ><strong class="slate-bold">Protocol</strong></p></td><td class="slate-td"><p class="slate-p " >HTTPS only (TLS 1.2+)</p></td></tr><tr class="slate-tr " ><td class="slate-td"><p class="slate-p " ><strong class="slate-bold">Format</strong></p></td><td class="slate-td"><p class="slate-p " >JSON (with optional FHIR R4 output)</p></td></tr><tr class="slate-tr " ><td class="slate-td"><p class="slate-p " ><strong class="slate-bold">Authentication</strong></p></td><td class="slate-td"><p class="slate-p " >API key + organisation ID headers</p></td></tr><tr class="slate-tr " ><td class="slate-td"><p class="slate-p " ><strong class="slate-bold">Rate Limit</strong></p></td><td class="slate-td"><p class="slate-p " >100,000 requests per day per integrator</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;"><table class="slate-table" style="min-width:100%;"><div class="published-table-header" style="width:100%;min-width:100%;"><div style="width:100%;">Capability</div><div style="width:100%;">Status</div></div><colgroup ><col style="width:initial"><col style="width:initial"></colgroup><tbody class="slate-TableElement-tbody"><tr class="slate-tr " ><td class="slate-td"><p class="slate-p " >Read patient demographics &amp; recalls</p></td><td class="slate-td"><p class="slate-p " >✅ Available</p></td></tr><tr class="slate-tr " ><td class="slate-td"><p class="slate-p " >Read patient extended (custom fields)</p></td><td class="slate-td"><p class="slate-p " >✅ Available</p></td></tr><tr class="slate-tr " ><td class="slate-td"><p class="slate-p " >Write access (patients, appointments and clinical notes)</p></td><td class="slate-td"><p class="slate-p " >✅ Available</p></td></tr><tr class="slate-tr " ><td class="slate-td"><p class="slate-p " >Read appointments (incl. cancelled)</p></td><td class="slate-td"><p class="slate-p " >✅ Available</p></td></tr><tr class="slate-tr " ><td class="slate-td"><p class="slate-p " >Find available appointment slots</p></td><td class="slate-td"><p class="slate-p " >✅ Available</p></td></tr><tr class="slate-tr " ><td class="slate-td"><p class="slate-p " >Read treatments, treatment plans, clinical notes</p></td><td class="slate-td"><p class="slate-p " >✅ Available</p></td></tr><tr class="slate-tr " ><td class="slate-td"><p class="slate-p " >Read financial transactions &amp; receipts</p></td><td class="slate-td"><p class="slate-p " >✅ Available</p></td></tr><tr class="slate-tr " ><td class="slate-td"><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"><p class="slate-p " >✅ Available</p></td></tr><tr class="slate-tr " ><td class="slate-td"><p class="slate-p " >Read DICOM images &amp; metadata via MediaWeb PACS</p></td><td class="slate-td"><p class="slate-p " >✅ Available</p></td></tr><tr class="slate-tr " ><td class="slate-td"><p class="slate-p " >FHIR R4 reads (Patient, Appointment, Practitioner, Location, Observation, Procedure)</p></td><td class="slate-td"><p class="slate-p " >✅ Available</p></td></tr><tr class="slate-tr " ><td class="slate-td"><p class="slate-p " >Create / update Patient</p></td><td class="slate-td"><p class="slate-p " >✅ Available</p></td></tr><tr class="slate-tr " ><td class="slate-td"><p class="slate-p " >Create / update Appointment, Cancel, Reschedule</p></td><td class="slate-td"><p class="slate-p " >✅ Available</p></td></tr><tr class="slate-tr " ><td class="slate-td"><p class="slate-p " >Create Clinical Note</p></td><td class="slate-td"><p class="slate-p " >✅ Available</p></td></tr><tr class="slate-tr " ><td class="slate-td"><p class="slate-p " >OAuth 2.0 authentication and authorisation</p></td><td class="slate-td"><p class="slate-p " >🔜 Planned for future releases</p></td></tr><tr class="slate-tr " ><td class="slate-td"><p class="slate-p " >Webhook notifications</p></td><td class="slate-td"><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;"><table class="slate-table" style="min-width:100%;"><div class="published-table-header" style="width:100%;min-width:100%;"><div style="width:100%;">I want to...</div><div style="width:100%;">Go to...</div></div><colgroup ><col style="width:initial"><col style="width:initial"></colgroup><tbody class="slate-TableElement-tbody"><tr class="slate-tr " ><td class="slate-td"><p class="slate-p " >Set up authentication</p></td><td class="slate-td"><p class="slate-p " ><a href="/getting-started" target="_self">Getting Started</a></p></td></tr><tr class="slate-tr " ><td class="slate-td"><p class="slate-p " >Understand the response format</p></td><td class="slate-td"><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"><p class="slate-p " >Find the right endpoint for my use case</p></td><td class="slate-td"><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"><p class="slate-p " >Learn about FHIR support</p></td><td class="slate-td"><p class="slate-p " ><a href="/fhir-capabilities" target="_self">FHIR Capabilities</a></p></td></tr><tr class="slate-tr " ><td class="slate-td"><p class="slate-p " >See all available endpoints</p></td><td class="slate-td"><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>

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...

<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 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 class="slate-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></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 style="background-color:transparent;color:#434343">All HTTP requests must include the following headers:</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 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 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 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 style="background-color:transparent;color:#434343"><em class="slate-italic">Required. All requests must include this header to specify the expected response format. Requests sent without </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"> are rejected.</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 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;"><table class="slate-table" style="min-width:100%;"><div class="published-table-header" style="width:100%;min-width:100%;"><div style="width:100%;">Error</div><div style="width:100%;">Cause</div><div style="width:100%;">Fix</div></div><colgroup ><col style="width:initial"><col style="width:initial"><col style="width:initial"></colgroup><tbody class="slate-TableElement-tbody"><tr class="slate-tr " ><td class="slate-td"><p class="slate-p " >HTTP 401</p></td><td class="slate-td"><p class="slate-p " >Missing or invalid <code class="slate-code">x-api-key</code> header</p></td><td class="slate-td"><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"><p class="slate-p " >HTTP 400 &quot;Missing Organisation ID&quot;</p></td><td class="slate-td"><p class="slate-p " >Missing <code class="slate-code">org-id</code> header</p></td><td class="slate-td"><p class="slate-p " >Add <code class="slate-code">org-id: Sandbox</code></p></td></tr><tr class="slate-tr " ><td class="slate-td"><p class="slate-p " >HTTP 403</p></td><td class="slate-td"><p class="slate-p " >API key valid but not authorised for this organisation</p></td><td class="slate-td"><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"><p class="slate-p " >HTTP 429</p></td><td class="slate-td"><p class="slate-p " >Rate limit exceeded</p></td><td class="slate-td"><p class="slate-p " >Wait the <code class="slate-code">retry_after</code> seconds and try again</p></td></tr><tr class="slate-tr " ><td class="slate-td"><p class="slate-p " >Timeout</p></td><td class="slate-td"><p class="slate-p " >Slow connection or a temporary service slowdown</p></td><td class="slate-td"><p class="slate-p " >Increase client timeout to 60 s and retry</p></td></tr></tbody></table></div></div>

Error

Cause

<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 must include these three headers:</p><div class="published-table"><div class="table-container" style="padding-left: 0px;"><table class="slate-table" style="min-width:100%;"><div class="published-table-header" style="width:100%;min-width:100%;"><div style="width:100%;">Header</div><div style="width:100%;">Value</div><div style="width:100%;">Description</div></div><colgroup ><col style="width:initial"><col style="width:initial"><col style="width:initial"></colgroup><tbody class="slate-TableElement-tbody"><tr class="slate-tr " ><td class="slate-td"><p class="slate-p " ><span style="color:#434343"><code class="slate-code">x-api-key</code></span></p></td><td class="slate-td"><p class="slate-p " >Your API key</p></td><td class="slate-td"><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"><p class="slate-p " ><span style="color:#434343"><code class="slate-code">org-id</code></span></p></td><td class="slate-td"><p class="slate-p " >Organisation ID</p></td><td class="slate-td"><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"><p class="slate-p " ><code class="slate-code">Accept</code></p></td><td class="slate-td"><p class="slate-p " ><code class="slate-code">application/json</code></p></td><td class="slate-td"><p class="slate-p " >Specifies the expected response format.</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</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 401 on the next request.</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;"><table class="slate-table" style="min-width:100%;"><div class="published-table-header" style="width:100%;min-width:100%;"><div style="width:100%;">Status code</div><div style="width:100%;">Meaning</div><div style="width:100%;">What to check</div></div><colgroup ><col style="width:initial"><col style="width:initial"></colgroup><tbody class="slate-TableElement-tbody"><tr class="slate-tr " ><td class="slate-td"><p class="slate-p " >401 Unauthorized</p></td><td class="slate-td"><p class="slate-p " >Your <code class="slate-code">x-api-key</code> is missing, invalid, or expired</p></td><td class="slate-td"><p class="slate-p " >Verify the API key value is correct and has not been revoked</p></td></tr><tr class="slate-tr " ><td class="slate-td"><p class="slate-p " >403 Forbidden</p></td><td class="slate-td"><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"><p class="slate-p " >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 must include these three headers:

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

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 

Field

 has an upper bound; values above the maximum are rejected with a validation error. See 

 array. Where the platform can attribute the failure to a specific cause, it includes a stable 

 you can quote to Centaur Software support:

The complete reference — HTTP status code conventions, every 

, field limits, character handling, and the message-only responses — lives on the 

 page. It is the single source of truth; this page does not duplicate it.

 array. Each entry signals that the request succeeded but with a side-effect the caller should be aware of (capping, sanitisation, default-range injection, transformation).

Type

Emitted by

 is omitted (or empty) when nothing notable happened.

 object with informational fields callers can read to detect capping and window-injection:

Internal telemetry fields (request timing, routing, and similar) are not exposed in the public response.

 endpoints support idempotent retries via the 

The PATCH, Cancel, and Reschedule endpoints do NOT support idempotency keys — sending the header returns 

HL7 FHIR R4 output is served from dedicated endpoints under 

 with “Unexpected parameters: fhir, Please try again.”; on a write endpoint an unknown 

Each FHIR endpoint returns the standard envelope with an HL7 FHIR R4 

 contains the primary resource plus any referenced resources (for a Patient, the referenced 

Endpoint

FHIR resource

FHIR is read-only; there are no FHIR write endpoints. Write endpoints always return the standard envelope, and any 

Dental API supports HL7® FHIR® R4 (Release 4.0.1) output for healthcare interoperability. FHIR (Fast Healthcare Interoperability Resources) is an international standard for exchanging healthcare information electronically.

Scope: FHIR data format, not SMART on FHIR

If your integration needs SMART on FHIR (patient-facing apps, EHR-launched clinical apps, end-user OAuth), the Dental API is not a drop-in target. If you only need FHIR R4 data shapes for a server-to-server backend integration, the 

FHIR is a standard developed by HL7 International that defines how healthcare information can be exchanged between systems. It uses modern web technologies (REST, JSON, XML) and provides a set of standardised “resources” representing clinical concepts like patients, appointments, and observations.

The following endpoints support FHIR R4 output. Use the dedicated 

 endpoints to receive FHIR R4-formatted responses. Passing 

 to a non-FHIR read path returns 400 with 

Standard Endpoint

FHIR Endpoint

FHIR Resource Type

Reason

When using a FHIR endpoint, responses are returned as a FHIR Bundle of type 

Practice Management System (PMS) patient data maps to FHIR Patient as follows:

Source field

FHIR Path

PMS treatment data maps to FHIR Procedure as follows:

Sections

Ask an AI

Code with AI