Overview
This describes the resources that make up the official Dentally API. The Dentally API is organized around REST. JSON will be returned from all responses from the API, including errors.
API Endpoints
Production - https://api.dentally.co
Sandbox - https://api.sandbox.dentally.co
Join the Developer Program
The Dentally Developer Program is currently invite only. Sign up here to be notified when we’re ready to accept applications.
Versioning
By default, all requests receive the v1 version of the API. We encourage you to explicitly request the version by specifying it in the URL for example
https://api.dentally.co/v1/user
The version number is however optional and if it is missing you will simply receive the latest version of the API.
https://api.dentally.co/user
Pagination
Requests that return multiple items will be paginated to 25 items by default. You can specify further pages with the page parameter. For most resources, you can also set a custom page size, up to 100, with the per_page parameter.
EXAMPLE PAGINATION
https://api.dentally.co/patients?page=2&per_page=50
Ordering Resources
Most resources can also be ordered when listing multiple items. To order a resource, pass in the parameter sort_by and the name of the attribute you wish to order by. In addition, you can specify the direction you’d like to sort the attributes by including the parameter sort_direction. The available options for sort_direction are asc and desc
EXAMPLE ORDERING
https://api.dentally.co/appointments?sort_by=id&sort_direction=desc
Metadata
Some updatable Dentally objects - including Patients and Appointments - have a metadata parameter. You can use this parameter to attach key-value data to these Dentally objects. Metadata is useful for storing additional, structured information on an object. For example, you could store your unique ID and corresponding reference from your integration on a Dentally Patient object.
Metadata is not used by the Dentally app and won’t be seen by Dentally users unless you choose to show it to them.
EXAMPLE METADATA ATTRIBUTE
"metadata": {
"my_id": "ABC123"
}
Note: You can have up to 3 keys, with key names up to 40 characters long and values up to 500 characters long.
Cross Origin Resource Sharing
The API supports Cross Origin Resource Sharing (CORS) for AJAX requests from any origin.
EXAMPLE HEADERS
curl -i https://api.dentally.co -H "Origin: https://example.com"
HTTP/1.1 200 OK
Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET, POST, PUT, PATCH, DELETE
Access-Control-Allow-Headers: X-Requested-With, X-Prototype-Version, Content-Type, Authorization
Access-Control-Expose-Headers: ETag, X-OAuth-Scopes
X-OAuth-Scopes: user:read patient:read patient:update
ETag: "882411ad20c998d0e95b40d74af9b942"
User Agent Required
All api requests must include a valid User-Agent header. Requests without a User-Agent header will be rejected. We request that you put your application name and version for the User-Agent header value.
EXAMPLE 403 RESPONSE
{
"error": {
"type": "invalid_request_error",
"message": "Request forbidden by administrative rules. Please make sure your request has a User-Agent header.",
"documentation_url": "https://developer.dentally.co"
}
}
Here’s an example:
User-Agent: Awesome-Dental-App v1
If you don’t include a valid User-Agent header you’ll receive a 403 Forbidden response.
Authentication via OAuth
The Dentally API uses OAuth2 for authentication. OAuth2 is a protocol that lets external apps request authorization to private details in a practice’s Dentally account without getting their password.
All developers need to register their application before getting started. A registered OAuth application is assigned a unique Client ID and Client Secret. The Client Secret should not be shared.
Create an Application
To create an application that has access to the Dentally API, login to Dentally and select Settings > Developer > Apps
Request Authorization
DEFINITION
GET https://api.dentally.co/oauth/authorize
EXAMPLE PARAMETERS
{
"client_id": "f4cdfd450cc1139fb71d8dbf1342fb512e5e9ca507be6a79cf454fbe3a75fd73",
"redirect_uri": "https://example.com/callback",
"scope": "appointment patient:read patient:update user:read",
"response_type": "code",
"state": "914e62ad35e7aa8a14f46bf8aff9194b24b7f6d7c5a434a7"
}
Parameters
| client_id: string, required |
The client ID you received from Dentally when you registered your application |
| redirect_uri: string, required |
The URL in your app where users will be sent after authorization |
| response_type: string, required |
This must always be set to code |
| scope: string, required |
A list of scopes separated by a single space |
| state: string, optional |
An unguessable random string. It is used to protect against cross-site request forgery attacks |
Get a Token
If the user accepts your request, Dentally redirects back to your site with a temporary code in a code parameter as well as the state you provided in the previous step in a state parameter. If the states don’t match, the request has been created by a third party and the process should be aborted. You can exchange this temporary code for a token which will allow access to the API. Temporary codes are only valid for 10 minutes and API tokens are valid for a rolling 2 week period. If you don’t use your access token for a period longer than 2 weeks then it will automatically expire and you will have to request a new one.
DEFINITION
POST https://api.dentally.co/oauth/token
EXAMPLE RESPONSE
{
"access_token": "b3b2c56773ee72a90ab72ed4eb5a84edd48775380b81ab644f68441fdccceced",
"token_type": "bearer"
}
Parameters
| client_id: string, required |
The client ID you received from Dentally when you registered your application. |
| client_secret: string, required |
The client secret you received from Dentally when you registered your application. |
| redirect_uri: string, required |
The URL in your app where users will be sent after authorization. |
| code: string, required |
The code you received when you requested authorization |
| grant_type: string, required |
This must always be set to authorization_code. |
Use the Token
The access token allows you to make requests to the API on a behalf of a user.
GET https://api.dentally.co/user?access_token=...
The token can be passed as query param as shown above, however a cleaner approach is to include it in the Authorization header.
Authorization: Bearer ACCESS_TOKEN
Other Authentication Methods
While the API provides additional methods for authentication, we strongly recommend using OAuth for production applications. The other methods provided are intended to be used for scripts or testing (i.e., cases where full OAuth would be overkill).
Generate a Token
API tokens can also be generated in the from the developer dashboard with Dentally. To generate an access token, go to Settings > Developer > Tokens and select “Generate new token”. Here you’ll be able to select the scopes for the token and create it. Make sure to take a copy of your token after doing so as you won’t be able to see it again once you leave the page.
You should treat this token as if it were your password and keep it secure at all times. You can revoke your token at any point through the Developer Dashboard.
Use the Token
The access token allows you to make requests to the API on a behalf of a user.
GET https://api.dentally.co/user?access_token=...
The token can be passed as query param as shown above, however a cleaner approach is to include it in the Authorization header.
Authorization: Bearer ACCESS_TOKEN
Accounts
The account object
Accounts belong to patients and each patient in Dentally has their own account
EXAMPLE RESPONSE
{
"account": {
"id": 10,
"current_balance": "200.0",
"opening_balance": "10.0",
"patient_id": 16,
"patient_name": "Sergio Aguero",
"planned_nhs_treatment_value": "50.0",
"planned_private_treatment_value": "40.0"
}
}
ATTRIBUTES
| id: integer |
The ID of the account |
| current_balance: string |
The current balance of the account |
| opening_balance: string |
The opening balance for the account |
| patient_id: integer |
The ID of the patient the account belongs to |
| patient_name: string |
The first and last name of the patient the account belongs to |
| planned_nhs_treatment_value: string |
The total value of planned nhs treatment associated to the account |
| planned_private_treatment_value: string |
The total value of planned private treatment associated to the account |
Get a single account
Retrieves the details of an account
DEFINITION
GET https://api.dentally.co/v1/accounts/{ACCOUNT_ID}
EXAMPLE REQUEST
curl https://api.dentally.co/v1/accounts/10
Parameters
| id: | required |
Returns
The existing account object
EXAMPLE RESPONSE
{
"account": {
"id": 10,
"current_balance": "200.0",
"opening_balance": "10.0",
"patient_id": 16,
"patient_name": "Sergio Aguero",
"planned_nhs_treatment_value": "50.0",
"planned_private_treatment_value": "40.0"
}
}
List all accounts
Returns a list of accounts.
DEFINITION
GET https://api.dentally.co/v1/accounts?{state, patient_id}
EXAMPLE REQUEST
curl https://api.dentally.co/v1/accounts?state=credit
Parameters
| state: string, optional |
You can filter by the state of the account wither it is in credit OR debit |
| patient_id: string, optional |
The ID of the patient that the account is assigned to |
EXAMPLE RESPONSE:
{
"accounts": [
{
"id": 10,
"current_balance": "200.0",
"opening_balance": "10.0",
"patient_id": 16,
"patient_name": "Sergio Aguero",
"planned_nhs_treatment_value": "50.0",
"planned_private_treatment_value": "40.0"
},
{...},
{...}
],
"meta": {
"total": 3,
"total_nhs": "200.00",
"total_private": "400.00",
"current_page": 1,
"total_balance": "854.04"
}
}
Returns
Returns a list of accounts that match the query. The response includes a metadata object which contains the page number, the total number of accounts, the total value of planned nhs treatments, the total value of planned private treatments and the total balance.
Acquisition sources
The acquisition source object
EXAMPLE RESPONSE
{
"acquisition_source": {
"id": "abdcdeb5-ebe4-4629-a375-15e1506d3961",
"active": true,
"name": "Flyer",
"notes": "Posted Aug 2023"
}
}
ATTRIBUTES
| id: integer |
The source’s ID |
| active: boolean |
If the source is active true or has been archived false |
| name: string |
The name of the source |
| notes: string |
Notes related to the source |
List all acquisition sources
Returns a list of all the practice’s acquisition sources
DEFINITION
GET https://api.dentally.co/v1/acquisition_sources
EXAMPLE REQUEST
curl https://api.dentally.co/v1/acquisition_sources
EXAMPLE RESPONSE:
{
"acquisition_sources": [
{
"id": "abdcdeb5-ebe4-4629-a375-15e1506d3961",
"active": true,
"name": "Flyer",
"notes": "Posted Aug 2023"
},
{...},
{...}
],
"meta": {
"total": 3,
"page": 1
}
}
Returns
Returns a list of acquisition sources. The response includes a metadata object which contains the page number that was returned as well as the total number of sources. The sources are returned ordered by name.
Appointment Cancellation Reasons
The appointment cancellation reasons object
EXAMPLE RESPONSE
{
"appointment_cancellation_reasons": {
"id": "fcafb582-0434-4eb8-b990-01f5fa12904d",
"archived": false,
"created_at": "2020-03-23T15:58:49.331+00:00",
"reason": "Patient - Cancelled",
"reason_type": "cancelled",
"updated_at": "2020-03-23T15:58:49.331+00:00"
}
}
ATTRIBUTES
| id: string |
The ID of the appointment cancellation reason |
| archived: boolean |
Indicates if this appointment cancellation reason has been archived or not. Default is false |
| reason: string |
The name of this appointment cancellation reason. |
| reason_type: string |
The type of cancellation reason this is. Default is "cancelled" |
| created_at: datetime |
The date and time the appointment cancellation reason was created on |
| updated_at: datetime |
The date and time the appointment cancellation reason was updated on |
List all appointment cancellation reasons
Returns a list of all the practice’s appointment cancellation reasons
DEFINITION
GET https://api.dentally.co/v1/appointment_cancellation_reasons{created_after, created_before, updated_after, updated_before}
EXAMPLE REQUEST
curl https://api.dentally.co/v1/appointment_cancellation_reasons?sort_by=created_at&sort_direction=asc
EXAMPLE RESPONSE:
{
"appointment_cancellation_reasons": [
{
"id": "fcafb582-0434-4eb8-b990-01f5fa12904d",
"archived": false,
"created_at": "2020-03-23T15:58:49.331+00:00",
"reason": "Patient - Cancelled",
"reason_type": "cancelled",
"updated_at": "2020-03-23T15:58:49.331+00:00"
},
{...},
{...}
],
"meta": {
"total": 14,
"current_page": 1,
"total_pages": 1
}
}
Parameters
| created_after: datetime, optional |
Returns all Appointment Cancellation Reasons that were created after this time |
| created_before: datetime, optional |
Returns all Appointment Cancellation Reasons that were created before this time |
| updated_after: datetime, optional |
Returns all Appointment Cancellation Reasons that have been updated since this time |
| updated_before: datetime, optional |
Returns all Appointment Cancellation Reasons that have been updated since before this time |
Sorting
This resource accepts sort_by and sort_direction parameters for any attribute.
Returns
Returns a list of appointment cancellation reasons.
The response includes a metadata object which contains the page number that was returned, the total number of pages, as well as the total number of reasons.
By default, the reasons are returned ordered by the reason attribute.
Appointments
The appointment object
Appointments belong to a practice and can be used for patient appointments, lunch breaks etc.
EXAMPLE RESPONSE
{
"appointment": {
"id": 2,
"appointment_cancellation_reason_id": null,
"arrived_at": null,
"booked_via_api": false,
"cancelled_at": null,
"completed_at": null,
"confirmed_at": null,
"did_not_attend_at": null,
"duration": 15,
"finish_time": "2013-11-05T09:40:00.000+00:00",
"in_surgery_at": null,
"metadata": {
},
"notes": "",
"patient_name": "Harrison Daniel",
"patient_id": 1001,
"patient_image_url": "https://www.gravatar.com/avatar/b8a70ced4a175b0306a7cfb397ed714d.jpg?&r=pg&d=identicon&s=190",
"payment_plan_id": 1,
"pending_at": "2013-11-05T16:09:06.000+00:00",
"practitioner_id": 1,
"reason": "Exam",
"room_id": "04b2db45-455a-42f7-b9ce-99fa6b0c741b",
"start_time": "2013-11-05T09:25:00.000+00:00",
"state": "Pending",
"treatment_description": null,
"user_id": 1
}
}
ATTRIBUTES
| id: integer |
The ID of the appointment |
| appointment_cancellation_reason_id: string |
The ID of the cancellation reason assigned to this appointment, if any. |
| arrived_at: datetime |
When the appointment state was set to Arrived |
| booked_via_api: boolean |
If the appointment was booked using a service that uses the API |
| cancelled_at: datetime |
When the appointment state was set to Cancelled |
| completed_at: datetime |
When the appointment state was set to Completed |
| confirmed_at: datetime |
When the appointment state was set to Confirmed |
| did_not_attend_at: datetime |
When the appointment state was set to Did not attend |
| duration: integer |
The length of the appointment in minutes |
| finish_time: datetime |
The date and time the appointment was set to finish |
| in_surgery_at: datetime |
When the appointment state was set to In surgery |
| metadata: hash |
A set of key/value pairs that you can attach to an appointment. It can be useful for storing additional information about the appointment in a structured format. |
| notes: string |
Any notes that were added to the appointment |
| patient_name: string |
The name of the patient the appointment is for |
| patient_id: integer |
The ID of the patient the appointment is for |
| patient_image_url: string |
The address for the image associated to the patient the appointment is for |
| payment_plan_id: integer |
The ID of the payment plan the patient belongs to |
| pending_at: string |
When the appointment state was set to Pending |
| practitioner_id: integer |
The ID of the practitioner assigned to the appointment |
| reason: string |
The reason for the appointment. Will be one of Exam, Scale & Polish, Exam + Scale & Polish, Continuing Treatment, Emergency, Review or Other |
| room_id: string, optional |
The ID of the room the appointment is allocated |
| start_time: datetime |
The date and time the appointment was set to start |
| state: string |
The current state of the appointment. This can be Pending, Confirmed, Arrived, In surgery, Completed, Cancelled or Did not attend |
| treatment_description: string |
A short summary of treatment performed at that appointment |
| user_id: integer |
The ID of the user who created the appointment |
Create an appointment
Creates a new appointment
DEFINITION
POST https://api.dentally.co/v1/appointments
EXAMPLE REQUEST
curl --include \
--request POST \
--header "Content-Type: application/json" \
--data-binary '{
"appointment": {
"start_time": "2015-01-02T13:00:00.000Z",
"finish_time": "2015-01-02T13:10:00.000Z",
"patient_id": 1,
"practitioner_id": 1,
"reason": "Exam"
}
}' \
https://api.dentally.co/v1/appointments
Parameters
Parameters must be wrapped by an appointment object
| start_time: datetime, required |
The start time of the appointment |
| finish_time: datetime, required |
The finish time of the appointment |
| practitioner_id: integer, required |
The ID of the practitioner |
| reason: string, required |
The reason for the appointment Must be one of Exam, Scale & Polish, Exam + Scale & Polish, Continuing Treatment, Emergency, Review or Other |
| patient_id: integer, optional |
The ID of the patient |
| state: string, optional |
The state of the appointment. Must be one of Pending, Confirmed, Arrived, In surgery, Completed, Cancelled or Did not attend. Defaults to Pending |
| notes: string, optional |
Notes specific to the appointment |
| metadata: hash, optional |
A set of key/value pairs that you can attach to an appointment. It can be useful for storing additional information about the appointment in a structured format. |
| force_changes: boolean, optional |
Setting this to true suppresses any double booking errors and allow the appointment to be double booked |
EXAMPLE RESPONSE
{
"appointment": {
"id": 14493,
"appointment_cancellation_reason_id": null,
"arrived_at": null,
"cancelled_at": null,
"completed_at": null,
"confirmed_at": null,
"did_not_attend_at": null,
"duration": 10,
"finish_time": "2015-01-02T13:10:00.000+00:00",
"in_surgery_at": null,
"metadata": {
},
"notes": null,
"patient_name": "Liza Stafford",
"patient_id": 1,
"patient_image_url": "https://www.gravatar.com/avatar/d80c726c2a3a8f426acaa06e16b05b09.jpg?&r=pg&d=identicon&s=190",
"payment_plan_id": 1,
"pending_at": "2015-01-02T13:42:14.424+00:00",
"practitioner_id": 1,
"reason": "Exam",
"start_time": "2015-01-02T13:00:00.000+00:00",
"state": "Pending",
"treatment_description": null,
"user_id": 1
}
}
Returns
The newly created appointment object
Get a single appointment
Retrieves the details of an existing appointment
DEFINITION
GET https://api.dentally.co/v1/appointments/{APPOINTMENT_ID}
EXAMPLE REQUEST
curl https://api.dentally.co/v1/appointments/14493
Parameters
| id: | required |
EXAMPLE RESPONSE
{
"appointment": {
"id": 14493,
"appointment_cancellation_reason_id": null,
"arrived_at": null,
"cancelled_at": null,
"completed_at": null,
"confirmed_at": null,
"did_not_attend_at": null,
"duration": 10,
"finish_time": "2015-01-02T13:10:00.000+00:00",
"in_surgery_at": null,
"metadata": {
},
"notes": null,
"patient_name": "Liza Stafford",
"patient_id": 1,
"patient_image_url": "https://www.gravatar.com/avatar/d80c726c2a3a8f426acaa06e16b05b09.jpg?&r=pg&d=identicon&s=190",
"payment_plan_id": 1,
"pending_at": "2015-01-02T13:42:14.424+00:00",
"practitioner_id": 1,
"reason": "Exam",
"room_id": "04b2db45-455a-42f7-b9ce-99fa6b0c741b",
"start_time": "2015-01-02T13:00:00.000+00:00",
"state": "Pending",
"treatment_description": null,
"user_id": 1
}
}
Returns
The existing appointment object
Edit an appointment
Updates an existing appointment. Updating the appointment state will automatically update the corresponding timestamp.
DEFINITION
PUT/PATCH https://api.dentally.co/v1/appointments/{APPOINTMENT_ID}
EXAMPLE REQUEST
curl --include \
--request PUT \
--header "Content-Type: application/json" \
--data-binary '{
"appointment": {
"finish_time": "2015-01-02T13:15:00.000Z"
}
}' \
https://api.dentally.co/v1/appointments/14493
Parameters
Parameters must be wrapped by an appointment object
| start_time: datetime, optional |
The start time of the appointment |
| finish_time: datetime, optional |
The finish time of the appointment |
| practitioner_id: integer, optional |
The ID of the practitioner |
| reason: string, optional |
The reason for the appointment. Must be one of Exam, Scale & Polish, Exam + Scale & Polish, Continuing Treatment, Emergency, Review or Other |
| patient_id: integer, optional |
The ID of the patient |
| state: string, optional |
The state of the appointment. Must be one of Pending, Confirmed, Arrived, In surgery, Completed, Cancelled or Did not attend. Defaults to Pending |
| metadata: hash, optional |
A set of key/value pairs that you can attach to an appointment. It can be useful for storing additional information about the appointment in a structured format. |
| notes: string, optional |
Notes specific to the appointment |
| force_changes: boolean, optional |
Setting this to true suppresses any double booking errors and allow the appointment to be double booked |
EXAMPLE RESPONSE
{
"appointment": {
"id": 14493,
"appointment_cancellation_reason_id": null,
"arrived_at": null,
"cancelled_at": null,
"completed_at": null,
"confirmed_at": null,
"did_not_attend_at": null,
"duration": 15,
"finish_time": "2015-01-02T13:15:00.000+00:00",
"in_surgery_at": null,
"metadata": {
},
"notes": null,
"patient_name": "Liza Stafford",
"patient_id": 1,
"patient_image_url": "https://www.gravatar.com/avatar/d80c726c2a3a8f426acaa06e16b05b09.jpg?&r=pg&d=identicon&s=190",
"payment_plan_id": 1,
"pending_at": "2015-01-02T13:42:14.424+00:00",
"practitioner_id": 1,
"reason": "Exam",
"start_time": "2015-01-02T13:00:00.000+00:00",
"state": "Pending",
"treatment_description": null,
"user_id": 1
}
}
Returns
The updated appointment object
Delete an appointment
Deletes an appointment. This should only be used when you want to remove an appointment. To cancel an appointment simply set the state of the appointment to Cancelled instead
DEFINITION
DELETE https://api.dentally.co/v1/appointments/{APPOINTMENT_ID}
EXAMPLE REQUEST
curl --include \
--request DELETE \
https://api.dentally.co/v1/appointments/14493
Parameters
| id: | required |
Returns
Returns a 204 response
List all appointments
DEFINITION
GET https://api.dentally.co/v1/appointments?{on, before, after, practitioner_id, patient_id, site_id, state, updated_after}
EXAMPLE REQUEST
curl https://api.dentally.co/v1/appointments?on=2015-01-02
EXAMPLE RESPONSE:
{
"appointments": [
{
"id": 14493,
"appointment_cancellation_reason_id": null,
"arrived_at": null,
"cancelled_at": null,
"completed_at": null,
"confirmed_at": null,
"did_not_attend_at": null,
"duration": 15,
"finish_time": "2015-01-02T13:15:00.000+00:00",
"in_surgery_at": null,
"metadata": {
},
"notes": null,
"patient_name": "Liza Stafford",
"patient_id": 1,
"room_id": "04b2db45-455a-42f7-b9ce-99fa6b0c741b",
"patient_image_url": "https://www.gravatar.com/avatar/d80c726c2a3a8f426acaa06e16b05b09.jpg?&r=pg&d=identicon&s=190",
"payment_plan_id": 1,
"pending_at": "2015-01-02T13:42:14.424+00:00",
"practitioner_id": 1,
"reason": "Exam",
"start_time": "2015-01-02T13:00:00.000+00:00",
"state": "Pending",
"treatment_description": null,
"user_id": 1,
"created_at": "2015-01-02T13:00:00.000+00:00",
"updated_at": "2015-01-02T13:00:00.000+00:00"
},
{...},
{...}
],
"meta": {
"total": 3,
"page": 1
}
}
Returns a list of existing appointments
Parameters
Parameters are not mutually exclusive and can be combined to build up complex queries
| on: datetime, optional |
On a date |
| before: datetime, optional |
Before a date |
| after: datetime, optional |
After a date |
| updated_after: datetime, optional |
Only those modified on or after this time |
| practitioner_id: string, optional |
With a practitioner |
| patient_id: string, optional |
With a patient |
| room_id: string, optional |
With a room |
| site_id: string, optional |
For a practitioner’s site |
| state: string, optional |
With a state |
| cancelled: boolean, optional |
Set to true to include cancelled appointments or appointments that have a “did not attend” date. Defaults to false |
Returns
Returns a list of matching appointments. The response includes a metadata object which contains the page number that was returned as well as the total number of matching appointments. The appointments are returned in the order of their start time
Appointment availability
DEFINITION
GET https://api.dentally.co/v1/appointments/availability?{start_time,finish_time,duration,practitioner_ids}
EXAMPLE REQUEST
curl "https://api.dentally.co/v1/appointments/availability?practitioner_ids%5B%5D=1&duration=5&start_time=2015-01-07T12:00:11+00:00&finish_time=2015-02-06T12:00:11+00:00"
EXAMPLE RESPONSE:
{
"availability": [
{
"start_time": "2015-01-07T12:00:00.000+00:00",
"finish_time": "2015-01-07T14:20:00.000+00:00",
"available_duration": 140
},
{
"start_time": "2015-01-07T14:40:00.000+00:00",
"finish_time": "2015-01-07T17:00:00.000+00:00",
"available_duration": 140
},
{...}
],
"meta": {
"page": 1
}
}
Returns a list of available time slots
Parameters
| start_time: datetime, required |
A time to start searching from. Must be in the future |
| finish_time: datetime, required |
A time to search until. Must be in the future & after the start time |
| practitioner_ids: array, required |
An array of integers containing the IDs of the practitioners |
| duration: integer, optional |
The minimum duration required in minutes. If not supplied then this falls back to the practice’s minimum appointment duration (usually 5 minutes) |
| page: integer, optional |
The page to be returned |
| per_page: integer, optional |
The number of items to be returned per page (maximum is 20) |
Returns
Returns a list of available time slots matching the requested criteria
| start_time: datetime |
The start of the available period |
| finish_time: datetime |
The end of the available period |
| available_duration: integer |
The duration of the available period in minutes |
Appointment reasons
DEFINITION
GET https://api.dentally.co/v1/appointment_reasons/?{deleted}
EXAMPLE REQUEST
curl "https://api.dentally.co/v1/appointment_reasons?deleted=false"
EXAMPLE RESPONSE:
{
"appointment_reasons": [
{
"id": "7a0a4a71-ecd0-4b0b-81d5-e1739aee88ba",
"colour": "#ad00fc",
"deleted": false,
"exam": false,
"hygiene": false,
"position": 50,
"reason": "NOT WORKING"
},
{
"id": "430c6234-4f3d-424d-b1ea-a4d1bc728d36",
"colour": "#25B0E6",
"deleted": false,
"exam": false,
"hygiene": false,
"position": 49,
"reason": "LUNCH"
}
],
"meta": {
"total": 50,
"page": 1
}
}
Returns a list of appointment reasons
Parameters
| colour: string |
The background colour of the diary listing for the appointment |
| deleted: boolean |
Whether the appointment reason is visible or not |
| exam: boolean |
If the appointment is a dental appointment, default false |
| hygiene: boolean |
If the appointment is a hygienist appointment, default false |
| position: integer |
Position of the appointment reason in the appointment reason list |
| reason: string, optional |
The reason for the appointment |
Contracts
The contract object
EXAMPLE RESPONSE
{
"contract": {
"id": "652e5e2f-1697-417e-8feb-1ecd832bd42d",
"active": true,
"contract_number": "12345678910",
"end_date": "2016-01-19",
"name": "Contract 1",
"nhs_location_id": "123456",
"nhs_site_id": "654321",
"notes": "This is a note about a contract",
"pds_plus": false,
"site_id": "e1d854af-15db-4482-8e29-39e74a6c7f75",
"start_date": "2015-01-19",
"target": "1000",
"uda_value": "3",
"uoa_target": "300",
"uoa_value": "5",
"created_at": "2015-01-18T14:08:16.523+00:00",
"updated_at": "2017-01-03T20:38:44.896+00:00"
}
}
ATTRIBUTES
| id: string |
The ID of the contract |
| active boolean |
Indicates the contract is active |
| contract_number string |
The contract number assigned by the NHS |
| end_date date |
The date the contract is due to end |
| name string |
The user assigned name (easy identifier) |
| nhs_location_id string |
The NHS location number of the premises where the work is performed |
| nhs_site_id string |
The NHS site id attributed to the contract |
| notes string |
The user defined meta description about the contract |
| pds_plus boolean |
Indicates the contract is PDS plus |
| site_id: string |
The ID of the site that the contract belongs to |
| start_date date |
The date the contract is due to end |
| target string |
The UDA target of the contract |
| uda_value string |
The monetary value of each UDA, set out by the contract |
| uoa_target string |
The UOA target of the contract |
| uoa_value string |
The monetary value of each UOA, set out by the contract |
| created_at: datetime |
The date and time the contract was created |
| updated_at: datetime |
The date and time the contract was updated |
Get a single contract
Retrieves the details of an existing contract
DEFINITION
GET https://api.dentally.co/v1/contracts/{CONTRACT_ID}
EXAMPLE REQUEST
curl https://api.dentally.co/v1/contracts/652e5e2f-1697-417e-8feb-1ecd832bd42d
Parameters
| id: | required |
EXAMPLE RESPONSE
{
"contract": {
"id": "652e5e2f-1697-417e-8feb-1ecd832bd42d",
"active": true,
"contract_number": "12345678910",
"end_date": "2016-01-19",
"name": "Contract 1",
"nhs_location_id": "123456",
"nhs_site_id": "654321",
"notes": "This is a note about a contract",
"pds_plus": false,
"site_id": "e1d854af-15db-4482-8e29-39e74a6c7f75",
"start_date": "2015-01-19",
"target": "1000",
"uda_value": "3",
"uoa_target": "300",
"uoa_value": "5",
"created_at": "2015-01-18T14:08:16.523+00:00",
"updated_at": "2017-01-03T20:38:44.896+00:00"
}
}
Returns
A contract object
List all contracts
Returns a list of all contracts
DEFINITION
GET https://api.dentally.co/v1/contracts{active, site_id}
EXAMPLE REQUEST
curl https://api.dentally.co/v1/contracts?active=true
EXAMPLE RESPONSE:
{
"contracts": [
{
"id": "652e5e2f-1697-417e-8feb-1ecd832bd42d",
"active": true,
"contract_number": "12345678910",
"end_date": "2016-01-19",
"name": "Contract 1",
"nhs_location_id": "123456",
"nhs_site_id": "654321",
"notes": "This is a note about a contract",
"pds_plus": false,
"site_id": "e1d854af-15db-4482-8e29-39e74a6c7f75",
"start_date": "2015-01-19",
"target": "1000",
"uda_value": "3",
"uoa_target": "300",
"uoa_value": "5",
"created_at": "2015-01-18T14:08:16.523+00:00",
"updated_at": "2017-01-03T20:38:44.896+00:00"
},
{...},
{...}
],
"meta": {
"total": 3,
"page": 1
}
}
Parameters
| active boolean, optional |
Returns contracts that are active or not. |
| site_id string, optional |
Contracts assigned to a specific site |
Sorting
The following columns can be used to sort.
| created_at | ascending or descending |
Returns
Returns a list of contracts that match the query.
Custom Fields
List all custom fields
Returns a list of all custom fields questions used in this practice. This conforms to the questions asked in the custom fields, on Treatment Plan Items and Patients. The custom field’s answers will be found in the custom_fields JSON attribute found in treatment_plan_item and patient endpoints where the field_id in the custom_fields attribute in those endpoints corresponds to the IDs of this record.
DEFINITION
GET https://api.dentally.co/v1/custom_fields?{active, updated_after, updated_before}
EXAMPLE REQUEST
curl https://api.dentally.co/v1/custom_fields?active=true&update_after=2021-08-21&updated_before=2021-08-25
Parameters
| updated_after datetime |
Request entries that have been modified on or after the date specified |
| updated_before datetime |
Request entries that have been modified on or before the date specified |
| active boolean |
Filter to entries that are either active or not active |
EXAMPLE RESPONSE:
{
"custom_fields": [
{
"id": "5427b8d4-eacd-4e6a-8a4a-f2a37979425c",
"active": true,
"created_at": "2020-05-19T08:32:36.008+01:00",
"updated_at": "2020-05-19T08:32:36.008+01:00",
"customizable_id": "a243bf5f-72a8-4e52-9fd7-62b729e8544c",
"customizable_type": "Treatment",
"default_value": null,
"description": null,
"name": "Registration Status",
"options": [
{
"name": "Registered at the practice",
"position": 0
},
{
"name": "New patient",
"position": 1
},
{
"name": "Emergency referral",
"position": 2
}
],
"position": 0,
"type": "enum",
"width": 5
}
],
"meta": {
"total": 1,
"current_page": 1,
"total_pages": 1
}
}
Returns
Returns a list of custom fields created in that practice.
Get a single custom field
Retrieves the details of a custom field
DEFINITION
GET https://api.dentally.co/v1/custom_fields/{CUSTOM_FIELD_ID}
EXAMPLE REQUEST
curl https://api.dentally.co/v1/custom_fields/a5ee8c65-84e9-49a0-a7b5-cb136e65007c
Parameters
| id: | required |
Returns
The existing custom field object
EXAMPLE RESPONSE
{
"custom_field": {
"id": "5427b8d4-eacd-4e6a-8a4a-f2a37979425c",
"active": true,
"created_at": "2020-05-19T08:32:36.008+01:00",
"updated_at": "2020-05-19T08:32:36.008+01:00",
"customizable_id": "a243bf5f-72a8-4e52-9fd7-62b729e8544c",
"customizable_type": "Treatment",
"default_value": null,
"description": null,
"name": "Registration Status",
"options": [
{
"name": "Registered at the practice",
"position": 0
},
{
"name": "New patient",
"position": 1
},
{
"name": "Emergency referral",
"position": 2
}
],
"position": 0,
"type": "enum"
}
}
The custom field object
Custom Fields are optional fields that can be included on the Patient information screen and/or the Treatment screen to gather additional information for that patient or treatment. Custom fields can be customized as several different UI components, such as a text box with a label, a checkmark, an option list and so on. When a treatment is applied, or a Patient is edited, these custom fields are displayed and the user can interact with them to provide additional ad-hoc data on the treatment or patient that requires completion.
EXAMPLE RESPONSE
{
"custom_field": {
"id": "5427b8d4-eacd-4e6a-8a4a-f2a37979425c",
"active": true,
"created_at": "2020-05-19T08:32:36.008+01:00",
"updated_at": "2020-05-19T08:32:36.008+01:00",
"customizable_id": "a243bf5f-72a8-4e52-9fd7-62b729e8544c",
"customizable_type": "Treatment",
"default_value": null,
"description": null,
"name": "Registration Status",
"options": [
{
"name": "Registered at the practice",
"position": 0
},
{
"name": "New patient",
"position": 1
},
{
"name": "Emergency referral",
"position": 2
}
],
"position": 0,
"type": "enum",
}
}
ATTRIBUTES
| id uuid |
UUID of the record |
| active boolean |
Marked whether the field is active |
| created_at timestamp |
When the custom field was created |
| updated_at timestamp |
When the custom field was last updated |
| customizable_id UUID |
UUID of the entity the custom field is attached to |
| customizable_type string |
The name of the entity the custom field is attached to (Treatment or Patient) |
| default_value string |
The default value of the custom field, if any |
| description string |
The description of the custom field |
| name string |
The name of the custom field |
| options array |
The options for the custom field, if any, such as checkbox entries or options in an option group, etc |
| position integer |
The position of the custom field |
| type string |
The type of the custom field, can be one of: checkbox, enum, number, text, textarea, title, spacer |
Fees
The fee object
A fee represents the costs and durations of a treatment within a payment plan.
EXAMPLE RESPONSE
{
"fee": {
"id": "a5ee8c65-84e9-49a0-a7b5-cb136e65007c",
"payment_plan_id": 1234,
"treatment_id": 5678,
"multiple_pricing": true,
"duration_one": 10,
"duration_two": 20,
"duration_three": 30,
"duration_four": 40,
"duration_five": 50,
"price_one": "10.00",
"price_two": "20.00",
"price_three": "30.00",
"price_four": "40.00",
"price_five": "50.00"
}
}
ATTRIBUTES
| id: uuid |
The ID of the fee |
| payment_plan_id integer |
The associated payment plan |
| treatment_id integer |
The associated treatment |
| multiple_pricing boolean |
whether to set the prices and durations of multiple treatments individually. If true, use price_two and duration_two etc in calculations. If false, use price_one and duration_one regardless of the number of treatments. |
| duration_one integer |
The duration in minutes of treatment on one tooth or surface. If multiple_pricing is false, this is the price for any number of treatments. |
| duration_two integer |
The duration in minutes of treatment on two teeth or surfaces. |
| duration_three integer |
The duration in minutes of treatment on three teeth or surfaces. |
| duration_four integer |
The duration in minutes of treatment on four teeth or surfaces. |
| duration_five integer |
The duration in minutes of treatment on five teeth or surfaces. |
| price_one string |
The price of treatment for one tooth or surface. If multiple_pricing is false, this is the price for any number of treatments. |
| price_two string |
The price of treatment for two teeth or surfaces. |
| price_three string |
The price of treatment for three teeth or surfaces. |
| price_four string |
The price of treatment for four teeth or surfaces. |
| price_five string |
The price of treatment for five teeth or surfaces. |
Get a single fee
Retrieves the details of a fee
DEFINITION
GET https://api.dentally.co/v1/fees/{FEE_ID}
EXAMPLE REQUEST
curl https://api.dentally.co/v1/fees/a5ee8c65-84e9-49a0-a7b5-cb136e65007c
Parameters
| id: | required |
Returns
The existing fee object
EXAMPLE RESPONSE
{
"fee": {
"id": "a5ee8c65-84e9-49a0-a7b5-cb136e65007c",
"payment_plan_id": 1234,
"treatment_id": 5678,
"multiple_pricing": true,
"duration_one": 10,
"duration_two": 20,
"duration_three": 30,
"duration_four": 40,
"duration_five": 50,
"price_one": "10.00",
"price_two": "20.00",
"price_three": "30.00",
"price_four": "40.00",
"price_five": "50.00"
}
}
List fees
Returns a list of existing fees. The request must filter by either payment_plan_id or treatment_id.
DEFINITION
GET https://api.dentally.co/v1/fees
EXAMPLE REQUEST
curl https://api.dentally.co/v1/fees?payment_plan_id=1234
curl https://api.dentally.co/v1/fees?treatment_id=5678
Parameters
| payment_plan_id: integer, optional |
Returns all fees that have that payment_plan_id. Either this or treatment_id is required. |
| treatment_id: integer, optional |
Returns all fees that have that treatment_id. Either this or payment_plan_id is required. |
EXAMPLE RESPONSE:
{
"fees": [
{
"id": "a5ee8c65-84e9-49a0-a7b5-cb136e65007c",
"payment_plan_id": 1234,
"treatment_id": 5678,
"multiple_pricing": true,
"duration_one": 10,
"duration_two": 20,
"duration_three": 30,
"duration_four": 40,
"duration_five": 50,
"price_one": "10.00",
"price_two": "20.00",
"price_three": "30.00",
"price_four": "40.00",
"price_five": "50.00"
}
]
}
Returns
Returns a list of fees that match the query. The response includes a metadata object which contains the page number that was returned as well as the total number of fees that match the query. The fees are returned in id order.
Edit a fee
Updates an existing fee
DEFINITION
PUT/PATCH https://api.dentally.co/v1/fees/{FEE_ID}
EXAMPLE REQUEST
curl --include \
--request PUT \
--header "Content-Type: application/json" \
--data-binary '{
"fee": {
"price_one": "20.00"
}
}' \
https://api.dentally.co/v1/fees/a5ee8c65-84e9-49a0-a7b5-cb136e65007c
Parameters
Parameters must be wrapped by a fee object
| multiple_pricing boolean, optional |
whether to set the prices and durations of multiple treatments individually. If true, use price_two and duration_two etc in calculations. If false, use price_one and duration_one regardless of the number of treatments. |
| duration_one integer, optional |
The duration in minutes of treatment on one tooth or surface. If multiple_pricing is false, this is the price for any number of treatments. |
| duration_two integer, optional |
The duration in minutes of treatment on two teeth or surfaces. |
| duration_three integer, optional |
The duration in minutes of treatment on three teeth or surfaces. |
| duration_four integer, optional |
The duration in minutes of treatment on four teeth or surfaces. |
| duration_five integer, optional |
The duration in minutes of treatment on five teeth or surfaces. |
| price_one string, optional |
The price of treatment for one tooth or surface. If multiple_pricing is false, this is the price for any number of treatments. |
| price_two string, optional |
The price of treatment for two teeth or surfaces. |
| price_three string, optional |
The price of treatment for three teeth or surfaces. |
| price_four string, optional |
The price of treatment for four teeth or surfaces. |
| price_five string, optional |
The price of treatment for five teeth or surfaces. |
EXAMPLE RESPONSE
{
"fee": {
"id": "a5ee8c65-84e9-49a0-a7b5-cb136e65007c",
"payment_plan_id": 1234,
"treatment_id": 5678,
"multiple_pricing": true,
"duration_one": 10,
"duration_two": 20,
"duration_three": 30,
"duration_four": 40,
"duration_five": 50,
"price_one": "10.00",
"price_two": "20.00",
"price_three": "30.00",
"price_four": "40.00",
"price_five": "50.00"
}
}
Returns
The updated fee object
Invoices
The invoice object
An invoice belongs to a patient and has many invoice items.
EXAMPLE RESPONSE
{
"invoice": {
"id": 2043,
"amount": "11.12",
"amount_outstanding": "0.0",
"dated_on": "2018-02-05",
"due_on": "2018-02-12",
"footnote": "",
"nhs_amount": "11.12",
"paid": true,
"paid_on": "2018-02-05",
"payment_terms": "",
"reference": "01946",
"sent_at": null,
"created_at": "2018-02-05T14:12:00.607+00:00",
"updated_at": "2018-09-15T00:33:34.872+01:00",
"account_id": 2986,
"patient_id": 2986,
"site_id": "0fbff38e-3995-4d32-8db7-3b7aed9b35a3",
"user_id": 4985,
"invoice_items": [
{
"id": "b2cc52a7-f488-419b-b9ac-f3c2f989c78e",
"item_price": "0.0",
"name": "Routine Examination",
"nhs_charge": false,
"quantity": 1,
"total_price": "0.0",
"created_at": "2018-09-15T00:33:34.847+01:00",
"updated_at": "2018-09-15T00:33:34.847+01:00",
"invoice_id": 2043,
"practitioner_id": 4,
"sundry_id": null,
"treatment_plan_id": 3946,
"treatment_plan_item_id": 55296,
"user_id": null
}
]
}
}
ATTRIBUTES
| id: uuid |
The ID of the invoice |
| amount: integer |
The invoice amount |
| amount_outstanding: integer |
The outstanding amount |
| dated_on: datetime |
The date assigned to the invoice |
| due_on: datetime |
The date the invoice is due on |
| footnote: string |
Additional information on the invoice |
| nhs_amount: integer |
Any amount on the invoice specific to the NHS. Specific to NHS Scotland. |
| paid: boolean |
Whether the invoice has been marked as paid or not |
| paid_on: datetime |
The date the invoice was paid on |
| payment_terms: text |
Any terms related to the invoice |
| reference: string |
Reference for the invoice |
| sent_at: datetime |
The date and time the invoice was sent to the patient |
| created_at: datetime |
The date and time the invoice was created |
| account_id: uuid |
The ID of the account the invoice belongs to |
| patient_id: uuid |
The ID of the patient the invoice belongs to |
| site_id: uuid |
The ID of the site the invoice belongs to |
| user_id: uuid |
The ID of the user the invoice belongs to |
List all invoices
Returns a list of invoices
DEFINITION
GET https://api.dentally.co/v1/invoices?{account_id, dated_on_after, dated_on_before, patient_id}
EXAMPLE REQUEST
curl http://api.dentally.co/v1/invoices?dated_on_after=2016-01-05
Parameters
| site_id: uuid, optional |
The ID of the site the invoice belongs to |
| account_id: uuid, optional |
Invoices belonging to a specific account |
| patient_id: uuid, optional |
Invoices belonging to a specific patient |
| dated_on_after: date, optional |
After a date |
| dated_on_before: date, optional |
Before a date |
| updated_after: datetime, optional |
Returns all invoices that have been updated since this time |
| site_id: string, optional |
Invoices attributed to a specific site |
EXAMPLE RESPONSE:
{
"invoices": [
{
"id": 10253,
"amount": "11.4",
"amount_outstanding": "0.0",
"dated_on": "2019-05-10",
"due_on": "2019-05-17",
"footnote": "",
"nhs_amount": null,
"paid": true,
"paid_on": "2019-05-10",
"payment_terms": "",
"reference": "09944",
"sent_at": null,
"status": "new",
"created_at": "2019-05-10T08:41:27.934+01:00",
"updated_at": "2019-05-10T08:48:43.322+01:00",
"account_id": 637,
"patient_id": 637,
"site_id": "0fbff38e-3995-4d32-8db7-3b7aed9b35a3",
"user_id": 4983
}
],
"meta": {
"total": 1,
"current_page": 3,
}
}
Sorting
By default, this endpoint sorts on the dated_on attribute.
Alternatively, you can choose to sort by another attribute. The following columns can be used to sort.
| created_at | ascending or descending |
| updated_at | ascending or descending |
Returns
Returns a list of invoices that match the query.
Get a single invoice
Retrieves the details of an invoice
DEFINITION
GET https://api.dentally.co/v1/invoices/{INVOICE_ID}
EXAMPLE REQUEST
curl https://api.dentally.co/v1/invoices/10
Parameters
| id: | required |
Returns
The existing invoice object
EXAMPLE RESPONSE
{
"invoice": {
"id": 2043,
"amount": "11.12",
"amount_outstanding": "0.0",
"dated_on": "2018-02-05",
"due_on": "2018-02-12",
"footnote": "",
"nhs_amount": "11.12",
"paid": true,
"paid_on": "2018-02-05",
"payment_terms": "",
"reference": "01946",
"sent_at": null,
"status": "new",
"created_at": "2018-02-05T14:12:00.607+00:00",
"updated_at": "2018-09-15T00:33:34.872+01:00",
"account_id": 2986,
"patient_id": 2986,
"site_id": "0fbff38e-3995-4d32-8db7-3b7aed9b35a3",
"user_id": 4985,
"invoice_items": [
{
"id": "b2cc52a7-f488-419b-b9ac-f3c2f989c78e",
"item_price": "0.0",
"name": "Routine Examination",
"nhs_charge": false,
"quantity": 1,
"total_price": "0.0",
"created_at": "2018-09-15T00:33:34.847+01:00",
"updated_at": "2018-09-15T00:33:34.847+01:00",
"invoice_id": 2043,
"practitioner_id": 4,
"sundry_id": null,
"treatment_plan_id": 3946,
"treatment_plan_item_id": 55296,
"user_id": null
}
]
}
}
Invoice Items
The invoice item object
An invoice item belongs to an invoice.
EXAMPLE RESPONSE
{
"invoice_items": [
{
"id": "b2cc52a7-f488-419b-b9ac-f3c2f989c78e",
"item_price": "0.0",
"name": "Routine Examination",
"nhs_charge": false,
"quantity": 1,
"total_price": "0.0",
"created_at": "2018-09-15T00:33:34.847+01:00",
"updated_at": "2018-09-15T00:33:34.847+01:00",
"invoice_id": 2043,
"practitioner_id": 4,
"sundry_id": null,
"treatment_plan_id": 3946,
"treatment_plan_item_id": 55296,
"user_id": null
}
]
}
ATTRIBUTES
| id: uuid |
The ID of the invoice item |
| item_price: integer |
The invoice item amount |
| name: string |
The name assigned to the invoice item |
| nhs_charge: integer |
Any amount on the invoice item specific to the NHS |
| quantity: integer |
The quantity of the invoice item, the total price is calculated by multiplying the quantity with the item price |
| total_price: integer |
The total price of the invoice item |
| created_at: datetime |
The date and time the invoice item was created on |
| updated_at: datetime |
The date and time the invoice item was updated on |
| invoice_id: uuid |
The ID of the invoice that the invoice item belongs to |
| practitioner_id: uuid |
The ID of the practitioner that the invoice item belongs to |
| sundry_id: uuid |
The ID of the sundry that belongs to the invoice item |
| treatment_plan_id: uuid |
The ID of the treatment plan that the invoice item belongs to |
| treatment_plan_item_id: uuid |
the ID of the treatment plan item that the invoice item belongs to |
| user_id: uuid |
The ID of the user that the invoice item belongs to |
List all invoice items
Returns a list of invoice items
DEFINITION
GET https://api.dentally.co/v1/invoice_items?{invoice_id, updated_after}
EXAMPLE REQUEST
curl http://api.dentally.co/v1/invoice_items?invoice_id=10&updated_after=2021-08-21T13:14:15.123Z
Parameters
| invoice_id: integer, optional |
Invoice Items belong to a specific invoice. |
| updated_after: datetime, optional |
Returns all invoices Items that have been updated since this time |
EXAMPLE RESPONSE:
{
"invoice_items": [
{
"id": "b2cc52a7-f488-419b-b9ac-f3c2f989c78e",
"item_price": "0.0",
"name": "Routine Examination",
"nhs_charge": false,
"quantity": 1,
"total_price": "0.0",
"created_at": "2018-09-15T00:33:34.847+01:00",
"updated_at": "2018-09-15T00:33:34.847+01:00",
"invoice_id": 2043,
"practitioner_id": 4,
"sundry_id": null,
"treatment_plan_id": 3946,
"treatment_plan_item_id": 55296,
"user_id": null
}
]
}
Returns
Returns a list of invoice items that list the query.
NHS Claims
The NHS claim object
EXAMPLE RESPONSE
{
"nhs_claim": {
"id": "5bd1f93d-bfa3-4402-a2fc-5880c5218815",
"awarded_uda": "12.0",
"approval_date": "2012-07-28",
"contract_id": "652e5e2f-1697-417e-8feb-1ecd832bd42d",
"claim_status": "complete",
"expected_uda": "12.0",
"patient_id": 1,
"practitioner_id": 1,
"sequence_number": 1420,
"site_id": "e1d854af-15db-4482-8e29-39e74a6c7f75",
"status_comments": "UDA 12.00 positive, Employment Support",
"treatment_plan_id": 1,
"ni_calculated_dentist_fee": "0.0",
"ni_calculated_patient_fee": "0.0",
"submitted_date": "2012-07-27",
"dentist_charge": "0.0",
"patient_charge": "53.9",
"scot_amount_authorised": "0.0",
"scot_amount_expected": "0.0",
"uda_band": "3",
"ortho": false,
"continuation_part_number": 1,
"created_at":"2012-05-8:54:05:00.000+00:00",
"updated_at":"2012-07-27T11:24:00.000+00:00"
}
}
ATTRIBUTES
| id: string |
The ID of the NHS claim |
| awarded_uda string |
The UDA awarded by the the NHS for the claim |
| approval_date date |
The date the claim was approved |
| contract_id string |
The ID of the contract the claim belongs to |
| claim_status string |
The status of the claim new, queued, submitted, completed, error, invalid, received, queried, withdrawn |
| expected_uda string |
The UDA value that is being claimed for |
| contract_id string |
The ID of the contract the claim belongs to |
| patient_id integer |
The ID of the patient the claim belongs to |
| practitioner_id integer |
The ID of the practitioner the claim belongs to |
| sequence_number integer |
The reference number of the claim used during NHS communications and presented to the user |
| site_id string |
The ID of the site the claim belongs to |
| status_comments string |
Further details on the claim status (Information provided in NHs responses may be included here) |
| treatment_plan_id integer |
The ID of the treatment plan the claim belongs to |
| ni_calculated_dentist_fee string |
The Northern Irish dentist charge associated with the claim |
| ni_calculated_patient_fee string |
The Northern Irish dentist charge associated with the claim |
| submitted_date date |
The date the claim was last submitted |
| dentist_charge string |
The dentist charge associated with the claim |
| patient_charge string |
The patient charge associated with the claim |
| scot_amount_authorised string |
The Scottish practice fee awarded for the claim |
| scot_amount_expected string |
The Scottish practice fee expected for the claim |
| uda_band string |
The UDA band the claim is being submitted under |
| ortho boolean |
Whether the claim is orthodontic or not |
| continuation_part_number integer |
The continuation part number of the claim (if present) |
| created_at: datetime |
The time and date the claim was created |
| updated_at: datetime |
The time and date the claim was last updated |
Get a single NHS claim
Retrieves the details of an existing NHS claim
DEFINITION
GET https://api.dentally.co/v1/nhs_claims/{NHS_CLAIM_ID}
EXAMPLE REQUEST
curl https://api.dentally.co/v1/nhs_claims/5bd1f93d-bfa3-4402-a2fc-5880c5218815
Parameters
| id: | required |
EXAMPLE RESPONSE
{
"nhs_claim": {
"id": "5bd1f93d-bfa3-4402-a2fc-5880c5218815",
"awarded_uda": "12.0",
"approval_date": "2012-07-28",
"contract_id": "652e5e2f-1697-417e-8feb-1ecd832bd42d",
"claim_status": "complete",
"expected_uda": "12.0",
"patient_id": 1,
"practitioner_id":1,
"sequence_number": "1420",
"site_id": "e1d854af-15db-4482-8e29-39e74a6c7f75",
"status_comments": "UDA 12.00 positive, Employment Support",
"treatment_plan_id": 1,
"ni_calculated_dentist_fee": "0.0",
"ni_calculated_patient_fee": "0.0",
"submitted_date": "2012-07-27",
"dentist_charge": "0.0",
"patient_charge": "53.9",
"scot_amount_authorised": "0.0",
"scot_amount_expected": "0.0",
"uda_band": "3",
"ortho": false,
"continuation_part_number": 1,
"created_at":"2012-05-8:54:05:00.000+00:00",
"updated_at":"2012-07-27T11:24:00.000+00:00"
}
}
Returns
An NHS claim object
List all NHS Claims
Returns a list of all NHS Claims
DEFINITION
GET https://api.dentally.co/v1/nhs_claims{created_after, created_after, site_id}
EXAMPLE REQUEST
curl https://api.dentally.co/v1/nhs_claims?site_id=f1ce59f8-6ec3-48cc-bc07-5428721c5cdd
EXAMPLE RESPONSE:
{
"nhs_claims": [
{
"id": "5bd1f93d-bfa3-4402-a2fc-5880c5218815",
"awarded_uda": "12.0",
"approval_date": "2012-07-28",
"contract_id": "652e5e2f-1697-417e-8feb-1ecd832bd42d",
"claim_status": "complete",
"expected_uda": "12.0",
"patient_id": 1,
"practitioner_id":1,
"sequence_number": "1420",
"site_id": "e1d854af-15db-4482-8e29-39e74a6c7f75",
"status_comments": "UDA 12.00 positive, Employment Support",
"treatment_plan_id": 1,
"ni_calculated_dentist_fee": "0.0",
"ni_calculated_patient_fee": "0.0",
"submitted_date": "2012-07-27",
"dentist_charge": "0.0",
"patient_charge": "53.9",
"scot_amount_authorised": "0.0",
"scot_amount_expected": "0.0",
"uda_band": "3",
"ortho": false,
"continuation_part_number": 1,
"created_at":"2012-05-8:54:05:00.000+00:00",
"updated_at":"2012-07-27T11:24:00.000+00:00"
},
{...},
{...}
],
"meta": {
"total": 3,
"page": 1
}
}
Parameters
| created_after: datetime, optional |
Returns all NHS claims that were created after this time |
| updated_after: datetime, optional |
Returns all NHS claims that have been updated since this time |
| site_id string, optional |
NHS claims attributed to a specific site through their assigned practitioner |
Sorting
The following columns can be used to sort.
| created_at | ascending or descending |
Returns
Returns a list of NHS claims that match the query.
Patients
The patient object
A patient belongs to a practice
EXAMPLE RESPONSE
{
"patient": {
"id": 1,
"account_id": 1,
"active": true,
"acquisition_source_id": "abdcdeb5-ebe4-4629-a375-15e1506d3961",
"address_line_1": "25.5 Coda Studios",
"address_line_2": "Munster Road",
"county": "London",
"created_at": "2015-01-01T12:00:00.000+00:00",
"custom_fields": [
{
"value": true,
"field_id": "2c19fdf0-987c-4e5a-aa71-06ad8a58ee22",
"position": 0
},
{
"value": true,
"field_id": "db96ab4b-5c3a-4f00-9534-9d8ad9bcf13b",
"position": 1
},
{
"value": false,
"field_id": "38b96e14-e31d-477b-a1c0-1538ff4cf360",
"position": 2
}],
"custom_field_1": "92837484",
"custom_field_2": null,
"date_of_birth": "1988-06-02",
"dentist_id": 1,
"dentist_recall_date": "2016-01-09",
"dentist_recall_interval": 6,
"doctor_id": 1,
"email_address": "sergio@aguero.com",
"ethnicity": "16",
"family_id": "abdcdeb5-ebe4-4629-a375-15e1506d3961",
"first_name": "Sergio",
"gender": true,
"home_phone": "02023456789",
"home_phone_country": "GB",
"hygienist_id": 2,
"hygienist_recall_date": "2016-07-09",
"hygienist_recall_interval": 12,
"image_url": "https://www.gravatar.com/avatar/1c9e3735c970be65be56baa5db0edf83.jpg?&r=pg&d=identicon&s=190",
"last_name": "Aguero",
"legacy_id": "0000000010",
"marketing": true,
"medical_alert": false,
"medical_alert_text": null,
"metadata": {
},
"middle_name": "Kun",
"mobile_phone": "07123456789",
"mobile_phone_country": "GB",
"nhs_number": "0123456789",
"ni_number": null,
"occupation": "Footballer",
"payment_plan_id": 2,
"postcode": "FO07 8AL",
"pps_number": "4567893W",
"preferred_name": null,
"preferred_phone_number": 3,
"recall_method": "Letter",
"site_id": "e1d854af-15db-4482-8e29-39e74a6c7f75",
"title": "Mr",
"town": "London",
"updated_at": "2016-01-26T11:27:43.516+00:00",
"use_email": false,
"use_sms": true,
"work_phone": "01234567890",
"work_phone_country": "GB",
"emergency_contact_name": "Jim",
"emergency_contact_relationship": "Friend",
"emergency_contact_phone": "07306743470",
"emergency_contact_phone_country": "GB",
"emergency_contact_phone_normalized": "+447306743470",
}
}
ATTRIBUTES
| id: integer |
The patient’s ID |
| account_id: integer |
The patient’s account ID |
| active: boolean |
If the patient is active true or has been archived false |
| acquisition_source_id: string |
The identifier of the patient’s acquisition source |
| address_line_1: string |
The first line of the patient’s address |
| address_line_2: string |
The second line of the patient’s address |
| county: string |
The county the patient resides |
| created_at: datetime |
The time and date the patient’s record was created |
| custom_fields: array |
Custom fields for this Patient, where the field_id refers to an object in the Custom Fields resource and the value is the value of the custom field for this Patient. |
| custom_field_1: string |
A data field a practice can use to store extra info about patients. Label is listed on the practice under custom_patient_field_label_1 |
| custom_field_2: string |
A data field a practice can use to store extra info about patients. Label is listed on the practice under custom_patient_field_label_2 |
| date_of_birth: date |
The patient’s date of birth |
| dentist_id: integer |
The practitioner ID of the patient’s preferred dentist |
| dentist_recall_date: date |
The date the patient is next due for a dental exam |
| dentist_recall_interval: integer |
The number of months between dental exams. Must be between 0 & 24 |
| doctor_id: integer |
The ID of the patient’s doctor |
| email_address: string |
The patients email address |
| ethnicity: string |
The ethnicity code of the patient. Must be one of the codes listed here |
| family_id: uuid |
A string identifying a family unit this patient belongs to or null. |
| first_name: string |
The patient’s first name |
| gender: boolean |
The patient’s gender (true for male, false for female) |
| home_phone: string |
The patient’s home phone number |
| home_phone_country: string |
The ISO country code for the home phone number |
| hygienist_id: integer |
The practitioner ID of the patient’s preferred hygienist |
| hygienist_recall_date: date |
The date the patient is next due for a hygiene exam |
| hygienist_recall_interval: integer |
The number of months between hygiene exams. Must be between 0 & 24 |
| image_url: string |
URL of the patient’s profile image |
| last_name: string |
The patient’s last name |
| legacy_id: string |
The patient’s ID on a previous or different system |
| marketing: integer, optional |
Indicates if the patient consents to receiving marketing material |
| medical_alert: boolean |
Set to true if the patient has a medical condition. Default false |
| medical_alert_text: string |
A summary of the patient’s medical condition |
| metadata: hash |
A set of key/value pairs that you can attach to a patient. It can be useful for storing additional information about the patient in a structured format. |
| middle_name: string |
The patient’s middle name. |
| mobile_phone: string |
The patient’s mobile phone number |
| mobile_phone_country: string |
The ISO country code for the mobile phone number |
| nhs_number: string |
The patient’s NHS number |
| ni_number: string |
The patient’s national insurance number |
| pps_number: string |
The patient’s PPS number |
| occupation: string |
The patient’s occupation |
| payment_plan_id: integer |
The ID of the payment plan that the patient belongs to |
| postcode: string |
The patient’s postcode |
| preferred_name: string |
The patient’s preferred name |
| preferred_phone_number: integer |
The patient’s preferred contact number. 1 for home, 2 for work and 3 for mobile |
| recall_method: string |
The preferred method of contacting the patient when their recall is due. Must be Letter, SMS, Email or Phone. Default is Letter |
| site_id: string |
The ID of the site that the patient belongs to |
| title: string |
The patient’s title. It must be one of Mr, Mrs, Miss, Ms, Dr, Master, Prof, Hon, Rev, Sir, Lady, Lord, Earl, Judge or Dame |
| town: string |
The town the patient resides |
| updated_at: datetime |
The date and time the patients details were last updated |
| use_email: boolean |
If the patient wants to receive emails from the practice. Default true |
| use_sms: boolean |
If the patient wants to receive sms from the practice. Default true |
| work_phone: string |
The patient’s work phone number |
| work_phone_country: string |
The ISO country code for the work phone number |
| emergency_contact_name: string |
The patient’s emergency contact name |
| emergency_contact_relationship: string |
The patient’s emergency contact relationship |
| emergency_contact_phone: string |
The patient’s emergency phone number |
| emergency_contact_phone_country: string |
The ISO country code for the emergency phone number |
| emergency_contact_phone_normalized: string |
The patient’s emergency contact phone number inclucing the country code |
Create a patient
Creates a new patient
DEFINITION
POST https://api.dentally.co/v1/patients
EXAMPLE REQUEST
curl --include \
--request POST \
--header "Content-Type: application/json" \
--data-binary '{
"patient": {
"title": "Mr",
"first_name": "John",
"last_name": "Smith",
"date_of_birth": "1980-01-01",
"gender": true,
"ethnicity": "99",
"address_line_1": "21 Oak Avenue",
"postcode": "W1A 1AA",
"payment_plan_id": 1
}
}' \
https://api.dentally.co/v1/patients
Parameters
Parameters must be wrapped by a patient object
| title: string, required |
The patient’s title. It must be one of Mr, Mrs, Miss, Ms, Dr, Master, Prof, Hon, Rev, Sir, Lady, Lord, Earl, Judge or Dame |
| first_name: string, required |
The patient’s first name |
| last_name: string, required |
The patient’s last name |
| date_of_birth: date, required |
The patient’s date of birth |
| gender: boolean, required |
The patient’s gender, true for male and false for female |
| ethnicity: string, required |
Must be one of the codes listed here |
| address_line_1: string, required |
The fist line of the patient’s address |
| postcode: string, required |
The patient’s postcode |
| payment_plan_id: integer, required |
The ID of the payment plan that the patient belongs to |
| active: boolean, optional |
If the patient is active. Default is true |
| address_line_2: string, optional |
The second line of the patient’s address |
| county: string, optional |
The patient’s address county |
| dentist_id: integer, optional |
The practitioner ID of the patient’s dentist |
| dentist_recall_date: date, optional |
The date the patient is next due for an exam |
| dentist_recall_interval: integer, optional |
The number of months between exams. Must be between 0 & 24 |
| email_address: string, optional |
The patient’s email address |
| home_phone: string, optional |
The patient’s home phone number |
| home_phone_country: string |
The ISO country code for the home phone number |
| hygienist_id: integer, optional |
The practitioner ID of the patient’s hygienist |
| hygienist_recall_date: date, optional |
The date the patient is next due for a scale and polish |
| hygienist_recall_interval: integer, optional |
The number of months between hygienist visits. Must be between 0 & 24 |
| legacy_id: string, optional |
The patient’s ID on a previous or different system |
| marketing: integer, optional |
Indicates if the patient consents to receiving marketing material |
| medical_alert: integer, optional |
Set to true if the patient has a medical condition. Default false |
| medical_alert_text: string, optional |
A summary of the patient’s medical condition |
| metadata: hash, optional |
A set of key/value pairs that you can attach to a patient. It can be useful for storing additional information about the patient in a structured format. |
| middle_name: string, optional |
The patient’s middle name |
| mobile_phone: string, optional |
The patient’s mobile phone number |
| mobile_phone_country: string |
The ISO country code for the mobile phone number |
| nhs_number: string, optional |
The patient’s NHS number |
| ni_number: string, optional |
The patient’s national insurance number |
| pps_number: string, optional |
The patient’s PPS number |
| preferred_name: string, optional |
The patient’s nickname or preferred name |
| preferred_phone_number: integer, optional |
The phone number the patient prefers to be contacted on. 1 for home, 2 for work and 3 for mobile |
| recall_method: string, optional |
The preferred method of contacting the patient when their recall is due. Must be Letter, SMS, Email or Phone. Default is Letter |
| site_id: string, optional |
The ID of the site that the patient belongs to. Will default to the user’s site if not specified |
| town: string, optional |
The patient’s address town |
| use_email: boolean, optional |
If the patient wants to receive emails from the practice. Default true |
| use_sms: boolean, optional |
If the patient wants to receive SMS from the practice. Default true |
| work_phone: string |
The patient’s work phone number |
| work_phone_country: string |
The ISO country code for the work phone number |
| emergency_contact_name: string |
The patient’s emergency contact name |
| emergency_contact_relationship: string |
The patient’s emergency contact relationship |
| emergency_contact_phone: string |
The patient’s emergency phone number |
| emergency_contact_phone_country: string |
The ISO country code for the emergency phone number |
Note: The emergency_contact_phone can be set alone, but if you set emergency_contact_name or emergency_contact_relationship you must set emergency_contact_phone.
EXAMPLE RESPONSE
{
"patient": {
"id": 3,
"account_id": 3,
"active": true,
"address_line_1": "21 Oak Avenue",
"address_line_2": null,
"county": null,
"created_at": "2014-09-11T14:48:01.563+01:00",
"date_of_birth": "1980-01-01",
"dentist_id": null,
"dentist_recall_date": null,
"dentist_recall_interval": 0,
"email_address": null,
"ethnicity": "99",
"first_name": "John",
"gender": true,
"home_phone": null,
"home_phone_country": "GB",
"hygienist_id": null,
"hygienist_recall_date": null,
"hygienist_recall_interval": 0,
"image_url": "https://www.gravatar.com/avatar/fb830e28cd031264e371ab85563b37b0.jpg?&r=pg&d=identicon&s=190",
"last_name": "Smith",
"legacy_id": null,
"medical_alert": false,
"medical_alert_text": null,
"metadata": {
},
"middle_name": null,
"mobile_phone": null,
"mobile_phone_country": "GB",
"nhs_number": null,
"ni_number": null,
"occupation": null,
"payment_plan_id": 1,
"postcode": "W1A 1AA",
"preferred_name": null,
"preferred_phone_number": null,
"recall_method": "Letter",
"site_id": "e1d854af-15db-4482-8e29-39e74a6c7f75",
"title": "Mr",
"town": null,
"updated_at": "2014-09-11T14:48:01.563+01:00",
"use_email": true,
"use_sms": true,
"work_phone": null,
"work_phone_country": "GB",
"emergency_contact_name": null,
"emergency_contact_relationship": null,
"emergency_contact_phone": null,
"emergency_contact_phone_country": "GB",
"emergency_contact_phone_normalized": null,
}
}
Returns
The newly created patient object
Get a single patient
Retrieves the details of an existing patient
DEFINITION
GET https://api.dentally.co/v1/patients/{PATIENT_ID}
EXAMPLE REQUEST
curl https://api.dentally.co/v1/patients/1
Parameters
| id: | required |
Returns
The existing patient object
EXAMPLE RESPONSE
{
"patient": {
"id": 1,
"account_id": 1,
"active": true,
"acquisition_source_id": "abdcdeb5-ebe4-4629-a375-15e1506d3961",
"address_line_1": "135 New Crescent",
"address_line_2": "Trlr 882",
"county": "Breconshire",
"created_at": "2013-11-04T03:07:33.954+00:00",
"custom_fields": [
{
"value": true,
"field_id": "2c19fdf0-987c-4e5a-aa71-06ad8a58ee22",
"position": 0
},
{
"value": true,
"field_id": "db96ab4b-5c3a-4f00-9534-9d8ad9bcf13b",
"position": 1
},
{
"value": false,
"field_id": "38b96e14-e31d-477b-a1c0-1538ff4cf360",
"position": 2
}],
"custom_field_1": "92837484",
"custom_field_2": null,
"date_of_birth": "1975-10-23",
"dentist_id": null,
"dentist_recall_date": null,
"dentist_recall_interval": 12,
"email_address": "patient@dentalpractice.com",
"ethnicity": "07",
"family_id": "abdcdeb5-ebe4-4629-a375-15e1506d3961",
"first_name": "Alesha",
"gender": false,
"home_phone": "013332511673",
"home_phone_country": "GB",
"hygienist_id": null,
"hygienist_recall_date": null,
"hygienist_recall_interval": 12,
"image_url": "https://www.gravatar.com/avatar/7a37035f9ccdd683c05435e07c60ff90.jpg?&r=pg&d=identicon&s=190",
"last_name": "Chaney",
"legacy_id": null,
"marketing": true,
"medical_alert": false,
"medical_alert_text": null,
"metadata": {
},
"middle_name": "Kiara",
"mobile_phone": "07306743470",
"mobile_phone_country": "GB",
"nhs_number": "7474158055",
"ni_number": null,
"occupation" "Doctor",
"payment_plan_id": 2,
"postcode": "DG11 6JM",
"pps_number": "4567893W",
"preferred_name": null,
"preferred_phone_number": 3,
"recall_method": "Letter",
"site_id": "e1d854af-15db-4482-8e29-39e74a6c7f75",
"title": "Ms",
"town": "Giffnock",
"updated_at": "2013-11-04T03:07:33.954+00:00",
"use_email": false,
"use_sms": true,
"work_phone": "020303132213",
"work_phone_country": "GB",
"emergency_contact_name": "Jim",
"emergency_contact_relationship": "Friend",
"emergency_contact_phone": "07306743470",
"emergency_contact_phone_country": "GB",
"emergency_contact_phone_normalized": "+447306743470",
}
}
Edit a patient
Updates an existing patient
DEFINITION
PUT/PATCH https://api.dentally.co/v1/patients/{PATIENT_ID}
EXAMPLE REQUEST
curl --include \
--request PUT \
--header "Content-Type: application/json" \
--data-binary '{
"patient": {
"first_name": "Frank"
}
}' \
https://api.dentally.co/v1/patients/3
Parameters
Parameters must be wrapped by a patient object
| title: string, optional |
The patient’s title. It must be one of Mr, Mrs, Miss, Ms, Dr, Master, Prof, Hon, Rev, Sir, Lady, Lord, Earl, Judge or Dame |
| first_name: string, optional |
The patient’s first name |
| last_name: string, optional |
The patient’s last name |
| date_of_birth: date, optional |
The patient’s date of birth |
| gender: boolean, optional |
The patient’s gender, true for male and false for female |
| ethnicity: string, optional |
Must be one of the codes listed here |
| address_line_1: string, optional |
The fist line of the patient’s address |
| postcode: string, optional |
The patient’s postcode |
| payment_plan_id: integer, optional |
The ID of the payment plan that the patient belongs to |
| active: boolean, optional |
If the patient is active. Default is true |
| address_line_2: string, optional |
The second line of the patient’s address |
| county: string, optional |
The patient’s address county |
| dentist_id: integer, optional |
The practitioner ID of the patient’s dentist |
| dentist_recall_date: date, optional |
The date the patient is next due for an exam |
| dentist_recall_interval: integer, optional |
The number of months between exams. Must be between 0 & 24 |
| email_address: string, optional |
The patient’s email address |
| home_phone: string, optional |
The patient’s home phone number |
| home_phone_country: string |
The ISO country code for the home phone number |
| hygienist_id: integer, optional |
The practitioner ID of the patient’s hygienist |
| hygienist_recall_date: date, optional |
The date the patient is next due for a scale and polish |
| hygienist_recall_interval: integer, optional |
The number of months between hygienist visits. Must be between 0 & 24 |
| legacy_id: string, optional |
The patient’s ID on a previous or different system |
| marketing: integer, optional |
Indicates if the patient consents to receiving marketing material |
| medical_alert: integer, optional |
Set to true if the patient has a medical condition. Default false |
| medical_alert_text: string, optional |
A summary of the patient’s medical condition |
| metadata: hash, optional |
A set of key/value pairs that you can attach to a patient. It can be useful for storing additional information about the patient in a structured format. |
| middle_name: string, optional |
The patient’s middle name |
| mobile_phone: string, optional |
The patient’s mobile phone number |
| mobile_phone_country: string |
The ISO country code for the mobile phone number |
| nhs_number: string, optional |
The patient’s NHS number |
| ni_number: string, optional |
The patient’s national insurance number |
| pps_number: string, optional |
The patient’s PPS number |
| preferred_name: string, optional |
The patient’s nickname or preferred name |
| preferred_phone_number: integer, optional |
The phone number the patient prefers to be contacted on. 1 for home, 2 for work and 3 for mobile |
| recall_method: string, optional |
The preferred method of contacting the patient when their recall is due. Must be Letter, SMS, Email or Phone. Default is Letter |
| site_id: string, optional |
The ID of the site that the patient belongs to |
| town: string, optional |
The patient’s address town |
| use_email: boolean, optional |
If the patient wants to receive emails from the practice. Default true |
| use_sms: boolean, optional |
If the patient wants to receive SMS from the practice. Default true |
| work_phone: string |
The patient’s work phone number |
| work_phone_country: string |
The ISO country code for the work phone number |
| emergency_contact_name: string |
The patient’s emergency contact name |
| emergency_contact_relationship: string |
The patient’s emergency contact relationship |
| emergency_contact_phone: string |
The patient’s emergency phone number |
| emergency_contact_phone_country: string |
The ISO country code for the emergency phone number |
Note: The emergency_contact_phone can be set alone, but if you set emergency_contact_name or emergency_contact_relationship you must set emergency_contact_phone.
EXAMPLE RESPONSE
{
"patient": {
"id": 3,
"account_id": 3,
"active": true,
"address_line_1": "21 Oak Avenue",
"address_line_2": null,
"county": null,
"created_at": "2014-09-11T14:48:01.563+01:00",
"custom_field_1": "92837484",
"custom_field_2": null,
"date_of_birth": "1980-01-01",
"dentist_id": null,
"dentist_recall_date": null,
"dentist_recall_interval": 0,
"email_address": null,
"ethnicity": "99",
"first_name": "Frank",
"gender": true,
"home_phone": null,
"home_phone_country": "GB",
"hygienist_id": null,
"hygienist_recall_date": null,
"hygienist_recall_interval": 0,
"image_url": "https://www.gravatar.com/avatar/fb830e28cd031264e371ab85563b37b0.jpg?&r=pg&d=identicon&s=190",
"last_name": "Smith",
"legacy_id": null,
"marketing": true,
"medical_alert": false,
"medical_alert_text": null,
"metadata": {
},
"middle_name": null,
"mobile_phone": null,
"mobile_phone_country": "GB",
"nhs_number": null,
"ni_number": null,
"occupation" "Doctor",
"payment_plan_id": 1,
"postcode": "W1A 1AA",
"pps_number": "4567893W",
"preferred_name": null,
"preferred_phone_number": null,
"recall_method": "Letter",
"site_id": "e1d854af-15db-4482-8e29-39e74a6c7f75",
"title": "Mr",
"town": null,
"updated_at": "2014-09-11T14:48:01.563+01:00",
"use_email": true,
"use_sms": true,
"work_phone": null,
"work_phone_country": "GB",
"emergency_contact_name": "Jim",
"emergency_contact_relationship": "Friend",
"emergency_contact_phone": "07306743470",
"emergency_contact_phone_country": "GB"
}
}
Returns
The updated patient object
Delete a patient
This sets the patient’s active flag to false and can be undone by simply setting the active flag back to true
DEFINITION
DELETE https://api.dentally.co/v1/patients/{PATIENT_ID}
EXAMPLE REQUEST
curl --include \
--request DELETE \
https://api.dentally.co/v1/patients/1
Parameters
| id: | required |
Returns
Returns a 204 response
List all patients
Returns a list of existing patients
DEFINITION
GET https://api.dentally.co/v1/patients?query
EXAMPLE REQUEST
curl https://api.dentally.co/v1/patients?query=al
Parameters
| query: string, optional |
A search query to filter patient records. This can be a combination of the patient’s first, middle and last names OR their postcode OR their date of birth OR their email address OR their home, work or mobile phone number (or part of). By default this list will only return active patients, to return only inactive patients include an asterisk * in the search query |
| updated_after: datetime, optional |
Returns all patients that have been updated since this time |
| created_after: datetime, optional |
Returns all patients that have been created since this time |
| payment_plan_id: integer, optional |
Returns all patients that have that payment_plan_id |
| site_id: string, optional |
Patients assigned to a specific site |
EXAMPLE RESPONSE:
{
"patients": [
{
"id": 1,
"account_id": 1,
"active": true,
"acquisition_source_id": "abdcdeb5-ebe4-4629-a375-15e1506d3961",
"address_line_1": "135 New Crescent",
"address_line_2": "Trlr 882",
"county": "Breconshire",
"created_at": "2013-11-04T03:07:33.954+00:00",
"custom_fields": [
{
"value": true,
"field_id": "2c19fdf0-987c-4e5a-aa71-06ad8a58ee22",
"position": 0
},
{
"value": true,
"field_id": "db96ab4b-5c3a-4f00-9534-9d8ad9bcf13b",
"position": 1
},
{
"value": false,
"field_id": "38b96e14-e31d-477b-a1c0-1538ff4cf360",
"position": 2
}],
"custom_field_1": "92837484",
"custom_field_2": null,
"date_of_birth": "1975-10-23",
"dentist_id": null,
"dentist_recall_date": null,
"dentist_recall_interval": 12,
"email_address": "patient@dentalpractice.com",
"ethnicity": "07",
"family_id": "abdcdeb5-ebe4-4629-a375-15e1506d3961",
"first_name": "Alesha",
"gender": false,
"home_phone": "013332511673",
"home_phone_country": "GB",
"hygienist_id": null,
"hygienist_recall_date": null,
"hygienist_recall_interval": 12,
"image_url": "https://www.gravatar.com/avatar/7a37035f9ccdd683c05435e07c60ff90.jpg?&r=pg&d=identicon&s=190",
"last_name": "Chaney",
"legacy_id": null,
"marketing": true,
"medical_alert": false,
"medical_alert_text": null,
"metadata": {
},
"middle_name": "Kiara",
"mobile_phone": "07306743470",
"mobile_phone_country": "GB",
"nhs_number": "7474158055",
"ni_number": null,
"occupation": "Doctor",
"payment_plan_id": 2,
"postcode": "DG11 6JM",
"pps_number": "4567893W",
"preferred_name": null,
"preferred_phone_number": 3,
"recall_method": "Letter",
"site_id": "e1d854af-15db-4482-8e29-39e74a6c7f75",
"title": "Ms",
"town": "Giffnock",
"updated_at": "2013-11-04T03:07:33.954+00:00",
"use_email": false,
"use_sms": true,
"work_phone": "020303132213",
"work_phone_country": "GB",
"emergency_contact_name": "Jim",
"emergency_contact_relationship": "Friend",
"emergency_contact_phone": "07306743470",
"emergency_contact_phone_country": "GB",
"emergency_contact_phone_normalized": "+447306743470",
},
{...},
{...}
],
"meta": {
"total": 3,
"page": 1
}
}
Returns
Returns a list of patients that match the query. The response includes a metadata object which contains the page number that was returned as well as the total number of patients that match the query. The patients are returned in the order that best matches the query
Patient Stats
The patient stat object
A patient stat belongs to a patient
EXAMPLE RESPONSE
{
"patient_stat": {
"created_at": "2015-10-20T23:21:46.690+01:00",
"first_appointment_date": "2016-01-11T16:00:00.000+00:00",
"first_exam_date": "2016-01-11T16:00:00.000+00:00",
"last_appointment_date": "2016-06-09T14:00:00.000+01:00",
"last_cancelled_appointment_date": null
"last_exam_date": "2016-01-11T16:00:00.000+00:00",
"last_fta_appointment_date": "2018-09-18T10:00:00.000+01:00",
"last_scale_and_polish_date": null,
"next_appointment_date": null,
"next_exam_date": null,
"next_scale_and_polish_date": null,
"nhs_exemption_code": null,
"patient_id": 52,
"total_invoiced": "0.0",
"total_paid": "0.0",
"updated_at": "2018-09-19T01:00:36.638+01:00",
}
}
ATTRIBUTES
| created_at: datetime |
The date and time at which the record was created |
| first_appointment_date: datetime, optional |
The date and time of the patient’s first appointment |
| first_exam_date: datetime, optional |
The date and time of the patient’s first examination |
| last_appointment_date: datetime, optional |
The date and time of the patient’s most recent appointment |
| last_cancelled_appointment_date: datetime, optional |
The date and time of the patient’s most recent cancelled appointment |
| last_exam_date: datetime, optional |
The date and time of the patient’s most recent examination |
| last_fta_appointment_date: datetime, optional |
The date and time of the patient’s most recent Failure To Attend an appointment |
| last_scale_and_polish_date: datetime, optional |
The date and time of the patient’s most recent scale and polish |
| next_appointment_date: datetime, optional |
The date and time of the patient’s next appointment |
| next_exam_date: datetime, optional |
The date and time of the patient’s next examination |
| next_scale_and_polish_date: datetime, optional |
The date and time of the patient’s next scale and polish |
| nhs_exemption_code: string, optional |
The NHS exemption code of the patient |
| patient_id: integer |
The ID of the patient |
| total_invoiced: string |
The total invoiced to the patient |
| total_paid: string |
The total paid by the patient |
| updated_at: datetime |
The date and time at which the record was last updated |
Get a single patient stat
Retrieves the details of an existing patient stat
DEFINITION
GET https://api.dentally.co/v1/patients/{PATIENT_ID}/stats
EXAMPLE REQUEST
curl https://api.dentally.co/v1/patients/1/stats
Parameters
| id: | required |
Returns
The existing patient stat object
EXAMPLE RESPONSE
{
"patient_stat": {
"last_appointment_date": "2016-06-09T14:00:00.000+01:00",
"last_exam_date": "2016-01-11T16:00:00.000+00:00",
"last_scale_and_polish_date": null,
"next_appointment_date": null,
"next_exam_date": null,
"next_scale_and_polish_date": null,
"created_at": "2015-10-20T23:21:46.690+01:00",
"updated_at": "2018-09-19T01:00:36.638+01:00",
"total_paid": "0.0",
"total_invoiced": "0.0",
"last_fta_appointment_date": "2018-09-18T10:00:00.000+01:00",
"first_appointment_date": "2016-01-11T16:00:00.000+00:00",
"first_exam_date": "2016-01-11T16:00:00.000+00:00",
"nhs_exemption_code": null,
"patient_id": 52,
"last_cancelled_appointment_date": null
}
}
List all patient stats
Returns a list of existing patient stats
DEFINITION
GET https://api.dentally.co/v1/patient_stats{created_at_after, created_at_before, updated_at_after, updated_at_before}
EXAMPLE REQUEST
curl https://api.dentally.co/v1/patient_stats?created_at_after=2016-01-05
Parameters
| created_at_after: datetime, optional |
Returns all patient stats that have been created since this time |
| created_at_before: datetime, optional |
Returns all patient stats that were created before this time |
| updated_at_after: datetime, optional |
Returns all patient stats that have been updated since this time |
| updated_at_before: datetime, optional |
Returns all patient stats that were updated before this time |
EXAMPLE RESPONSE:
{
"patient_stats": [
{
"last_appointment_date": "2016-06-09T14:00:00.000+01:00",
"last_exam_date": "2016-01-11T16:00:00.000+00:00",
"last_scale_and_polish_date": null,
"next_appointment_date": null,
"next_exam_date": null,
"next_scale_and_polish_date": null,
"created_at": "2015-10-20T23:21:46.690+01:00",
"updated_at": "2018-09-19T01:00:36.638+01:00",
"total_paid": "0.0",
"total_invoiced": "0.0",
"last_fta_appointment_date": "2018-09-18T10:00:00.000+01:00",
"first_appointment_date": "2016-01-11T16:00:00.000+00:00",
"first_exam_date": "2016-01-11T16:00:00.000+00:00",
"nhs_exemption_code": null,
"patient_id": 52,
"last_cancelled_appointment_date": null
},
{...},
{...}
],
"meta": {
"total": 3,
"page": 1
}
}
Returns
Returns a list of patient stats that match the query. The response includes a metadata object which contains the page number that was returned as well as the total number of patient stats that match the query. The patient stats are returned in the order that best matches the query
Payment Plans
The payment plan object
EXAMPLE RESPONSE
{
"payment_plan": {
"id": 1,
"created_at": "2013-11-05T11:27:05.686+00:00",
"colour": "#25B0E6",
"dentist_recall_interval": 6,
"emergency_duration": 15,
"exam_duration": 10,
"exam_scale_and_polish_duration": 20,
"hygienist_recall_interval": 6,
"name": "NHS",
"patient_friendly_name": "NHS Plan",
"scale_and_polish_duration": 10,
"site_id": "e1d854af-15db-4482-8e29-39e74a6c7f75"
}
}
ATTRIBUTES
| id: integer |
The ID of the payment plan |
| active: boolean |
If the payment plan is active true or has been archived false |
| created_at: string |
The date and time the payment plan was created |
| colour: string |
The colour used to display the payment plan |
| dentist_recall_interval: integer |
The interval between dental recalls |
| emergency_duration: integer |
The default duration of emergency appointments |
| exam_scale_and_polish_duration: integer |
The default duration of scale and polish appointments |
| exam_duration: integer |
The default duration of exam appointments |
| hygienist_recall_interval: integer |
The interval between hygienist recalls |
| name: string |
The name of the payment plan |
| patient_friendly_name: string |
A friendly name shown to patients |
| scale_and_polish_duration: integer |
The default duration of scale and polish appointments |
| site_id: string |
The ID of the site that the payment plan belongs to |
Get a single payment plan
Retrieves the details of an existing payment plan
DEFINITION
GET https://api.dentally.co/v1/payment_plans/{PAYMENT_PLAN_ID}
EXAMPLE REQUEST
curl https://api.dentally.co/v1/payment_plans/1
Parameters
| id: | required |
Returns
The existing payment plan object.
EXAMPLE RESPONSE
{
"payment_plan": {
"id": 1,
"active": true,
"created_at": "2013-11-05T11:27:05.686+00:00",
"colour": "#25B0E6",
"dentist_recall_interval": 6,
"emergency_duration": 15,
"exam_duration": 10,
"exam_scale_and_polish_duration": 20,
"hygienist_recall_interval": 6,
"name": "NHS",
"patient_friendly_name": "NHS Plan",
"scale_and_polish_duration": 10,
"site_id": "e1d854af-15db-4482-8e29-39e74a6c7f75"
}
}
Edit a payment plan
Updates an existing payment plan
DEFINITION
PUT/PATCH https://api.dentally.co/v1/payment_plans/{PAYMENT_PLAN_ID}
EXAMPLE REQUEST
curl --include \
--request PUT \
--header "Content-Type: application/json" \
--data-binary '{
"payment_plan": {
"colour": "#FFFFFF"
}
}' \
https://api.dentally.co/v1/payment_plans/1
Parameters
Parameters must be wrapped by a payment_plan object
| active boolean, optional |
Set to true to activate the payment plan, false otherwise |
| colour: string, optional |
The payment plan’s colour. Must be in hexadecimal format |
| dentist_recall_interval integer, optional |
The time before dentist recall in months |
| emergency_duration integer, optional |
The duration of an emergency appointment in minutes, between 5 and 120 |
| exam_duration integer, optional |
The duration of an exam in minutes, between 5 and 120 |
| exam_scale_and_polish_duration integer, optional |
The duration of an exam, scale and polish appointment in minutes, between 5 and 120 |
| hygienist_recall_interval integer, optional |
The time before hygienist recall in months |
| name: string, optional |
The name of the payment plan |
| patient_friendly_name string, optional |
The name of the payment plan as seen by patients |
| scale_and_polish_duration integer, optional |
The duration of a scale and polish appointment in minutes, between 5 and 120 |
| site_id uuid, optional |
The site the plan is associated with. If null then it is associated with all sites. |
EXAMPLE RESPONSE
{
"payment_plan": {
"id": 1,
"active": false,
"created_at": "2013-11-05T11:27:05.686+00:00",
"colour": "#FFFFFF",
"dentist_recall_interval": 6,
"emergency_duration": 15,
"exam_duration": 10,
"exam_scale_and_polish_duration": 20,
"hygienist_recall_interval": 6,
"name": "NHS",
"patient_friendly_name": "NHS Plan",
"scale_and_polish_duration": 10,
"site_id": "e1d854af-15db-4482-8e29-39e74a6c7f75"
}
}
Returns
The updated payment plan object
Create a payment plan
Creates a new payment plan
DEFINITION
POST https://api.dentally.co/v1/payment_plans
EXAMPLE REQUEST
curl --include \
--request POST \
--header "Content-Type: application/json" \
--data-binary '{
"payment_plan": {
"name": "Custom Plan",
"colour": "#FFFFFF"
}
}' \
https://api.dentally.co/v1/payment_plans
Parameters
Parameters must be wrapped by a payment_plan object
| active boolean, optional |
Set to true to activate the payment plan, false otherwise. Default true. |
| colour: string, optional |
The payment plan’s colour. Must be in hexadecimal format. |
| dentist_recall_interval integer, optional |
The time before dentist recall in months. Default 6. |
| emergency_duration integer, optional |
The duration of an emergency appointment in minutes, between 5 and 120. Default 10. |
| exam_duration integer, optional |
The duration of an exam in minutes, between 5 and 120. Default 10. |
| exam_scale_and_polish_duration integer, optional |
The duration of an exam, scale and polish appointment in minutes, between 5 and 120. Default 20. |
| hygienist_recall_interval integer, optional |
The time before hygienist recall in months. Default 6. |
| name: string, required |
The name of the payment plan |
| patient_friendly_name string, optional |
The name of the payment plan as seen by patients. If null, will default to the value of name. |
| scale_and_polish_duration integer, optional |
The duration of a scale and polish appointment in minutes, between 5 and 120. Default 10. |
| site_id uuid, optional |
The site the plan is associated with. If null then it is associated with all sites. |
EXAMPLE RESPONSE
{
"payment_plan": {
"id": 1,
"active": false,
"created_at": "2013-11-05T11:27:05.686+00:00",
"colour": "#FFFFFF",
"dentist_recall_interval": 6,
"emergency_duration": 15,
"exam_duration": 10,
"exam_scale_and_polish_duration": 20,
"hygienist_recall_interval": 6,
"name": "NHS",
"patient_friendly_name": "NHS Plan",
"scale_and_polish_duration": 10,
"site_id": "e1d854af-15db-4482-8e29-39e74a6c7f75"
}
}
Returns
The created payment plan object
List all payment plans
Returns a list of existing payment plans
DEFINITION
GET https://api.dentally.co/v1/payment_plans?{site_id, active}
EXAMPLE REQUEST
curl https://api.dentally.co/v1/payment_plans?active=true
Parameters
| site_id: string, optional |
Returns payment plans assigned to a specific site |
| active: boolean, optional |
Returns active payment plans if true or inactive if false |
EXAMPLE RESPONSE:
{
"payment_plans": [
{
"id": 1,
"active": true,
"created_at": "2013-11-05T11:27:05.686+00:00",
"colour": "#25B0E6",
"dentist_recall_interval": 6,
"emergency_duration": 15,
"exam_duration": 10,
"exam_scale_and_polish_duration": 20,
"hygienist_recall_interval": 6,
"name": "NHS",
"patient_friendly_name": "NHS Plan",
"scale_and_polish_duration": 10,
"site_id": "e1d854af-15db-4482-8e29-39e74a6c7f75"
},
{...}
],
"meta": {
"total": 2,
"page": 1
}
}
Returns
Returns a list of payment plans ordered by date of creation
Payments
The payment object
A payment belongs to a patient and can be matched to an invoice or multiple invoices
EXAMPLE RESPONSE
{
payment: {
"id": 1,
"account_id": 4511,
"amount": "18.5",
"amount_unexplained": "0.0",
"dated_on": "2015-01-19",
"deleted": false,
"fully_explained": true,
"method": "Debit Card",
"patient_id": 5106,
"payment_plan_id": 1,
"practitioner_id": 1,
"reference": "00001",
"site_id": "e1d854af-15db-4482-8e29-39e74a6c7f75",
"status": null,
"transaction_number": "6932",
"user_id": 271,
"explanations": [
{
"amount": "18.5",
"comments": null,
"id": 57,
"invoice_id": 51,
"invoice_reference": "00051",
"payment_id": 1,
"payment_reference": "00001",
"user_id": 253
}
]
}
}
ATTRIBUTES
| id: integer |
The ID of the payment |
| account_id: integer |
The account ID the payment is associated to. Usually this is the patient’s account ID |
| amount: string |
The payment amount |
| amount_unexplained: string |
The payment amount that is still to be explained |
| dated_on: date |
The date assigned to the payment |
| deleted: boolean |
If the payment has been delete or not |
| fully_explained: boolean |
If the payment has been fully explained or not |
| method: string |
The payment method used to make the payment |
| patient_id: integer |
The ID of the patient the payment is assigned to |
| payment_plan_id: integer |
The ID of the payment plan the payment is assigned to |
| practitioner_id: integer |
The ID of the practitioner the payment is assigned to |
| reference: string |
The payment reference number generated for the payment |
| site_id: string |
The ID of the site that the payment belongs to |
| status: string |
The status of a Dentally Pay payment |
| transaction_number: string |
The transaction number added to the payment |
| user_id: integer |
The ID of the user who took the payment |
| explanations: array |
List of payment explanations |
child attributes for explanation
| id: integer |
The ID of the explanation |
| amount: string |
The amount that is being explained |
| comments: string |
A comment describing what the payment was for |
| invoice_id: integer |
The ID of the invoice the payment is explaining |
| invoice_reference: string |
The invoice reference number of the invoice the payment is explaining |
| payment_id: integer |
The ID of the payment that the explanation is explaining |
| payment_reference: string |
The payment reference number of the payment the explanation is explaining |
| user_id: integer |
The ID of the user who created the explanation |
Create a payment
Creates a new payment
DEFINITION
POST https://api.dentally.co/v1/payments
EXAMPLE REQUEST
curl --include \
--request POST \
--header "Content-Type: application/json" \
--data-binary '{
"payment": {
"account_id": 1,
"amount": "100.00",
"dated_on": "2017-02-02",
"method": "Cash",
"patient_id": 1,
"payment_plan_id": 1
}
}' \
https://api.dentally.co/v1/payments
Parameters
Parameters must be wrapped by a payment object
| account_id: string, required |
The ID of the account that you would like to credit the payment to. This is usually the patient’s account but can be another account. |
| amount: string, required |
The total value of the payment |
| dated_on: date, required |
The date the payment was made. This is the date that it will be applied to the patient’s account. |
| method: string, required |
The method of the payment. Must be one of Credit Card, Debit Card, American Express, Cash, Cheque, BACS, Finance or Other |
| patient_id: integer, required |
The ID of the patient the payment is associated with. |
| payment_plan_id: integer, required |
The ID of the payment plan the payment is associated with. |
| practitioner_id: integer, optional |
The ID of the practitioner the payment is associated with. |
| site_id: string, optional |
The ID of the site that the payment belongs to. Will default to the user’s site if not specified |
| transaction_number: string, optional |
A transaction number which can be used to identify the payment with a third party system. |
EXAMPLE RESPONSE
{
"payment": {
"id": 1,
"account_id": 1,
"amount": "100.0",
"amount_unexplained": "100.0",
"dated_on": "2017-02-02",
"deleted": false,
"fully_explained": false,
"method": "Cash",
"patient_id": 1,
"payment_plan_id": 1,
"practitioner_id": null,
"reference": "00001",
"site_id": "e1d854af-15db-4482-8e29-39e74a6c7f75",
"status": null,
"transaction_number": null,
"user_id": 1,
"explanations": []
}
}
Returns
The newly created payment object
Get a single payment
Retrieves the details of a payment
DEFINITION
GET https://api.dentally.co/v1/payments/{PAYMENT_ID}
EXAMPLE REQUEST
curl https://api.dentally.co/v1/payments/1
Parameters
| id: | required |
Returns
The existing payment object
EXAMPLE RESPONSE
{
payment: {
"id": 1,
"account_id": 4511,
"amount": "18.5",
"amount_unexplained": "0.0",
"dated_on": "2015-01-19",
"deleted": false,
"fully_explained": true,
"method": "Debit Card",
"patient_id": 5106,
"payment_plan_id": 1,
"practitioner_id": 1,
"reference": "00001",
"site_id": "e1d854af-15db-4482-8e29-39e74a6c7f75",
"status": null,
"transaction_number": "6932",
"user_id": 271,
"explanations": [
{
"amount": "18.5",
"comments": null,
"id": 57,
"invoice_id": 51,
"invoice_reference": "00051",
"payment_id": 1,
"payment_reference": "00001",
"user_id": 253
}
]
}
}
Delete a payment
Deletes a payment. This should only be used when you want to remove a payment and any associated explanations.
DEFINITION
DELETE https://api.dentally.co/v1/payments/{PAYMENT_ID}
EXAMPLE REQUEST
curl --include \
--request DELETE \
https://api.dentally.co/v1/payments/1
Parameters
| id: integer |
required |
Returns
Returns a 204 response
List all payments
Returns a list of payments
DEFINITION
GET https://api.dentally.co/v1/payments?{account_id, dated_after, dated_before, patient_id, payment_plan_id, practitioner_id}
EXAMPLE REQUEST
curl http://api.dentally.co/v1/payments?dated_after=2016-01-05
Parameters
| account_id: string, optional |
Payments belonging to a specific account. Usually you will want to look up payments by a patient’s account ID rather than their patient ID |
| dated_after: date, optional |
After a date |
| dated_before: date, optional |
Before a date |
| patient_id: string, optional |
Payments belonging to a specific patient |
| payment_plan_id: string, optional |
Payments assigned to a specific payment plan |
| practitioner_id: string, optional |
Payments assigned to a specific practitioner |
| site_id: string, optional |
Payments assigned to a specific site |
EXAMPLE RESPONSE:
{
"payments": [
{
"id": 1,
"account_id": 4511,
"amount": "18.5",
"amount_unexplained": "0.0",
"dated_on": "2015-01-19",
"deleted": false,
"fully_explained": true,
"method": "Debit Card",
"patient_id": 5106,
"payment_plan_id": 1,
"practitioner_id": 1,
"reference": "00001",
"site_id": "e1d854af-15db-4482-8e29-39e74a6c7f75",
"status": null,
"transaction_number": "6932",
"user_id": 271,
"explanations": [
{
"amount": "18.5",
"comments": null,
"id": 57,
"invoice_id": 51,
"invoice_reference": "00051",
"payment_id": 1,
"payment_reference": "00001",
"user_id": 253
}
]
}
,
{...},
{...}
],
"meta": {
"current_page": 1,
"total": 3,
"total_amount": "854.04"
}
}
Returns
Returns a list of payments that match the query. The response includes a metadata object which contains the page number, the total number of payments and the total value of those payments.
Payment Allocations
The payment allocation object
A payment allocation has complex relation ship to multiple models concerning payments and the allocation of funds to them.
EXAMPLE RESPONSE
{
"payment_allocation": {
"id": "1f9db5de-b974-49e7-ac84-faee723ce3b1",
"amount": "23.0",
"created_at": "2021-03-01T12:30:02.720+00:00",
"description": "Payment #04847",
"invoice_item_id": null,
"patient_id": 1330,
"payment_explanation_id": null,
"reversal_of_id": null,
"transfer_from_id": 1331,
"transfer_from_type": "Account",
"transfer_to_id": "1bf77f81-5a46-410d-80e3-a6a257d7f328",
"transfer_to_type": "Site",
"updated_at": "2021-03-01T12:30:02.720+00:00"
}
}
ATTRIBUTES
| id: integer |
The ID of the payment allocation |
| amount: string |
The amount for this allocation |
| description string |
The allocation summary text |
| invoice_item_id integer |
An associated invoice item id (optional) |
| patient_id: integer |
The ID of the patient the allocation is assigned to |
| payment_explanation_id: integer |
The ID of explanation (optional) |
| reversal_of_id string |
The ID of a payment allocation when this is used in a reversal (optional) |
| transfer_from_id integer/string |
The ID of the transfer type, where the allocation came from |
| transfer_from_type string |
The object type for the associated from id |
| transfer_to_id integer/string |
The ID of the transfer type, where the allocation went to |
| transfer_to_type string |
The object type for the associated to id |
Get a single payment allocation
Retrieves the details of a payment allocation
DEFINITION
GET https://api.dentally.co/v1/payment_allocations/{PAYMENT_ALLOCATION_ID}
EXAMPLE REQUEST
curl https://api.dentally.co/v1/payment_allocations/1f9db5de-b974-49e7-ac84-faee723ce3b1
Parameters
| id: | required |
Returns
The existing payment allocation object
EXAMPLE RESPONSE
{
"payment_allocation": {
"id": "1f9db5de-b974-49e7-ac84-faee723ce3b1",
"amount": "23.0",
"created_at": "2021-03-01T12:30:02.720+00:00",
"description": "Payment #04847",
"invoice_item_id": null,
"patient_id": 1330,
"payment_explanation_id": null,
"reversal_of_id": null,
"transfer_from_id": 1331,
"transfer_from_type": "Account",
"transfer_to_id": "1bf77f81-5a46-410d-80e3-a6a257d7f328",
"transfer_to_type": "Site",
"updated_at": "2021-03-01T12:30:02.720+00:00"
}
}
List all payment allocations
Returns a list of payment allocations
DEFINITION
GET https://api.dentally.co/v1/payment_allocations?{transfer_to_id, transfer_from_id, transfer_id, transfer_type, created_at_before, created_at_after}
EXAMPLE REQUEST
curl http://api.dentally.co/v1/payment_allocationss?transfer_to_id=1bf77f81-5a46-410d-80e3-a6a257d7f328
curl http://api.dentally.co/v1/payment_allocationss?transfer_to_id=2&transfer_to_type=Practitioner
Parameters
| transfer_to_id: string, optional |
Returns all items transferred to this ID. If searching for an Account or a Practitioner by numeric ID, you must also include the transfer_to_type parameter. |
| transfer_to_type: string, optional |
Returns all items transferred to this type. |
| transfer_from_id: string, optional |
Returns all items transferred from this ID. If searching for an Account or a Practitioner by numeric ID, you must also include the transfer_from_type parameter. |
| transfer_to_type: string, optional |
Returns all items transferred from this type. |
| transfer_id: string, optional |
Returns all items from either from or to. |
| transfer_type: string, optional |
Returns all items of the given type. |
| created_at_before: datetime, optional |
Returns all items that were created before this time. |
| created_at_after: datetime, optional |
Returns all items were created after this time. |
EXAMPLE RESPONSE:
{
"payment_allocations": [
{
"id": "1f9db5de-b974-49e7-ac84-faee723ce3b1",
"amount": "23.0",
"created_at": "2021-03-01T12:30:02.720+00:00",
"description": "Payment #04847",
"invoice_item_id": null,
"patient_id": 1330,
"payment_explanation_id": null,
"reversal_of_id": null,
"transfer_from_id": 1331,
"transfer_from_type": "Account",
"transfer_to_id": "1bf77f81-5a46-410d-80e3-a6a257d7f328",
"transfer_to_type": "Site",
"updated_at": "2021-03-01T12:30:02.720+00:00"
}
,
{...},
{...}
],
"meta": {
"total": 108,
"current_page": 1,
"total_pages": 5
}
}
Returns
Returns a list of payment allocations that match the query. The response includes a metadata object which contains the page number, the total number of payment allocations found and the total pages.
Payment Explanations
The payment explanation object
A payment explanation is used to describe why the payment was made. Payment explanations must be associated with a payment and can optionally be associated with an invoice.
EXAMPLE RESPONSE
{
"explanation": {
"id": 1,
"amount": "100",
"comments": "Deposit for treatment",
"invoice_id": null,
"invoice_reference": null,
"payment_id": 1,
"payment_reference": "0001",
"user_id": 1
}
}
ATTRIBUTES
| id: integer |
The ID of the explanation |
| amount: string |
The amount that is being explained |
| comments: string |
A comment describing what the payment was for |
| invoice_id: integer |
The ID of the invoice the payment is explaining |
| invoice_reference: string |
The invoice reference number of the invoice the payment is explaining |
| payment_id: integer |
The ID of the payment that the explanation is explaining |
| payment_reference: string |
The payment reference number of the payment the explanation is explaining |
| user_id: integer |
The ID of the user who created the explanation |
Get a single payment explanation
Retrieves the details of a payment explanation
DEFINITION
GET https://api.dentally.co/v1/payment_explanation/{PAYMENT_EXPLANATION_ID}
EXAMPLE REQUEST
curl https://api.dentally.co/v1/payment_explanation/1
Parameters
| id: | required |
Returns
The existing payment explanation object
EXAMPLE RESPONSE
{
"explanation": {
"id": 1,
"amount": "100",
"comments": "Deposit for treatment",
"invoice_id": null,
"invoice_reference": null,
"payment_id": 1,
"payment_reference": "0001",
"user_id": 1
}
}
Create a payment explanation
Creates a new payment explanation
DEFINITION
POST https://api.dentally.co/v1/payments/{PAYMENT_ID}/explanations/
EXAMPLE REQUEST
curl --include \
--request POST \
--header "Content-Type: application/json" \
--data-binary '{
"explanation": {
"amount": "100",
"comments": "Deposit for treatment"
}
}' \
https://api.dentally.co/v1/payments
Parameters
Parameters must be wrapped by a explanation object
| amount: string, required |
The value of the payment that you would like to explain. This must be less than or equal to the total value of the payment |
| comments: string, required |
A comment describing what the payment was for |
EXAMPLE RESPONSE
{
"explanation": {
"id": 1,
"amount": "100",
"comments": "Deposit for treatment",
"invoice_id": null,
"invoice_reference": null,
"payment_id": 1,
"payment_reference": "0001",
"user_id": 1
}
}
Returns
The newly created payment explanation object
Delete a payment explanation
Deletes a payment explanation. You can also delete all explanations associated with a payment by deleting the associated payment object.
DEFINITION
DELETE https://api.dentally.co/v1/payments/{PAYMENT_ID}/explanations/{PAYMENT_EXPLANATION_ID}
EXAMPLE REQUEST
curl --include \
--request DELETE \
https://api.dentally.co/v1/payments/1/explanations/1
Parameters
| payment_id: integer |
required |
| payment_explanation_id: integer |
required |
Returns
Returns a 204 response
Practitioners
The practitioner object
A practitioner account belongs to a user
EXAMPLE RESPONSE
{
"practitioner": {
"id": 1,
"active": true,
"colour": "#6796f2",
"contract_targets": [
{
"id": 1,
"contract_id": "e1d854af-1rt-4455-8e29-39e74a6ch6d7",
"uda_target": 1,
"uoa_target": 1,
"default": true
}
],
"default_contract_id": "8aee9505-a6de-4517-87fb-764790fc9b04",
"gdc_number": null,
"nhs_number": null,
"site_id": "e1d854af-15db-4482-8e29-39e74a6c7f75",
"user": {
"id": 1,
"created_at": "2013-11-04T02:47:17.380+00:00",
"email": "ross@hepburn.com",
"first_name": "Ross",
"image_url": "https://www.gravatar.com/avatar/672a9f4da85d4b2026059973b84dd827.jpg?&r=pg&d=identicon&s=100",
"last_login": "2016-01-26T10:24:07.961+00:00",
"last_name": "Hepburn",
"middle_name": null,
"mobile_phone": "07123456789",
"permission_level": 4,
"role": "Dentist",
"title": "Mx",
"updated_at": "2015-01-02T12:02:52.402+00:00"
}
}
}
ATTRIBUTES
| id: integer |
The ID of the practitioner |
| active: boolean |
If set to false the practitioner will be hidden in Dentally |
| colour: string |
The practitioner’s colour. Must be in hexadecimal format, e.g. #FFFFFF |
| contract_targets: array |
The practitioner’s associated contracts and targets |
| default_contract_id: uuid |
The ID of the practitioner’s default NHS contract |
| gdc_number: string |
The practitioner’s GDC number |
| nhs_number: string |
The practitioner’s NHS number |
| site_id: string |
The ID of the site that the practitioner belongs to |
| user: string |
The practitioners user account |
child attributes for user
| id: integer |
The ID of the user |
| created_at: datetime |
The date and time the user was created |
| email: string |
The user’s email address |
| first_name: string |
The user’s first name |
| image_url: string |
URL of the user’s profile image |
| last_login: datetime |
The date and time the user last logged in |
| last_name: string |
The user’s last name |
| middle_name: string |
The user’s middle name |
| mobile_phone: string |
The user’s mobile phone number |
| permission_level: integer |
The user’s permission level. Can range between 0 and 4. Further details on permission levels can be found here |
| role: string |
The user’s role. Must be one of Administrator, Dentist, Hygienist, Nurse, Practice Manager, Receptionist, Technician, Therapist |
| updated_at: datetime |
The date and time the user was last updated. |
child attributes for contract targets
| id: integer |
The ID of the contract target |
| contract_id: uuid |
The ID of the practitioner’s NHS contract |
| uda_target: integer |
The NHS UDA target value |
| uoa_target: integer |
The NHS UOA target value |
| default: boolean |
Determines if this contract is the practitioner’s default NHS contract |
Get a single practitioner
Retrieves the details of an existing practitioner with the associated user
DEFINITION
GET https://api.dentally.co/v1/practitioners/{PRACTITIONER_ID}
EXAMPLE REQUEST
curl https://api.dentally.co/v1/practitioners/1
Parameters
| id: | required |
Returns
The existing practitioner object
EXAMPLE RESPONSE
{
"practitioner": {
"id": 1,
"active": true,
"colour": "#9CCB3B",
"contract_targets": [
{
"id": 1,
"contract_id": "e1d854af-1rt-4455-8e29-39e74a6ch6d7",
"uda_target": 1,
"uoa_target": 1,
"default": true
}
],
"default_contract_id": "8aee9505-a6de-4517-87fb-764790fc9b04",
"gdc_number": null,
"nhs_number": null,
"site_id": "e1d854af-15db-4482-8e29-39e74a6c7f75",
"user": {
"id": 4,
"created_at": "2013-11-05T11:26:52.904+00:00",
"email": "user@dentalpractice.com",
"first_name": "Greg",
"image_url": "https://www.gravatar.com/avatar/0242720e04226d4d190f9ffc15a2644b.jpg?&r=pg&d=identicon&s=100",
"last_login": "2015-01-05T11:03:01.020+00:00",
"last_name": "Hays",
"middle_name": null,
"mobile_phone": null,
"permission_level": 4,
"role": "Dentist",
"title": "Mx",
"updated_at": "2015-01-02T12:02:52.402+00:00"
}
}
}
Edit a practitioner
Updates an existing practitioner
DEFINITION
PUT/PATCH https://api.dentally.co/v1/practitioners/{PRACTITIONER_ID}
EXAMPLE REQUEST
curl --include \
--request PUT \
--header "Content-Type: application/json" \
--data-binary '{
"practitioner": {
"gdc_number": "12345"
}
}' \
https://api.dentally.co/v1/practitioners/1
Parameters
Parameters must be wrapped by a practitioner object
| active: boolean, optional |
If set to false the practitioner will be hidden in Dentally |
| colour: string, optional |
The practitioner’s colour. Must be in hexadecimal format, e.g. #FFFFFF |
| gdc_number: string, optional |
The practitioner’s GDC number |
| nhs_number: string, optional |
The practitioner’s NHS number |
EXAMPLE RESPONSE
{
"practitioner": {
"id": 1,
"active": true,
"colour": "#9CCB3B",
"contract_targets": [
{
"id": 1,
"contract_id": "e1d854af-1rt-4455-8e29-39e74a6ch6d7",
"uda_target": 1,
"uoa_target": 1,
"default": true
}
],
"default_contract_id": "8aee9505-a6de-4517-87fb-764790fc9b04",
"gdc_number": "12345",
"nhs_number": null,
"site_id": "e1d854af-15db-4482-8e29-39e74a6c7f75",
"user": {
"id": 4,
"created_at": "2013-11-05T11:26:52.904+00:00",
"email": "user@dentalpractice.com",
"first_name": "Greg",
"image_url": "https://www.gravatar.com/avatar/0242720e04226d4d190f9ffc15a2644b.jpg?&r=pg&d=identicon&s=100",
"last_login": "2015-01-05T11:03:01.020+00:00",
"last_name": "Hays",
"middle_name": null,
"mobile_phone": null,
"permission_level": 4,
"role": "Dentist",
"title": "Mx",
"updated_at": "2015-01-02T12:02:52.402+00:00"
}
}
}
Returns
The updated practitioner object with the associated user.
List all practitioners
Returns a list of existing practitioners
DEFINITION
GET https://api.dentally.co/v1/practitioners?{site_id, created_after, updated_after}
EXAMPLE REQUEST
curl https://api.dentally.co/v1/practitioners?site_id=e1d854af-15db-4482-8e29-39e74a6c7f75
curl https://api.dentally.co/v1/practitioners?site_id[]=8af3d10a-9c1d-415f-941e-2094d45dc08a&site_id[]=e1d854af-15db-4482-8e29-39e74a6c7f75
Parameters
| site_id: string |
The ID of the site that the practitioner belongs to |
| site_id: array |
An array of site IDs that the practitioner belongs to |
| created_after: datetime |
The date and time the practitioner was created |
| updated_after: datetime |
The date and time the practitioner was updated |
EXAMPLE RESPONSE:
{
"practitioners": [
{
"id": 1,
"active": true,
"colour": "#9CCB3B",
"contract_targets": [
{
"id": 1,
"contract_id": "e1d854af-1rt-4455-8e29-39e74a6ch6d7",
"uda_target": 1,
"uoa_target": 1,
"default": true
}
],
"default_contract_id": "8aee9505-a6de-4517-87fb-764790fc9b04",
"gdc_number": null,
"nhs_number": null,
"site_id": "e1d854af-15db-4482-8e29-39e74a6c7f75",
"user": {
"id": 4,
"created_at": "2013-11-05T11:26:52.904+00:00",
"email": "user@dentalpractice.com",
"first_name": "Greg",
"image_url": "https://www.gravatar.com/avatar/0242720e04226d4d190f9ffc15a2644b.jpg?&r=pg&d=identicon&s=100",
"last_login": "2015-01-05T11:03:01.020+00:00",
"last_name": "Hays",
"middle_name": null,
"mobile_phone": null,
"permission_level": 4,
"role": "Dentist",
"title": "Mx",
"updated_at": "2015-01-02T12:02:52.402+00:00"
}
},
{...}
],
"meta": {
"total": 2,
"page": 1
}
}
Returns
Returns a list of practitioners ordered by ID
PRSI Eligibilities
The PRSI eligibility object
A PRSI eligibility belongs to a patient
EXAMPLE RESPONSE
{
"prsi_eligibility": {
"id": "d7c1781a-2d7d-4d50-8de8-a2b5e5306a91",
"eligible_check_date": "2024-04-19T00:00:00.000+01:00",
"exam_eligible_status": "Eligible",
"hygienist_eligible_status": "Eligible",
"expiry_date": "2025-04-19T00:00:00.000+01:00",
"patient_consented": true,
"patient_id": "0f4a6af2-2a52-4be5-a27a-a49f52b7f381",
"user_id": 1,
"site_id": "0406e162-58c5-4384-bfe0-e842ab4fa4cf",
"created_at": "2024-05-02T08:53:55.585+01:00",
"updated_at": "2024-05-02T08:53:55.585+01:00"
}
}
ATTRIBUTES
| id: integer |
The PRSI eligibility ID |
| eligible_check_date: datetime |
The time and date of eligibility check |
| exam_eligible_status: string |
The exam eligibility status. It must be one of Eligible, Expired, Used, None. Default None |
| hygienist_eligible_status: string |
The hygienist eligibility status. It must be one of Eligible, Expired, Used, None. Default None |
| expiry_date: datetime |
The time and date the PRSI eligibility will expire |
| patient_consented: boolean |
The PRSI eligibility patient consent status. Set to true if the patient has consented. Default false |
| patient_id: integer |
The ID of the patient |
| user_id: integer |
The ID of the user who created the appointment |
| site_id: string |
The ID of the site |
| created_at: datetime |
The time and date the PRSI eligibility record was created |
| updated_at: datetime |
The date and time the PRSI eligibility details were last updated |
List all PRSI eligibilites
Returns a list of PRSI eligibilities
DEFINITION
GET https://api.dentally.co/v1/prsi_eligibilities
EXAMPLE REQUEST
curl https://api.dentally.co/v1/prsi_eligibilities?eligible_check_date_after=2024-02-29
Parameters
| eligible_check_date_after: datetime, optional |
Returns all PRSI eligibilities that have been check date after this time |
| eligible_check_date_before: datetime, optional |
Returns all PRSI eligibilities that have been check date before this time |
| expiry_date_after: datetime, optional |
Returns all PRSI eligibilities that have been expiry date after this time |
| expiry_date_before: datetime, optional |
Returns all PRSI eligibilities that have been expiry date before this time |
| hygienist_eligible_status: boolean, optional |
Returns all PRSI eligibilities that have hygienist eligible status or not |
| exam_eligible_status: boolean, optional |
Returns all PRSI eligibilities that have exam eligible status or not |
| patient_consented: boolean, optional |
Returns all PRSI eligibilities that have patient consented or not |
| site_id: string, optional |
PRSI eligibilities assigned to a specific site |
| patient_id: string, optional |
PRSI eligibilities assigned to a specific patient |
EXAMPLE RESPONSE:
{
"prsi_eligibilities": [
{
"id": "80d0d7be-b2da-4cc8-833a-fefea0d17456",
"created_at": "2024-05-02T08:53:43.799+01:00",
"eligible_check_date": "2024-04-19T00:00:00.000+01:00",
"exam_eligible_status": "Eligible",
"expiry_date": "2025-04-19T00:00:00.000+01:00",
"hygienist_eligible_status": "Eligible",
"patient_consented": true,
"patient_id": "0f4a6af2-2a52-4be5-a27a-a49f52b7f381",
"site_id": "0406e162-58c5-4384-bfe0-e842ab4fa4cf",
"updated_at": "2024-05-02T08:53:43.799+01:00",
"user_id": 1
},
{
"id": "d7c1781a-2d7d-4d50-8de8-a2b5e5306a91",
"created_at": "2024-05-02T08:53:55.585+01:00",
"eligible_check_date": "2024-04-19T00:00:00.000+01:00",
"exam_eligible_status": "Eligible",
"expiry_date": "2025-04-19T00:00:00.000+01:00",
"hygienist_eligible_status": "Eligible",
"patient_consented": true,
"patient_id": "0f4a6af2-2a52-4be5-a27a-a49f52b7f381",
"site_id": "0406e162-58c5-4384-bfe0-e842ab4fa4cf",
"updated_at": "2024-05-02T08:53:55.585+01:00",
"user_id": 1
}
],
"meta": {
"total": 2,
"current_page": 1,
"total_pages": 1
}
}
Returns
Returns a list of PRSI eligibilities that match the query. The response includes a metadata object which contains the page number that was returned as well as the total number of PRSI eligibilities that match the query. The PRSI eligibilities are returned in the order that best matches the query
Get a single PRSI eligibility
Retrieves the details of a PRSI eligibility
DEFINITION
GET https://api.dentally.co/v1/prsi_eligibilities/{PRSI_ELIGIBILITY_ID}
EXAMPLE REQUEST
curl https://api.dentally.co/v1/prsi_eligibilities/d7c1781a-2d7d-4d50-8de8-a2b5e5306a91
Parameters
| id: | required |
Returns
The existing PRSI eligibility object
EXAMPLE RESPONSE
{
"prsi_eligibility": {
"id": "d7c1781a-2d7d-4d50-8de8-a2b5e5306a91",
"created_at": "2024-05-02T08:53:55.585+01:00",
"eligible_check_date": "2024-04-19T00:00:00.000+01:00",
"exam_eligible_status": "Eligible",
"expiry_date": "2025-04-19T00:00:00.000+01:00",
"hygienist_eligible_status": "Eligible",
"patient_consented": true,
"patient_id": "0f4a6af2-2a52-4be5-a27a-a49f52b7f381",
"site_id": "0406e162-58c5-4384-bfe0-e842ab4fa4cf",
"updated_at": "2024-05-02T08:53:55.585+01:00",
"user_id": 1
}
}
Edit a PRSI eligibility
Updates an existing PRSI eligibility
DEFINITION
PUT/PATCH https://api.dentally.co/v1/prsi_eligibilities/{PRSI_ELIGIBILITY_ID}
EXAMPLE REQUEST
curl --include \
--request PATCH \
--header "Content-Type: application/json" \
--data-binary '{
"prsi_eligibility":
{
"exam_eligible_status": "Expired",
"hygienist_eligible_status": "Eligible"
}
}' \
https://api.dentally.co/v1/prsi_eligibilities
Parameters
Parameters must be wrapped by a prsi_eligibility object
| patient_id: string, required |
The ID of the patient the PRSI eligibility is associated with |
| patient_consented: boolean, required |
The PRSI eligibility patient consent status. Set to true if the patient has consented. Default false |
| eligible_check_date: datetime, required |
The time and date of eligibility check |
| expiry_date: datetime, required |
The time and date the PRSI eligibility will expire |
| hygienist_eligible_status: string, optional |
The hygienist eligibility status. It must be one of Eligible, Expired, Used, None. Default None |
| exam_eligible_status: string, optional |
The exam eligibility status. It must be one of Eligible, Expired, Used, None. Default None |
| site_id: string, optional |
The ID of the site associated to the PRSI eligibility |
EXAMPLE RESPONSE
{
"prsi_eligibility": {
"id": "d7c1781a-2d7d-4d50-8de8-a2b5e5306a91",
"created_at": "2024-05-02T08:53:55.585+01:00",
"eligible_check_date": "2024-04-19T00:00:00.000+01:00",
"exam_eligible_status": "Expired",
"expiry_date": "2025-04-19T00:00:00.000+01:00",
"hygienist_eligible_status": "Eligible",
"patient_consented": true,
"patient_id": "0f4a6af2-2a52-4be5-a27a-a49f52b7f381",
"site_id": "0406e162-58c5-4384-bfe0-e842ab4fa4cf",
"updated_at": "2024-05-02T10:58:22.511+01:00",
"user_id": 1
}
}
Returns
The updated PRSI eligibility object
Create a PRSI eligibility
Creates a new PRSI eligibility
DEFINITION
POST https://api.dentally.co/v1/prsi_eligibilities
EXAMPLE REQUEST
curl --include \
--request POST \
--header "Content-Type: application/json" \
--data-binary '{
"prsi_eligibility":
{
"patient_id": "0f4a6af2-2a52-4be5-a27a-a49f52b7f381",
"patient_consented": true,
"eligible_check_date": "19/04/2024",
"expiry_date": "19/04/2025"
}
}' \
https://api.dentally.co/v1/prsi_eligibilities
Parameters
Parameters must be wrapped by a prsi_eligibility object
| patient_id: string, required |
The ID of the patient the PRSI eligibility is associated with |
| patient_consented: boolean, required |
The PRSI eligibility patient consent status. Set to true if the patient has consented. Default false |
| eligible_check_date: datetime, required |
The time and date of eligibility check |
| expiry_date: datetime, required |
The time and date the PRSI eligibility will expire |
| hygienist_eligible_status: string, optional |
The hygienist eligibility status. It must be one of Eligible, Expired, Used, None. Default None |
| exam_eligible_status: string, optional |
The exam eligibility status. It must be one of Eligible, Expired, Used, None. Default None |
| site_id: string, optional |
The ID of the site associated to the PRSI eligibility |
EXAMPLE RESPONSE
{
"prsi_eligibility": {
"id": "02d0f5f6-30e2-46aa-a257-036c3e744d9d",
"created_at": "2024-05-02T10:16:42.382+01:00",
"eligible_check_date": "2024-04-19T00:00:00.000+01:00",
"exam_eligible_status": "None",
"expiry_date": "2025-04-19T00:00:00.000+01:00",
"hygienist_eligible_status": "None",
"patient_consented": true,
"patient_id": "0f4a6af2-2a52-4be5-a27a-a49f52b7f381",
"site_id": "0406e162-58c5-4384-bfe0-e842ab4fa4cf",
"updated_at": "2024-05-02T10:16:42.382+01:00",
"user_id": 1
}
}
Returns
The newly created PRSI eligibility object
Delete a PRSI eligibility
Deletes a PRSI eligibility. This should be used when you want to remove a PRSI eligibility.
DEFINITION
DELETE https://api.dentally.co/v1/prsi_eligibilities/{PRSI_ELIGIBILITY_ID}
EXAMPLE REQUEST
curl --include \
--request DELETE \
https://api.dentally.co/v1/prsi_eligibilities/90205d1d-9e07-43ee-9a95-245995cb1f42
Parameters
| id: | required |
Returns
Returns a 204 response
Recalls
The recall object
The recall object stores details about recalls sent to patients.
EXAMPLE RESPONSE
{
"recall": {
"appointment_id": "de63f346-5426-4321-45t4-7c0aar13e443",
"due_date": "2021-09-30",
"first_reminder_id": "fe53d337-4693-4478-86b9-8b0aaa13e483",
"first_reminder_sent_at": "2021-09-30T13:24:57.107+01:00",
"first_reminder_type": "Email",
"id": "4cefeeed-0723-4095-8b0d-ff16943d1af8",
"last_reminded_at": "2021-09-30T13:24:57.107+01:00",
"latest_reminder_type": "Email",
"patient_id": 2,
"reminders": [
{
"type": "Email",
"id": "fe53d337-4693-4478-86b9-8b0aaa13e483",
"date": "2021-09-30T13:24:57.107+01:00",
"template_name": "Default recall template"
},
{
"type": "Letter",
"id": "45b14ca1-4b59-475c-80af-7f711ba1fd8e",
"date": "2021-09-30T13:24:57.107+01:00",
"template_name": "Default recall template"
}
],
"recall_method": "SMS",
"recall_type": "Dentist",
"second_reminder_id": "45b14ca1-4b59-475c-80af-7f711ba1fd8e",
"second_reminder_sent_at": "2021-09-30T13:24:57.107+01:00",
"second_reminder_type": "Letter",
"status": "Completed",
"times_contacted": 2,
"run_date": null,
"workflow_stage_id": null,
"workflow_status": "unprocessed"
}
}
ATTRIBUTES
| appointment_id: uuid |
The ID of the appointment |
| due_date: date |
The date time the recall is due |
| first_reminder_id: uuid |
The ID of the first recall reminder |
| first_reminder_sent_at: datetime |
The date and time the first recall reminder is sent |
| first_reminder_type: string |
The correspondence type for the reminder that is sent |
| id: uuid |
The ID of the recall |
| last_reminded_at: datetime |
The ID of the site that the practitioner belongs to |
| patient_id: integer |
The ID of the patient |
| reminders: json |
The reminder correspondence type, id, date and template_name used |
| recall_method: string |
The method of recall. Must be Letter, SMS, Recall, Phone |
| recall_type: string |
The type of dental recall. Must be Dentist, Hygienist, Dentist + Hygienist |
| second_reminder_id: uuid |
The ID of the second recall reminder |
| second_reminder_sent_at: datetime |
The date and time the first recall reminder is sent |
| second_reminder_type: string |
The correspondence type of the second reminder that is sent |
| status: string |
The state of the recall. Must be Unbooked, Booked, Completed, Skipped, Missed |
| times_contacted: integer |
The number of times the patient has been sent a reminder |
| run_date: date |
The date the recall workflow was last run |
| workflow_stage_id: uuid |
The ID of the recall workflow stage |
| workflow_status: integer |
The recall workflow status. Must be unprocessed: 0, processing: 1, completed: 2, exhausted: 3, error: 4 |
List all recalls
Returns a list of recalls
DEFINITION
GET https://api.dentally.co/v1/recalls?{created_after, created_before, updated_after}
EXAMPLE REQUEST
curl https://api.dentally.co/v1/recalls
Parameters
| created_after datetime |
Request entries created on or after |
| created_before datetime |
Request entries created on or before |
| updated_after datetime |
Request entries created on or after |
EXAMPLE RESPONSE:
{
"recalls": [
{
"appointment_id": 1,
"due_date": "2021-09-30",
"first_reminder_id": "fe53d337-4693-4478-86b9-8b0aaa13e483",
"first_reminder_sent_at": "2021-09-30T13:24:57.107+01:00",
"first_reminder_type": "Email",
"id": "4cefeeed-0723-4095-8b0d-ff16943d1af8",
"last_reminded_at": "2021-09-30T13:24:57.107+01:00",
"latest_reminder_type": "Email",
"patient_id": 2,
"reminders": [
{
"type": "Email",
"id": "fe53d337-4693-4478-86b9-8b0aaa13e483",
"date": "2021-09-30T13:24:57.107+01:00",
"template_name": "Default recall template"
},
{
"type": "Letter",
"id": "45b14ca1-4b59-475c-80af-7f711ba1fd8e",
"date": "2021-09-30T13:24:57.107+01:00",
"template_name": "Default recall template"
}
],
"recall_method": "SMS",
"recall_type": "Dentist",
"second_reminder_id": "45b14ca1-4b59-475c-80af-7f711ba1fd8e",
"second_reminder_sent_at": "2021-09-30T13:24:57.107+01:00",
"second_reminder_type": "Letter",
"status": "Completed",
"times_contacted": 2,
"run_date": null,
"workflow_stage_id": null,
"workflow_status": "unprocessed"
}
],
"meta": {
"total": 1,
"current_page": 1,
"total_pages": 1
}
}
Returns
Returns a list of recalls
Rooms
The site object
A room is a physical location within a dental practice. Practices can have many rooms
EXAMPLE RESPONSE
{
"room": {
"id": "04b2db45-455a-42f7-b9ce-99fa6b0c741b",
"calendar_position": null,
"colour": "#A3F137",
"name": "Surgery 3",
"created_at": "2018-01-02T15:27:15.461+00:00",
"updated_at": "2018-01-02T15:27:15.461+00:00",
"import_id": null,
"practice_id": 1,
"site_id": "e1d854af-15db-4482-8e29-39e74a6c7f75"
}
}
ATTRIBUTES
| id: uuid |
The ID of the room |
| calendar_position: integer |
The calendar position of the room. |
| colour: string |
The colour of the room in the calendar |
| name: string |
The name of the room. |
| created_at: datetime |
The creation date and time of the room in Dentally |
| updated_at: datetime |
The last updated date and time of the room in Dentally |
| import_id: string |
An ID that identifies the record when imported from another system |
| practice_id: integer |
An ID that identifies the practice this room belongs to |
| site_id: uuid |
An ID that identifies the site this room belongs to |
Get a single room
Retrieves the details of an existing room
DEFINITION
GET https://api.dentally.co/v1/rooms/{ROOM_ID}
EXAMPLE REQUEST
curl https://api.dentally.co/v1/rooms/04b2db45-455a-42f7-b9ce-99fa6b0c741b"
Parameters
| id: | required |
Returns
The existing room object
EXAMPLE RESPONSE
{
"room": {
"id": "04b2db45-455a-42f7-b9ce-99fa6b0c741b",
"calendar_position": null,
"colour": "#A3F137",
"name": "Surgery 3",
"created_at": "2018-01-02T15:27:15.461+00:00",
"updated_at": "2018-01-02T15:27:15.461+00:00",
"import_id": null,
"practice_id": 1,
"site_id": "e1d854af-15db-4482-8e29-39e74a6c7f75"
}
}
List all rooms
Returns a list of existing rooms
DEFINITION
GET https://api.dentally.co/v1/rooms
EXAMPLE REQUEST
curl https://api.dentally.co/v1/rooms
Parameters
Parameters are not mutually exclusive and can be combined to build up complex queries
| site_id: UUID, optional |
From a specified site |
EXAMPLE RESPONSE:
{
"rooms": [
{
"id": "984deaaf-9218-48fe-9034-20d0fe44f946",
"calendar_position": null,
"colour": "#a660a6",
"name": "Surgery 1",
"created_at": "2017-01-26T14:49:47.426+00:00",
"updated_at": "2017-01-26T14:49:47.426+00:00",
"import_id": null,
"practice_id": 1,
"site_id": "e1d854af-15db-4482-8e29-39e74a6c7f75"
},
{
"id": "202a329a-93b7-45ad-88df-b8336b97e694",
"calendar_position": null,
"colour": "#3753EA",
"name": "Surgery 2",
"created_at": "2017-04-18T10:03:13.951+01:00",
"updated_at": "2017-04-18T10:03:13.951+01:00",
"import_id": null,
"practice_id": 1,
"site_id": "e1d854af-15db-4482-8e29-39e74a6c7f75"
}],
"meta": {
"total": 4,
"current_page": 1,
"total_pages": 1
}
}
Returns
Returns a list of rooms
Practitioner Diary
The practitioner diary object
Practitioner Diaries detail when a practitioner was scheduled to work. This requires the Rota feature to be enabled for the practice.
EXAMPLE RESPONSE
{
"rota_practitioner_diary": {
"id": "d6df1c88-b9b2-423d-8de8-62027e0ba0ab",
"day": "2021-08-23",
"end_time": "2021-08-23T15:00:00.000+01:00",
"start_time": "2021-08-23T10:00:00.000+01:00",
"unavailable": false,
"practitioner_id": "1",
"breaks": [
{
"id": "8c9c7d2a-6d1a-4786-98aa-2cbd6f1af3df",
"name": "Lunch",
"start_time": "2021-08-23T12:00:00.000+01:00",
"end_time": "2021-08-23T13:00:00.000+01:00"
},
{
"id": "767dcafb-0e13-45dd-9c55-c3f1f47eca38",
"name": "Tea",
"start_time": "2021-08-23T15:00:00.000+01:00",
"end_time": "2021-08-23T15:15:00.000+01:00"
}
]
}
}
ATTRIBUTES
| id uuid |
UUID of the record |
| day date |
Date the record is valid for |
| end_time timestamp |
Rota entry end time |
| start_time timestamp |
Rota entry start time |
| unavailable boolean |
Marked as practitioner unavailable |
| practitioner_id integer |
UUID of the practitioner |
| breaks: array |
The list of breaks for the day |
child attributes for break
| id: uuid |
UUID of the break |
| name: string |
Optional name of the break |
| start_time: timestamp |
Break start time |
| end_time: timestamp |
Break end time |
List all practitioner diaries
Returns a list of existing practitioner diaries. Note that these are generated at most 4 years into the future.
DEFINITION
GET https://api.dentally.co/v1/rota_practitioner_diaries?{after, before, practitioner_id, site_id}
EXAMPLE REQUEST
curl https://api.dentally.co/v1/rota_practitioner_diaries?after=2021-08-21&before=2021-08-25
Parameters
| after required datetime |
Request entries on or after |
| before required datetime |
Request entries on or before |
| practitioner_id integer |
Filter to entries for this practitioner |
| site_id uuid |
Filter to entries for this site |
EXAMPLE RESPONSE:
{
"rota_practitioner_diaries": [
{
"id": "d6df1c88-b9b2-423d-8de8-62027e0ba0ab",
"day": "2021-08-23",
"end_time": "2021-08-23T15:00:00.000+01:00",
"start_time": "2021-08-23T10:00:00.000+01:00",
"unavailable": false,
"practitioner_id": "1",
"breaks": [
{
"id": "8c9c7d2a-6d1a-4786-98aa-2cbd6f1af3df",
"name": "Lunch",
"start_time": "2021-08-23T12:00:00.000+01:00",
"end_time": "2021-08-23T13:00:00.000+01:00"
},
{
"id": "767dcafb-0e13-45dd-9c55-c3f1f47eca38",
"name": "Tea",
"start_time": "2021-08-23T15:00:00.000+01:00",
"end_time": "2021-08-23T15:15:00.000+01:00"
}
]
}
],
"meta": {
"total": 1,
"current_page": 1,
"total_pages": 1
}
}
Returns
Returns a list of practitioner diaries ordered by day
Sites
The site object
A site is the physical location of a dental practice. Practices can have many sites
EXAMPLE RESPONSE
{
"site": {
"id": "e1d854af-15db-4482-8e29-39e74a6c7f75",
"active": true,
"address_line_1": "126 The Crescent",
"address_line_2": "",
"default_payment_plan_id": 426,
"email_address": "site@dentalpractice.com",
"logo_url": "https://dentally.co/api-practice-logo.png",
"name": "Dentally Dental",
"nickname": "Dentaly",
"phone_number": "020134848228",
"postcode": "W1A 1AA",
"practice_id": "c687bd0b-b35c-44ac-81d5-aebc3b9310a6",
"town": "Pontyberem",
"website": "dentalpractice.com",
"opening_hours": {
"Monday": { "open": "09:00", "close": "17:00" },
"Tuesday": { "open": "09:00", "close": "17:00" },
"Wednesday": { "open": "09:00", "close": "17:00" },
"Thursday": { "open": "09:00", "close": "17:00" },
"Friday": { "open": "09:00", "close": "17:00" }
},
}
}
ATTRIBUTES
| id: string |
The ID of the site |
| active: boolean |
If the site is active true or has been deactivated false |
| address_line_1: string |
The first line of the site’s address |
| address_line_2: string |
The second line of the site’s address |
| default_payment_plan_id: integer |
The ID of the default payment plan. |
| email_address: string |
The site’s email address |
| logo_url: string |
The URL of the site’s logo |
| name: string |
The name of the site |
| nickname: string |
The nickname of the site - used within Dentally only |
| phone_number: string |
The phone number for the site |
| postcode: string |
The postcode for the site |
| town: string |
The town the site resides |
| website: string |
The website address of the site |
| opening_hours: hash |
A hash containing the days of the week that a site is open and the corresponding opening and closing time for each day. |
Get a single site
Retrieves the details of an existing site
DEFINITION
GET https://api.dentally.co/v1/sites/{SITE_ID}
EXAMPLE REQUEST
curl https://api.dentally.co/v1/sites/e1d854af-15db-4482-8e29-39e74a6c7f75
Parameters
| id: | required |
Returns
The existing site object
EXAMPLE RESPONSE
{
"site": {
"id": "e1d854af-15db-4482-8e29-39e74a6c7f75",
"active": true,
"address_line_1": "126 The Crescent",
"address_line_2": "",
"default_payment_plan_id": 426,
"logo_url": "https://dentally.co/api-practice-logo.png",
"name": "Dentally Dental",
"nickname": "Dentaly",
"phone_number": "020134848228",
"postcode": "W1A 1AA",
"practice_id": "c687bd0b-b35c-44ac-81d5-aebc3b9310a6",
"town": "Pontyberem",
"website": "dentalpractice.com",
"opening_hours": {
"Monday": { "open": "09:00", "close": "17:00" },
"Tuesday": { "open": "09:00", "close": "17:00" },
"Wednesday": { "open": "09:00", "close": "17:00" },
"Thursday": { "open": "09:00", "close": "17:00" },
"Friday": { "open": "09:00", "close": "17:00" }
},
}
}
Edit a site
Updates an existing site
DEFINITION
PUT/PATCH https://api.dentally.co/v1/sites/{SITE_ID}
EXAMPLE REQUEST
curl --include \
--request PUT \
--header "Content-Type: application/json" \
--data-binary '{
"site": {
"nickname": "Site One"
}
}' \
https://api.dentally.co/v1/sites/e1d854af-15db-4482-8e29-39e74a6c7f75
Parameters
Parameters must be wrapped by a site object
| address_line_1: string, optional |
The first line of the site’s address |
| address_line_2: string, optional |
The second line of the site’s address |
| default_payment_plan_id: integer, optional |
The ID of the default payment plan. |
| email_address: string, optional |
The site’s email address |
| name: string, optional |
The name of the site |
| nickname: string, optional |
The nickname of the site - used within Dentally only |
| phone_number: string, optional |
The phone number for the site |
| postcode: string, optional |
The postcode for the site |
| town: string, optional |
The town the site resides |
| website: string, optional |
The website address of the site |
EXAMPLE RESPONSE
{
"site": {
"id": "e1d854af-15db-4482-8e29-39e74a6c7f75",
"active": true,
"address_line_1": "126 The Crescent",
"address_line_2": "",
"default_payment_plan_id": 426,
"email_address": "site@dentalpractice.com",
"logo_url": "https://dentally.co/api-practice-logo.png",
"name": "Dentally Dental",
"nickname": "Site One",
"phone_number": "020134848228",
"postcode": "W1A 1AA",
"practice_id": "c687bd0b-b35c-44ac-81d5-aebc3b9310a6",
"town": "Pontyberem",
"website": "dentalpractice.com",
"opening_hours": {
"Monday": { "open": "09:00", "close": "17:00" },
"Tuesday": { "open": "09:00", "close": "17:00" },
"Wednesday": { "open": "09:00", "close": "17:00" },
"Thursday": { "open": "09:00", "close": "17:00" },
"Friday": { "open": "09:00", "close": "17:00" }
},
}
}
Returns
The updated site
List all sites
Returns a list of existing sites
DEFINITION
GET https://api.dentally.co/v1/sites
EXAMPLE REQUEST
curl https://api.dentally.co/v1/sites
Parameters
None
EXAMPLE RESPONSE:
{
"sites": [
{
"id": "e1d854af-15db-4482-8e29-39e74a6c7f75",
"active": true,
"address_line_1": "126 The Crescent",
"address_line_2": "",
"default_payment_plan_id": 426,
"logo_url": "https://dentally.co/api-practice-logo.png",
"name": "Dentally Dental",
"nickname": "Site One",
"phone_number": "020134848228",
"postcode": "W1A 1AA",
"practice_id": "c687bd0b-b35c-44ac-81d5-aebc3b9310a6",
"town": "Pontyberem",
"website": "dentalpractice.com",
"opening_hours": {
"Monday": { "open": "09:00", "close": "17:00" },
"Tuesday": { "open": "09:00", "close": "17:00" },
"Wednesday": { "open": "09:00", "close": "17:00" },
"Thursday": { "open": "09:00", "close": "17:00" },
"Friday": { "open": "09:00", "close": "17:00" }
},
},
{...}
],
"meta": {
"total": 2,
"page": 1
}
}
Returns
Returns a list of sites
Session Appointments
List all session appointments
DEFINITION
GET https://api.dentally.co/v1/session_appointments?{on,before,after,practitioner_id}
EXAMPLE REQUEST
curl https://api.dentally.co/v1/session_appointments?on=2015-01-02
EXAMPLE RESPONSE:
{
"session_appointments": [
{
"id": "9cfefa03-8870-4ec1-9dc3-5abec498b785",
"colour": "#0C99EF",
"description": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
"display_type": "background",
"finish_time": "2013-11-05T09:40:00.000+00:00",
"practitioner_id": 1,
"room_id": "04b2db45-455a-42f7-b9ce-99fa6b0c741b",
"start_time": "2013-11-05T09:00:00.000+00:00"
},
{...},
{...}
],
"meta": {
"total": 3,
"page": 1
}
}
Returns a list of existing session appointments
Parameters
Parameters are not mutually exclusive and can be combined to build up complex queries
| on: datetime, optional |
On a date |
| before: datetime, optional |
Before a date |
| after: datetime, optional |
After a date |
| practitioner_id: string, optional |
With a practitioner |
| room_id: string, optional |
With a room |
Returns
Returns a list of matching session_appointments. The response includes a metadata object which contains the page number that was returned as well as the total number of matching session_appointments. By default the session_appointments are returned in the order of their start time.
The session appointment object
Session appointments belong to a practice and can be used for highlighting time in the appointment book, lunch breaks, meetings etc.
EXAMPLE RESPONSE
{
"session_appointment": {
"id": "9cfefa03-8870-4ec1-9dc3-5abec498b785",
"colour": "#0C99EF",
"description": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
"display_type": "background",
"finish_time": "2013-11-05T09:40:00.000+00:00",
"practitioner_id": 1,
"room_id": "04b2db45-455a-42f7-b9ce-99fa6b0c741b",
"start_time": "2013-11-05T09:00:00.000+00:00"
}
}
ATTRIBUTES
| id: uuid |
The ID of the session appointment |
| colour: string |
The colour these appointments appear as in the practice appointment book |
| description: string |
Text describing the appointment |
| display_type: string |
Style of the how the session appointment appears in the appointment book. Currently one of (background, border, background_border) |
| finish_time: datetime |
The date and time the appointment was set to finish |
| practitioner_id: integer |
The ID of the practitioner assigned to the appointment |
| room_id: string, optional |
The ID of the room the appointment is allocated |
| start_time: datetime |
The date and time the appointment was set to start |
Sundries
Sundries
A sundry belongs to an invoice item.
GET https://api.dentally.co/v1/sundries/{SUNDRY_ID}
EXAMPLE REQUEST
curl "https://api.dentally.co/v1/sundries/1"
EXAMPLE RESPONSE:
{
"sundry": [
{
"id": "b2cc52a7-f488-419b-b9ac-f3c2f989c78e",
"name": "Dentally Sundry",
"nickname": "Dentally Sundry",
"price": 0.0,
"site_id": 1
}
],
"meta": {
"total": 50,
"page": 1
}
}
Returns a list of appointment reasons
Parameters
| id: uuid |
The ID of the sundry |
| name: string |
The name given to the sundry |
| nickname: string |
The nickname given to the sundry |
| price: integer |
The price of the sundry |
| site_id: integer |
The site ID of the site that the sundry belongs to |
List all Sundries
DEFINITION
GET https://api.dentally.co/v1/sundries?{SUNDRY_ID}
EXAMPLE REQUEST
curl https://api.dentally.co/v1/sundries?sundry_id=10
EXAMPLE RESPONSE:
{
"sundry": [
{
"id": "b2cc52a7-f488-419b-b9ac-f3c2f989c78e",
"name": "Dentally Sundry",
"nickname": "Dentally Sundry",
"price": 0.0,
"site_id": 1
}
],
"meta": {
"total": 50,
"page": 1
}
}
Returns a list of existing sundries
Parameters
| sundry_id: integer, optional |
The ID of a sundry |
Treatment Categories
The treatment category object
The treatment category object provides a link between treatment_category_id and the category name.
EXAMPLE RESPONSE
{
"id": 3,
"name": "Primary"
}
Get a single treatment category
Retrieves the details of an existing treatment category
DEFINITION
GET https://api.dentally.co/v1/treatment_categories/{TREATMENT_CATEGORY_ID}
EXAMPLE REQUEST
curl https://api.dentally.co/v1/treatment_categories/1
Parameters
| id: | required |
EXAMPLE RESPONSE
{
"treatment_category": {
"id": 3,
"name": "Primary"
}
}
Returns
A treatment category object
List all treatment categories
Returns a list of treatment categories
DEFINITION
GET https://api.dentally.co/v1/treatment_categories
EXAMPLE REQUEST
curl https://api.dentally.co/v1/treatment_categories
Parameters
None
EXAMPLE RESPONSE:
{
"treatment_categories": [
{
"id": 1,
"name": "Primary"
},
{
"id": 2,
"name": "Secondary"
}
],
"meta": {
"total": 2,
"current_page": 1
}
}
Returns
Returns a list of treatment categories
Treatments
The treatment object
EXAMPLE RESPONSE
{
"treatment": {
"id": 210,
"active": true,
"code": "URGXL",
"created_at": "2015-06-01T15:48:39.412+01:00",
"description": "",
"nhs_treatment_cat": "9307",
"nomenclature": "Extraction (urgent)",
"notes": "<div>Lignocaine 2% with 1:80,000 Adrenaline<br>Batch number:<br>Expiry:<br></div><div><br></div>Extracted using elevator and forceps<br>Haemostatis achieved<br>Post Operative Instruction given written / verbal",
"owner": "practice",
"patient_description": "",
"patient_nomenclature": "Extraction",
"region": "tooth",
"treatment_category_id": 1,
"uda_band": 4,
"updated_at": "2015-06-01T15:53:37.046+01:00"
}
}
ATTRIBUTES
| id: string |
The ID of the treatment |
| active: boolean |
Whether this treatment is active or not |
| code: string |
The code used for this treatment |
| created_at: string |
The date and time the treatment was created |
| description: string |
A short summary of treatment |
| nhs_treatment_cat: string |
The NHS category id for this treatment |
| nomenclature: string |
Term used to name this treatment |
| notes: string |
Any notes for this treatment |
| owner: string |
Who owns this treatment - practice or system |
| patient_description: string |
Description displayed to patient |
| patient_nomenclature: string |
Term displayed to patient |
| region: string |
Where the treatment occurs, patient, tooth |
| treatment_category_id: string |
The treatments category |
| uda_band: string |
The NHS charging band |
| updated_at: string |
The date and time the treatment was updated |
Get a single treatment
Retrieves the details of an existing treatment
DEFINITION
GET https://api.dentally.co/v1/treatments/{TREATMENT_ID}
EXAMPLE REQUEST
curl https://api.dentally.co/v1/treatments/210
Parameters
| id: | required |
EXAMPLE RESPONSE
{
"treatment": {
"id": 210,
"active": true,
"code": "URGXL",
"created_at": "2015-06-01T15:48:39.412+01:00",
"description": "",
"nhs_treatment_cat": "9307",
"nomenclature": "Extraction (urgent)",
"notes": "<div>Lignocaine 2% with 1:80,000 Adrenaline<br>Batch number:<br>Expiry:<br></div><div><br></div>Extracted using elevator and forceps<br>Haemostatis achieved<br>Post Operative Instruction given written / verbal",
"owner": "practice",
"patient_description": "",
"patient_nomenclature": "Extraction",
"region": "tooth",
"treatment_category_id": 1,
"uda_band": 4,
"updated_at": "2015-06-01T15:53:37.046+01:00"
}
}
Returns
A treatment object
List all treatments
Returns a list of all active treatments
DEFINITION
GET https://api.dentally.co/v1/treatments
EXAMPLE REQUEST
curl https://api.dentally.co/v1/treatments
EXAMPLE RESPONSE:
{
"treatments": [
{
"id": 210,
"active": true,
"code": "URGXL",
"created_at": "2015-06-01T15:48:39.412+01:00",
"description": "",
"nhs_treatment_cat": "9307",
"nomenclature": "Extraction (urgent)",
"notes": "<div>Lignocaine 2% with 1:80,000 Adrenaline<br>Batch number:<br>Expiry:<br></div><div><br></div>Extracted using elevator and forceps<br>Haemostatis achieved<br>Post Operative Instruction given written / verbal",
"owner": "practice",
"patient_description": "",
"patient_nomenclature": "Extraction",
"region": "tooth",
"treatment_category_id": 1,
"uda_band": 4,
"updated_at": "2015-06-01T15:53:37.046+01:00"
},
{...},
{...}
],
"meta": {
"total": 3,
"page": 1
}
}
Parameters
| active string, optional |
Set to true for active treatments, false for inactive treatments and all for all treatments |
| query: string, optional |
A search query to filter on code. |
| treatment_category_id: string, optional |
Returns all treatments for a given treatment category id |
Sorting
The following columns can be used to sort.
| code | ascending or descending |
| created_at | ascending or descending |
| updated_at | ascending or descending |
Note: Using the parameter query disables the sorting, so the sort_by and sort_direction parameters are not compatible with query.
Returns
Returns a list of all treatments in your practice. The list is by default ordered by code.
Treatment Appointments
The treatment appointment object
EXAMPLE RESPONSE
{
"treatment_appointment": {
"id": 98367,
"bookable": true,
"completed": false,
"completed_at": null,
"notes": null,
"position": 0,
"created_at": "2019-07-16T15:29:53.432+01:00",
"updated_at": "2019-07-16T15:29:53.432+01:00",
"appointment_id": null,
"patient_id": 19980,
"treatment_plan_id": 52308
}
}
}
ATTRIBUTES
| id: string |
The ID of the treatment |
| bookable: boolean |
Indicates if the appointment is bookable |
| notes: string |
Notes relating to this treatment appointment in html |
| position: number |
a relative position to other service appointments |
| created_at: string |
The date the TPI was created |
| updated_at: string |
The date the TPI was updated |
| appointment_id: number |
The Appointment resource ID |
| patient_id: number |
The Patient resource ID |
| treatment_plan_id: number |
The Treatment Plan resource ID |
Get a single treatment appointment
Retrieves the details of an existing treatment appointment
DEFINITION
GET https://api.dentally.co/v1/treatment_appointments/{TREATMENT_APPOINTMENT_ID}
EXAMPLE REQUEST
curl https://api.dentally.co/v1/treatment_appointments/98367
Parameters
| id: | required |
EXAMPLE RESPONSE
{
"treatment_appointment": {
"id": 98367,
"bookable": true,
"completed": false,
"completed_at": null,
"notes": null,
"position": 0,
"created_at": "2019-07-16T15:29:53.432+01:00",
"updated_at": "2019-07-16T15:29:53.432+01:00",
"appointment_id": null,
"patient_id": 19980,
"treatment_plan_id": 52308
}
}
}
Returns
A treatment appointment object
List all treatment appointments
Returns a list of existing treatment appointments
DEFINITION
GET https://api.dentally.co/v1/treatment_appointments
EXAMPLE REQUEST
curl https://api.dentally.co/v1/treatment_appointments
EXAMPLE RESPONSE:
{
"treatment_appointments": [
{
"id": 98367,
"bookable": true,
"completed": false,
"completed_at": null,
"notes": null,
"position": 0,
"created_at": "2019-07-16T15:29:53.432+01:00",
"updated_at": "2019-07-16T15:29:53.432+01:00",
"appointment_id": null,
"patient_id": 19980,
"treatment_plan_id": 52308
},
{...}
{...}
],
"meta": {
"total": 3,
"page": 1
}
}
Parameters
| patient_id: string, optional |
Returns treatment appointments for given patient id. |
| treatment_plan_id: string, optional |
Returns treatment appointments for given treatment plan id. |
| updated_after: datetime, optional |
Returns treatment appointment items that have been updated since this time. |
| updated_before: datetime, optional |
Returns treatment appointments items that were updated before this time. |
| created_after: datetime, optional |
Returns treatment appointment items that have been created since this time. |
| created_before: datetime, optional |
Returns treatment appointments items that were created before this time. |
Sorting
The following columns can be used to sort.
| created_at | ascending or descending |
| updated_at | ascending or descending |
Returns
Returns a list of all treatment appointments in your practice. The list is by default ordered by created_at.
Treatment Plans
The treatment plan object
EXAMPLE RESPONSE
{
"treatment_plan": {
"id": 77,
"completed": true,
"completed_at": "2015-02-17T11:28:37.039+00:00",
"created_at": "2015-01-18T14:08:16.523+00:00",
"end_date": null,
"last_completed_at": null,
"nhs_completed_uda_value": "0.0",
"nhs_uda_value": "3.0",
"nickname": null,
"patient_id": 7979,
"practitioner_id": 16,
"private_treatment_value": "0.0",
"start_date": "2015-01-18",
"updated_at": "2017-01-03T20:38:44.896+00:00"
}
}
ATTRIBUTES
| id: string |
The ID of the treatment plan |
| completed boolean |
Indicates the treatment plan is completed |
| completed_at string |
The date/time the treatment plan was completed |
| created_at: string |
The date and time the treatment plan was created |
| end_date string |
The date the treatment plan ended |
| last_completed_at string |
Indicates the previous completed at date |
| nhs_completed_uda_value string |
The NHS UDA value for completed work |
| nhs_uda_value string |
The NHS UDA Value |
| nickname string |
The plans nickname if set |
| patient_id string |
The patients id |
| practitioner_id string |
The practitioner id |
| private_treatment_value string |
The value if a private treatment |
| start_date string |
The date the plan began |
| updated_at: string |
The date and time the treatment plan was updated |
Get a single treatment plan
Retrieves the details of an existing treatment plan
DEFINITION
GET https://api.dentally.co/v1/treatment_plans/{TREATMENT_PLAN_ID}
EXAMPLE REQUEST
curl https://api.dentally.co/v1/treatment_plans/77
Parameters
| id: | required |
EXAMPLE RESPONSE
{
"treatment_plan": {
"id": 77,
"completed": true,
"completed_at": "2015-02-17T11:28:37.039+00:00",
"created_at": "2015-01-18T14:08:16.523+00:00",
"end_date": null,
"last_completed_at": null,
"nhs_completed_uda_value": "0.0",
"nhs_uda_value": "3.0",
"nickname": null,
"patient_id": 7979,
"practitioner_id": 16,
"private_treatment_value": "0.0",
"start_date": "2015-01-18",
"updated_at": "2017-01-03T20:38:44.896+00:00"
}
}
Returns
A treatment plan object
List all treatment plans
Returns a list of all treatment plans
DEFINITION
GET https://api.dentally.co/v1/treatment_plans?{completed, created_after, created_before, ids, patient_id, practitioner_id, start_date, updated_since}
EXAMPLE REQUEST
curl https://api.dentally.co/v1/treatment_plans?ids[]=77&ids[]=78
EXAMPLE RESPONSE:
{
"treatment_plans": [
{
"id": 77,
"completed": true,
"completed_at": "2015-02-17T11:28:37.039+00:00",
"created_at": "2015-01-18T14:08:16.523+00:00",
"end_date": null,
"last_completed_at": null,
"nhs_completed_uda_value": "0.0",
"nhs_uda_value": "3.0",
"nickname": null,
"patient_id": 7979,
"practitioner_id": 16,
"private_treatment_value": "0.0",
"start_date": "2015-01-18",
"updated_at": "2017-01-03T20:38:44.896+00:00"
},
{...},
{...}
],
"meta": {
"total": 3,
"page": 1
}
}
Parameters
| completed boolean, optional |
Returns treatment plans that are completed or not. |
| created_after datetime, optional |
Returns treatment plans that were created after this time |
| created_before datetime, optional |
Returns treatment plans that are created before this time |
| ids: array, optional |
An array of ids to return. |
| patient_id: string, optional |
Returns treatment plans for given patient id. |
| practitioner_id: integer, optional |
Returns treatment plans for given practitioner id. |
| start_date date, optional |
Returns treatment plans that start on the given date in YYYY-MM-DD format. |
| updated_since datetime, optional |
Returns treatment plans that were updated after this time |
Sorting
The following columns can be used to sort.
| created_at | ascending or descending |
| completed_at | ascending or descending |
| updated_at | ascending or descending |
Returns
Returns a list of all treatment plans in your practice. The list is by default ordered by created_at.
Treatment Plan Items
The treatment plan item object
EXAMPLE RESPONSE
{
"treatment_plan_item": {
"id": 1630192,
"appear_on_invoice": true,
"base_chart": false,
"charged": false,
"completed": false,
"completed_at": null,
"custom_fields": [
{
"value": true,
"field_id": "2c19fdf0-987c-4e5a-aa71-06ad8a58ee22",
"position": 0
},
{
"value": false,
"field_id": "db96ab4b-5c3a-4f00-9534-9d8ad9bcf13b",
"position": 1
},
{
"value": null,
"field_id": "38b96e14-e31d-477b-a1c0-1538ff4cf360",
"position": 2
}],
"duration": 15,
"nhs_treatment_cat": "9317",
"nomenclature": "Examination",
"notes": "<p><strong>Soft tissues checked</strong><br>Extra-Oral: NAD<br>Intra-Oral: NAD\n</p>",
"patient_nomenclature": "Examination",
"position": null,
"price": "0.0",
"region": "patient",
"surfaces": null,
"teeth": null,
"uda_band": 1,
"created_at": "2019-06-07T09:02:00.968+01:00",
"updated_at": "2019-06-07T09:02:00.968+01:00",
"invoice_id": null,
"patient_id": 45,
"payment_plan_id": 1,
"practitioner_id": 1,
"referrer_id": 1,
"treatment_appointment_id": 98361,
"treatment_id": 1,
"treatment_plan_id": 52302
}
}
}
ATTRIBUTES
| id: string |
The ID of the treatment |
| appear_on_invoice: boolean |
Displayed on the invoices |
| base_chart: boolean |
Displayed on the base chart |
| charged: boolean |
Indicates if charged |
| completed: boolean |
Indicates when the TPI is completed |
| completed_at: string |
When the TPI was completed |
| custom_fields: array |
Custom fields for this TPI, where the field_id refers to an object in the Custom Fields resource and the value is the value of the custom field for this TPI. |
| duration: number |
The duration in minutes |
| nhs_treatment_cat: string |
The NHS treatment category of this TPI |
| nomenclature: string |
Classification of this TPI |
| notes: string |
Notes relating to this TPI in html |
| patient_nomenclature: string |
Patient friendly classification of this TPI |
| position: number |
if set the sequence within a TreatmentPlan |
| price: string |
The cost/price of this TPI |
| region: string |
Where the TPI is applied, patient, site,tooth or a surface. |
| surfaces: array |
Indicates which surfaces treated |
| teeth: array |
Indicates which teeth treated |
| uda_band: number |
The NHS UDA Band for this treatment |
| created_at: string |
The date the TPI was created |
| updated_at: string |
The date the TPI was updated |
| invoice_id: string |
The Invoice resource ID |
| patient_id: string |
The Patient resource ID |
| payment_plan_id: number |
The Payment Plan resource ID |
| practitioner_id: number |
The Practitioner resource ID |
| referrer_id: number |
The Referrer(Practitioner) resource ID |
| treatment_appointment_id: number |
The TreatmentAppointment resource ID |
| treatment_id: number |
The Treatment resource ID |
| treatment_plan_id: number |
The Treatment Plan resource ID |
Surfaces
Surfaces are returned as numbers within an array. Surfaces are numbered 1-5 for incisors, canines, premolars and deciduous teeth and 1-8 for molar teeth. Surface numbering starts from the top left hand corner of the tooth and is counted clockwise around the edge of the tooth and into the center.
"surfaces": [
3,
8
],
Teeth
Teeth are returned as strings within an array. All teeth are stored using Palmer notation.
"teeth": [
"LR7"
],
Get a single treatment plan item
Retrieves the details of an existing treatment plan item
DEFINITION
GET https://api.dentally.co/v1/treatment_plan_items/{TREATMENT_PLAN_ITEM_ID}
EXAMPLE REQUEST
curl https://api.dentally.co/v1/treatment_plan_items/1630192
Parameters
| id: | required |
EXAMPLE RESPONSE
{
"treatment_plan_item": {
"id": 1630192,
"appear_on_invoice": true,
"base_chart": false,
"charged": false,
"completed": false,
"completed_at": null,
"custom_fields": [
{
"value": true,
"field_id": "2c19fdf0-987c-4e5a-aa71-06ad8a58ee22",
"position": 0
},
{
"value": false,
"field_id": "db96ab4b-5c3a-4f00-9534-9d8ad9bcf13b",
"position": 1
},
{
"value": null,
"field_id": "38b96e14-e31d-477b-a1c0-1538ff4cf360",
"position": 2
}],
"duration": 15,
"nhs_treatment_cat": "9317",
"nomenclature": "Examination",
"notes": "<p><strong>Soft tissues checked</strong><br>Extra-Oral: NAD<br>Intra-Oral: NAD\n</p>",
"patient_nomenclature": "Examination",
"position": null,
"price": "0.0",
"region": "patient",
"surfaces": null,
"teeth": null,
"uda_band": 1,
"created_at": "2019-06-07T09:02:00.968+01:00",
"updated_at": "2019-06-07T09:02:00.968+01:00",
"invoice_id": null,
"patient_id": 45,
"payment_plan_id": 1,
"practitioner_id": 1,
"referrer_id": 1,
"treatment_appointment_id": 98361,
"treatment_id": 1,
"treatment_plan_id": 52302
}
}
}
Returns
A treatment plan item object
List all treatment plan items
Returns a list of existing treatment plan items
DEFINITION
GET https://api.dentally.co/v1/treatment_plan_items{completed_on, patient_id, practitioner_id, treatment_plan_id, treatment_appointment_id, updated_after, updated_before}
EXAMPLE REQUEST
curl https://api.dentally.co/v1/treatment_plan_items?patient_id=45
Parameters
| completed_on: date, optional |
Returns treatment plan items that were completed on this day. |
| patient_id: string, optional |
Returns treatment plan items for given patient id. |
| practitioner_id: integer, optional |
Returns treatment plan items for given practitioner id. |
| treatment_plan_id: string, optional |
Returns treatment plan items for given treatment plan id. |
| treatment_appointment_id: string, optional |
Returns treatment plan items for given treatment appointment id. |
| updated_after: datetime, optional |
Returns treatment plan items that have been updated since this time. |
| updated_before: datetime, optional |
Returns treatment plan items that were updated before this time. |
EXAMPLE RESPONSE:
{
"treatment_plan_items": [
{
"id": 1630192,
"appear_on_invoice": true,
"base_chart": false,
"charged": false,
"completed": false,
"completed_at": null,
"custom_fields": [
{
"value": true,
"field_id": "2c19fdf0-987c-4e5a-aa71-06ad8a58ee22",
"position": 0
},
{
"value": false,
"field_id": "db96ab4b-5c3a-4f00-9534-9d8ad9bcf13b",
"position": 1
},
{
"value": null,
"field_id": "38b96e14-e31d-477b-a1c0-1538ff4cf360",
"position": 2
}],
"duration": 15,
"nhs_treatment_cat": "9317",
"nomenclature": "Examination",
"notes": "<p><strong>Soft tissues checked</strong><br>Extra-Oral: NAD<br>Intra-Oral: NAD\n</p>",
"patient_nomenclature": "Examination",
"position": null,
"price": "0.0",
"region": "patient",
"surfaces": null,
"teeth": null,
"uda_band": 1,
"created_at": "2019-06-07T09:02:00.968+01:00",
"updated_at": "2019-06-07T09:02:00.968+01:00",
"invoice_id": null,
"patient_id": 45,
"payment_plan_id": 1,
"practitioner_id": 1,
"referrer_id": 1,
"treatment_appointment_id": 98361,
"treatment_id": 1,
"treatment_plan_id": 52302
},
{...}
{...}
],
"meta": {
"total": 3,
"page": 1
}
}
Users
The user object
A user belongs to a practice
EXAMPLE RESPONSE
{
"user": {
"id": 1,
"allowed_sites": ["e1d854af-15db-4482-8e29-39e74a6c7f75"],
"created_at": "2013-11-04T02:47:17.380+00:00",
"email": "ross@hepburn.com",
"first_name": "Ross",
"image_url": "https://www.gravatar.com/avatar/672a9f4da85d4b2026059973b84dd827.jpg?&r=pg&d=identicon&s=100",
"last_login": "2016-01-26T10:24:07.961+00:00",
"last_name": "Hepburn",
"middle_name": null,
"mobile_phone": "07123456789",
"permission_level": 4,
"practice_id": "c687bd0b-b35c-44ac-81d5-aebc3b9310a6",
"role": "Dentist",
"site_id": "e1d854af-15db-4482-8e29-39e74a6c7f75",
"title": "Mx",
"updated_at": "2015-01-02T12:02:52.402+00:00"
}
}
ATTRIBUTES
| id: integer |
The ID of the user |
| allowed_sites Array |
An array of sites where the user is allowed |
| created_at: datetime |
The date and time the user was created |
| email: string |
The user’s email address |
| first_name: string |
The user’s first name |
| image_url: string |
URL of the user’s profile image |
| last_login: datetime |
The date and time the user last logged in |
| last_name: string |
The user’s last name |
| middle_name: string |
The user’s middle name |
| mobile_phone: string |
The user’s mobile phone number |
| permission_level: integer |
The user’s permission level. Can range between 0 and 4. Further details on permission levels can be found here |
| practice_id: string |
The ID of the practice that the user belongs to |
| role: string |
The user’s role. Must be one of Administrator, Dentist, Hygienist, Nurse, Practice Manager, Receptionist, Technician or Therapist |
| site_id string |
The user’s site ID. |
| title: string |
The user’s title. |
| updated_at: datetime |
The date and time the user was last updated. |
Get the authenticated user
Retrieves the details of the currently authenticated user
DEFINITION
GET https://api.dentally.co/v1/user
EXAMPLE REQUEST
curl https://api.dentally.co/v1/user
Parameters
None
EXAMPLE RESPONSE
{
"user": {
"id": 1,
"allowed_sites": ["e1d854af-15db-4482-8e29-39e74a6c7f75"],
"created_at": "2015-01-01T12:02:52.402+00:00",
"email": "user@dentalpractice.com",
"first_name": "Gregory",
"image_url": "https://www.gravatar.com/avatar/0242720e04226d4d190f9ffc15a2644b.jpg?&r=pg&d=identicon&s=100",
"last_login": "2015-01-02T18:16:50.235+00:00",
"last_name": "Hays",
"middle_name": null,
"mobile_phone": null,
"permission_level": 4,
"practice_id": "c687bd0b-b35c-44ac-81d5-aebc3b9310a6",
"role": "Dentist",
"site_id": "e1d854af-15db-4482-8e29-39e74a6c7f75",
"title": "Mx",
"updated_at": "2015-01-02T12:02:52.402+00:00"
}
}
Returns
A user object
Get a single user
Retrieves the details of an existing user
DEFINITION
GET https://api.dentally.co/v1/users/{USER_ID}
EXAMPLE REQUEST
curl https://api.dentally.co/v1/users/1
Parameters
| id: | required |
EXAMPLE RESPONSE
{
"user": {
"id": 1,
"allowed_sites": ["e1d854af-15db-4482-8e29-39e74a6c7f75"],
"created_at": "2015-01-01T12:02:52.402+00:00",
"email": "user@dentalpractice.com",
"first_name": "Gregory",
"image_url": "https://www.gravatar.com/avatar/0242720e04226d4d190f9ffc15a2644b.jpg?&r=pg&d=identicon&s=100",
"last_login": "2015-01-02T18:16:50.235+00:00",
"last_name": "Hays",
"middle_name": null,
"mobile_phone": null,
"permission_level": 4,
"practice_id": "c687bd0b-b35c-44ac-81d5-aebc3b9310a6",
"role": "Dentist",
"site_id": "e1d854af-15db-4482-8e29-39e74a6c7f75",
"title": "Mx",
"updated_at": "2015-01-02T12:02:52.402+00:00"
}
}
Returns
A user object
Edit a user
Updates an existing user
DEFINITION
PUT/PATCH https://api.dentally.co/v1/users/{PATIENT_ID}
EXAMPLE REQUEST
curl --include \
--request PUT \
--header "Content-Type: application/json" \
--data-binary '{
"user": {
"first_name": "Greg"
}
}' \
https://api.dentally.co/v1/users/1
Parameters
Parameters must be wrapped by a user object
| first_name: string, optional |
The user’s first name |
| middle_name: string, optional |
The user’s middle name |
| last_name: string, optional |
The user’s last name |
| mobile_phone: string, optional |
The user’s mobile phone number |
| role: string, optional |
The user’s role. Must be one of Administrator, Dentist, Hygienist, Nurse, Practice Manager, Receptionist, Technician and Therapist |
| permission_level: integer, optional |
The user’s permission level. Can range between 0 and 4. Further details on permission levels can be found here |
EXAMPLE RESPONSE
{
"user": {
"id": 1,
"allowed_sites": ["e1d854af-15db-4482-8e29-39e74a6c7f75"],
"created_at": "2015-01-01T12:02:52.402+00:00",
"email": "user@dentalpractice.com",
"first_name": "Greg",
"image_url": "https://www.gravatar.com/avatar/0242720e04226d4d190f9ffc15a2644b.jpg?&r=pg&d=identicon&s=100",
"last_login": "2015-01-02T18:16:50.235+00:00",
"last_name": "Hays",
"middle_name": null,
"mobile_phone": null,
"permission_level": 4,
"practice_id": "c687bd0b-b35c-44ac-81d5-aebc3b9310a6",
"role": "Dentist",
"site_id": "e1d854af-15db-4482-8e29-39e74a6c7f75",
"title": "Mx",
"updated_at": "2015-01-02T12:02:52.402+00:00"
}
}
Returns
The updated user object
List all users
Returns a list of all users
DEFINITION
GET https://api.dentally.co/v1/users
EXAMPLE REQUEST
curl https://api.dentally.co/v1/users
Parameters
| created_after: datetime |
The date and time after the user was created |
| updated_after: datetime |
The date and time after the user was last updated |
EXAMPLE RESPONSE:
{
"users": [
{
"id": 1,
"allowed_sites": ["e1d854af-15db-4482-8e29-39e74a6c7f75"],
"created_at": "2015-01-01T12:02:52.402+00:00",
"email": "user@dentalpractice.com",
"first_name": "Greg",
"image_url": "https://www.gravatar.com/avatar/0242720e04226d4d190f9ffc15a2644b.jpg?&r=pg&d=identicon&s=100",
"last_login": "2015-01-02T18:16:50.235+00:00",
"last_name": "Hays",
"middle_name": null,
"mobile_phone": null,
"permission_level": 4,
"practice_id": "c687bd0b-b35c-44ac-81d5-aebc3b9310a6",
"role": "Dentist",
"site_id": "e1d854af-15db-4482-8e29-39e74a6c7f75",
"title": "Mx",
"updated_at": "2015-01-02T12:02:52.402+00:00"
},
{...},
{...}
],
"meta": {
"total": 3,
"page": 1
}
}
Returns
Returns a list of all users in your practice. The list is ordered by ID
Practice
The practice object
EXAMPLE RESPONSE
{
"practice": {
"id": "c687bd0b-b35c-44ac-81d5-aebc3b9310a6",
"address_line_1": "126 The Crescent",
"address_line_2": "",
"custom_patient_field_label_1": "Insurance Number",
"custom_patient_field_label_2": null,
"email_address": "hello@dentalpractice.com",
"logo_url": "https://dentally.co/api-practice-logo.png",
"medical_history_expiry_days": 365,
"name": "Dentally Dental",
"nhs": true,
"opening_hours": {
"Monday": { "open": "09:00", "close": "17:00" },
"Tuesday": { "open": "09:00", "close": "17:00" },
"Wednesday": { "open": "09:00", "close": "17:00" },
"Thursday": { "open": "09:00", "close": "17:00" },
"Friday": { "open": "09:00", "close": "17:00" }
},
"patient_email_address": "dentalpractice@dentallymail.co.uk",
"phone_number": "020134848228",
"postcode": "W1A 1AA",
"slug": "dentalpractice",
"time_zone": "London",
"town": "Pontyberem",
"website": "dentalpractice.com"
}
}
ATTRIBUTES
| id: string |
The ID of the practice |
| address_line_1: string |
The first line of the practice’s address |
| address_line_2: string |
The second line of the practice’s address |
| custom_patient_field_label_1: string |
The label for a data field a practice can use to store extra info about patients. Field is listed on the patient as custom_field_1 |
| custom_patient_field_label_2: string |
The label for a data field a practice can use to store extra info about patients. Field is listed on the patient as custom_field_2 |
| email_address: string |
The email address for the practice |
| logo_url: string |
The URL of the practice’s logo |
| medical_history_expiry_days: integer |
Number of days after last medical history has been completed by a patient before a warning is shown on the patients record. |
| name: string |
The name of the practice |
| nhs: boolean |
If the practice is NHS. Default false |
| opening_hours: hash |
A hash containing the days of the week that the primary site* is open and the corresponding opening and closing time for each day. |
| patient_email_address: string |
The email address used to send emails to patients |
| phone_number: string |
The phone number for the practice |
| postcode: string |
The postcode for the practice |
| slug: string |
The unique name of the practice. Used as part of the patient email address |
| time_zone: string |
The practice timezone |
| town: string |
The town the practice resides |
| website: string |
The practices website address |
| iso_country_code: string |
The practice’s ISO alpha-2 country code |
*Primary site is the deemed to be the first (oldest), active site for a practice. Please see the site api for individual sites.
Get the practice
Retrieves the details of the currently authenticated user’s practice
DEFINITION
GET https://api.dentally.co/v1/practice
EXAMPLE REQUEST
curl https://api.dentally.co/v1/practice
Parameters
None
EXAMPLE RESPONSE
{
"practice": {
"id": "c687bd0b-b35c-44ac-81d5-aebc3b9310a6",
"address_line_1": "126 The Crescent",
"address_line_2": "",
"custom_patient_field_label_1": "Insurance Number",
"custom_patient_field_label_2": null,
"email_address": "hello@dentalpractice.com",
"iso_country_code": "GB",
"logo_url": "https://dentally.co/api-practice-logo.png",
"medical_history_expiry_days": 365,
"name": "Dentally Dental",
"nhs": true,
"opening_hours": {
"Monday": { "open": "09:00", "close": "17:00" },
"Tuesday": { "open": "09:00", "close": "17:00" },
"Wednesday": { "open": "09:00", "close": "17:00" },
"Thursday": { "open": "09:00", "close": "17:00" },
"Friday": { "open": "09:00", "close": "17:00" }
},
"patient_email_address": "dentalpractice@dentallymail.co.uk",
"phone_number": "020134848228",
"postcode": "W1A 1AA",
"slug": "dentalpractice",
"time_zone": "London",
"town": "Pontyberem",
"website": "dentalpractice.com"
}
}
Returns
A practice object
Waiting Lists
The waiting lists object
EXAMPLE RESPONSE
{
 "waiting_list": {
  "id": "751c9241-62de-40aa-8f8f-6a0326032e44",
  "active": true,
  "appointment_reasons": [],
  "created_at": "2019-09-05T16:31:38.910+01:00",
  "default_appointment_duration": 5,
  "default_appointment_reason": "Exam",
  "default_notes": null,
  "default_status": "waiting",
  "default_treatment_duration": 5,
  "default_treatment_reason": "Exam",
  "name": "Grahams List",
  "site_id": "0406e162-58c5-4384-bfe0-e842ab4fa4cf",
  "target_appointment_days": null,
  "target_treatment_days": null,
  "updated_at": "2023-02-21T14:36:37.041+00:00"
 }
}
ATTRIBUTES
| id: string |
The ID of the waiting list |
| active: boolean |
Indicates if waiting list is active or not. Default is true |
| appointment_reasons: string |
A list of reasons for the appointment. Will be one of Exam, Scale & Polish, Exam + Scale & Polish, Continuing Treatment, Emergency, Review or Other |
| default_appointment_duration: integer |
The default duration of the appointment. Default is 10 |
| default_appointment_reason: string |
The default reason of the appointment |
| default_notes: string |
The default notes of the waiting list |
| default_status: string |
The default status of the waiting list |
| default_treatment_duration: integer |
The default treamtent duration. Default is 30 |
| default_treatment_reason: string |
The default treamtent reason |
| name: string |
Name of the waiting list |
| target_appointment_days: integer |
The max number of days a patient is expected to remain on the list before receiving their appointment booking |
| target_treatment_days: integer |
The max number of days a patient is expected to remain on the list before receiving their treatment |
| created_at: datetime |
The date and time the waiting list was created on |
| updated_at: datetime |
The date and time the waiting list was updated on |
| site_id: uuid |
Waiting Lists that belongs to the site id |
Get a waiting list
Retrieves the details of an existing waiting list
DEFINITION
GET https://api.dentally.co/v1/waiting_lists/{WAITING_LIST_ID}
EXAMPLE REQUEST
curl https://api.dentally.co/v1/waiting_lists/751c9241-62de-40aa-8f8f-6a0326032e44
Parameters
| id: | required |
EXAMPLE RESPONSE
{
"waiting_list": [
{
"id": "751c9241-62de-40aa-8f8f-6a0326032e44",
"active": true,
"appointment_reasons": [],
"created_at": "2019-09-05T16:31:38.910+01:00",
"default_appointment_duration": 5,
"default_appointment_reason": "Exam",
"default_notes": null,
"default_status": "waiting",
"default_treatment_duration": 5,
"default_treatment_reason": "Exam",
"name": "Grahams List",
"site_id": "0406e162-58c5-4384-bfe0-e842ab4fa4cf",
"target_appointment_days": null,
"target_treatment_days": null,
"updated_at": "2023-02-21T14:36:37.041+00:00"
}
]
}
List all waiting lists
Returns a list of waiting lists for all practice locations
DEFINITION
GET https://api.dentally.co/v1/waiting_lists
EXAMPLE REQUEST
curl https://api.dentally.co/v1/waiting_lists
EXAMPLE REQUEST 2
curl https://api.dentally.co/v1/waiting_lists?site_id=0406e162-58c5-4384-bfe0-e842ab4fa4cf
Parameters
| site_id: string, optional |
Returns waiting lists that belong to one practice location (site) |
EXAMPLE RESPONSE:
{
"waiting_lists": [
{
"id": "ddcac4b7-9fd6-40ec-b969-38795066502b",
"active": true,
"appointment_reasons": [
"Exam",
"Scale and Polish"
],
"default_appointment_duration": 5,
"default_appointment_reason": "Exam",
"default_notes": null,
"default_status": "waiting",
"default_treatment_duration": 5,
"default_treatment_reason": "Exam",
"name": "Stuff",
"target_appointment_days": null,
"target_treatment_days": null,
"created_at": "2019-09-05T16:24:41.382+01:00",
"updated_at": "2019-09-05T16:24:41.382+01:00",
"site_id": "9006e11-58c54-4384-bfe0-e842ab4fa4cf"
},
{
"id": "751c9241-62de-40aa-8f8f-6a0326032e44",
"active": true,
"appointment_reasons": [],
"default_appointment_duration": 5,
"default_appointment_reason": "Exam",
"default_notes": null,
"default_status": "waiting",
"default_treatment_duration": 5,
"default_treatment_reason": "Exam",
"name": "Grahams List",
"target_appointment_days": null,
"target_treatment_days": null,
"created_at": "2019-09-05T16:31:38.910+01:00",
"updated_at": "2023-03-23T13:37:52.539+00:00",
"site_id": "0406e162-58c5-4384-bfe0-e842ab4fa4cf"
}
],
"meta": {
"total": 2,
"current_page": 1,
"total_pages": 1
}
}
Returns
Returns a list of waiting lists for all your practice locations.
Returns list of waiting lists that belongs to one practice location when filtering by site_id.
Waiting List Entries
The waiting list entries object
EXAMPLE RESPONSE
{
"waiting_list_entries": [
{
"id": "b758069a-aec5-45e8-8874-50196e72936d",
"appointment_actual_on": null,
"appointment_id": "3429c60d-9d0b-4f5b-add3-95f9edd3dc80",
"appointment_target_on": null,
"appointment_treatment_id": null,
"archived": false,
"created_at": "2023-03-22T15:30:47.571+00:00",
"days_waiting_appointment": 8,
"days_waiting_treatment": 0,
"history": [
{
"changes": {
"status": [
"waiting",
"booked"
],
"appointment_id": [
null,
"3429c60d-9d0b-4f5b-add3-95f9edd3dc80"
],
"practitioner_id": [
null,
"0c6ce55b-4751-4347-b287-23cc87688143"
]
},
"history_at": "2023-03-22T15:31:53.344+00:00",
"history_by": 1,
"changed_count": 3
}
],
"last_edited_by_id": 1,
"listed_on": "2023-03-22",
"notes": "i am waiting",
"patient_id": "276e47ce-3976-4317-b474-a349a5fe92c8",
"patient_name": "laura adam",
"practitioner_id": "0c6ce55b-4751-4347-b287-23cc87688143",
"priority": 2,
"referral_on": null,
"site_id": null,
"specialist_id": null,
"status": "booked",
"treatment_actual_on": null,
"treatment_target_on": null,
"updated_at": "2023-03-22T15:31:53.352+00:00",
"user_id": 1,
"waiting_list_id": "751c9241-62de-40aa-8f8f-6a0326032e44"
},
{
"id": "a707c99c-2300-4626-bc31-07a26ace3175",
"appointment_actual_on": null,
"appointment_id": null,
"appointment_target_on": null,
"appointment_treatment_id": null,
"archived": false,
"created_at": "2023-03-23T11:25:00.900+00:00",
"days_waiting_appointment": 7,
"days_waiting_treatment": 0,
"history": [
{
"changes": {
"referral_on": [
null,
"2023-03-24"
],
"specialist_id": [
null,
"638be207-1272-49cd-8bc0-ed0784e1c8c5"
],
"practitioner_id": [
null,
"0c6ce55b-4751-4347-b287-23cc87688143"
]
},
"history_at": "2023-03-23T11:25:23.101+00:00",
"history_by": 1,
"changed_count": 3
}
],
"last_edited_by_id": 1,
"listed_on": "2023-03-23",
"notes": "this is a note",
"patient_id": "276e47ce-3976-4317-b474-a349a5fe92c8",
"patient_name": "john b",
"practitioner_id": "0c6ce55b-4751-4347-b287-23cc87688143",
"priority": 1,
"referral_on": "2023-03-24",
"site_id": "e1d854af-15db-4482-8e29-39e74a6c7f75",
"specialist_id": "638be207-1272-49cd-8bc0-ed0784e1c8c5",
"status": "waiting",
"treatment_actual_on": null,
"treatment_target_on": null,
"updated_at": "2023-03-23T11:25:23.112+00:00",
"user_id": 1,
"waiting_list_id": "751c9241-62de-40aa-8f8f-6a0326032e44"
}
],
"meta": {
"total": 2,
"current_page": 1,
"total_pages": 1
}
}
ATTRIBUTES
| id: uuid |
The ID of the waiting list entry |
| appointment_actual_on: date |
The date the appointment is on |
| appointment_id: uuid |
ID of the appointment |
| appointment_target_on: date |
The max number of days a patient is expected to remain on the list before receiving their appointment booking |
| appointment_treatment_id: uuid |
The ID of the treatment for appointment |
| archived: boolean |
Whether the waiting list is archived or not. Default is false |
| days_waiting_appointment: integer |
The number of days waiting for appointment. Default is 0 |
| days_waiting_treatment: integer |
The number of days waiting for treatment. Default is 0 |
| history: json |
The history of the waiting list with changes, appointment_id,practitioner_id, history_at, history_by and changed_count |
| last_edited_by_id: integer |
The ID of the user that last edited the waiting list entry |
| listed_on: date |
The date the entry was added to the waiting list |
| notes: string |
Notes created by the user on the waiting list entry |
| patient_id: uuid |
The ID of the patient thats assosicated on the waiting list |
| practitioner_id: uuid |
The ID of the practitioner that is assosicated with the patient on the waiting list |
| site_id: uuid |
The site the waiting list entry belongs to |
| specialist_id: uuid |
The ID of the specialist that is assosicated with the patient on the waiting list |
| user_id: integer |
The user that created the waiting list entry |
| waiting_list_id: uuid |
The id of the waiting list that the entry belongs to |
Get waiting list entries
Retrieves waiting list entries
DEFINITION
GET https://api.dentally.co/v1/waiting_list_entries/{WAITING_LIST_ID}
EXAMPLE REQUEST
curl https://api.dentally.co/v1/waiting_list_entries?waiting_list_id=751c9241-62de-40aa-8f8f-6a0326032e44
Parameters
| waiting_list_id: string |
required |
EXAMPLE RESPONSE
{
"waiting_list_entries": [
{
"id": "b758069a-aec5-45e8-8874-50196e72936d",
"appointment_actual_on": null,
"appointment_id": "3429c60d-9d0b-4f5b-add3-95f9edd3dc80",
"appointment_target_on": null,
"appointment_treatment_id": null,
"archived": false,
"created_at": "2023-03-22T15:30:47.571+00:00",
"days_waiting_appointment": 8,
"days_waiting_treatment": 0,
"history": [
{
"changes": {
"status": [
"waiting",
"booked"
],
"appointment_id": [
null,
"3429c60d-9d0b-4f5b-add3-95f9edd3dc80"
],
"practitioner_id": [
null,
"0c6ce55b-4751-4347-b287-23cc87688143"
]
},
"history_at": "2023-03-22T15:31:53.344+00:00",
"history_by": 1,
"changed_count": 3
}
],
"last_edited_by_id": 1,
"listed_on": "2023-03-22",
"notes": "i am waiting",
"patient_id": "276e47ce-3976-4317-b474-a349a5fe92c8",
"patient_name": "laura adam",
"practitioner_id": "0c6ce55b-4751-4347-b287-23cc87688143",
"priority": 2,
"referral_on": null,
"site_id": null,
"specialist_id": null,
"status": "booked",
"treatment_actual_on": null,
"treatment_target_on": null,
"updated_at": "2023-03-22T15:31:53.352+00:00",
"user_id": 1,
"waiting_list_id": "751c9241-62de-40aa-8f8f-6a0326032e44"
},
{
"id": "a707c99c-2300-4626-bc31-07a26ace3175",
"appointment_actual_on": null,
"appointment_id": null,
"appointment_target_on": null,
"appointment_treatment_id": null,
"archived": false,
"created_at": "2023-03-23T11:25:00.900+00:00",
"days_waiting_appointment": 7,
"days_waiting_treatment": 0,
"history": [
{
"changes": {
"referral_on": [
null,
"2023-03-24"
],
"specialist_id": [
null,
"638be207-1272-49cd-8bc0-ed0784e1c8c5"
],
"practitioner_id": [
null,
"0c6ce55b-4751-4347-b287-23cc87688143"
]
},
"history_at": "2023-03-23T11:25:23.101+00:00",
"history_by": 1,
"changed_count": 3
}
],
"last_edited_by_id": 1,
"listed_on": "2023-03-23",
"notes": "this is a note",
"patient_id": "276e47ce-3976-4317-b474-a349a5fe92c8",
"patient_name": "john b",
"practitioner_id": "0c6ce55b-4751-4347-b287-23cc87688143",
"priority": 1,
"referral_on": "2023-03-24",
"site_id": "e1d854af-15db-4482-8e29-39e74a6c7f75",
"specialist_id": "638be207-1272-49cd-8bc0-ed0784e1c8c5",
"status": "waiting",
"treatment_actual_on": null,
"treatment_target_on": null,
"updated_at": "2023-03-23T11:25:23.112+00:00",
"user_id": 1,
"waiting_list_id": "751c9241-62de-40aa-8f8f-6a0326032e44"
}
],
"meta": {
"total": 2,
"current_page": 1,
"total_pages": 1
}
}
Returns
Returns waiting list entries that belong to a waiting list
Webhooks
Overview
EXAMPLE WEBHOOK
POST https://example.com/webhooks
User-Agent: Dentally-Webhook
Content-Type: application/json
X-Dentally-Signature: 63e0b2c79e8b73993777ce312d6b3ad421742d9a8f2657a3e3c14909c6578ab6
{
"data": {
"id": 2181,
"arrived_at": null,
"cancelled_at": null,
"completed_at": null,
"confirmed_at": null,
"did_not_attend_at": null,
"duration": 30,
"finish_time": "2015-07-08 10:00:00 +0100",
"in_surgery_at": null,
"notes": null,
"patient_name": "Carolina James",
"patient_id": 1,
"patient_image_url": "https://www.gravatar.com/avatar/207bbfd487c85ff34a2e7781f80c1305.jpg?&r=pg&d=identicon&s=190",
"payment_plan_id": 1,
"pending_at": "2015-07-01 12:00:00 +0100",
"practitioner_id": 1,
"reason": "Exam",
"start_time": "2015-07-08 09:30:00 +0100",
"state": "Pending",
"treatment_description": null,
"user_id": 1
},
"event": "appointment.created",
"object": "appointment",
"user": {
"id": 1,
"created_at": "2015-01-01T12:02:52.402+00:00",
"email": "user@dentalpractice.com",
"first_name": "Gregory",
"image_url": "https://www.gravatar.com/avatar/0242720e04226d4d190f9ffc15a2644b.jpg?&r=pg&d=identicon&s=100",
"last_login": "2015-01-02T18:16:50.235+00:00",
"last_name": "Hays",
"middle_name": null,
"mobile_phone": null,
"permission_level": 4,
"role": "Dentist"
}
}
Webhooks notify you of new events in your Dentally account (e.g., when a new appointment has been created).
You can enable webhooks by creating a Webhook from your Dentally Developer Settings or through the API as explained below
When an event occurs in your Dentally account, a webhook will be sent to every enabled webhook endpoint as a POST request, which contains details about the event as well as details about the user that triggered the event, if applicable.
There are a few other things to note when using webhooks:
- Webhooks may arrive out of order.
- Webhooks about unknown events should be ignored, and return 204 No Content. We may add new events to the API without considering this a backwards incompatible change.
- You must use SSL/TLS for webhook URLs. Unsecured webhook URLs are only allowed in the sandbox environment.
- Larger practices may generate several thousand webhooks per day. To reduce the number of webhooks you receive simply select the events you require when creating the webhook.
Status codes
Your webhook handler should return a response with a 2xx status code, e.g. 200 OK, or 204 No Content. Returning any other error code will cause Dentally to retry the webhook.
Errors & Retries
In the event we fail to deliver the webhook, or you respond with a non 2xx status code, we will attempt to resend the webhook up to 10 times at increasing time intervals. If we fail to deliver more than 50 webhooks to your endpoint then the webhook will automatically be disabled. It can be re-enabled from your Developer Settings.
Signing Webhooks
We sign the body of the POST request with an HMAC SHA256 hex digest, using the secret of the webhook endpoint for which this webhook is being sent. The signature is sent in the header of the request:
EXAMPLE SIGNATURE
X-Dentally-Signature: 63e0b2c79e8b73993777ce312d6b3ad421742d9a8f2657a3e3c14909c6578ab6
You must check that the webhook has a valid signature before processing it. Here’s how you could do that in Ruby.
The webhook object
EXAMPLE RESPONSE
{
"webhook": {
"id": 1,
"active": true,
"events": [
"appointment.created",
"appointment.updated",
"appointment.deleted"
],
"failed_deliveries": 0,
"last_delivered_at": "2017-12-13T12:34:56.000+00:00",
"name": "My example webhook",
"successful_deliveries": 343,
"url": "https://example.com/webhooks"
}
}
ATTRIBUTES
| id: integer |
The ID of the webhook |
| active: boolean |
If the webhook is active. Only active webhooks will be delivered |
| events: array |
The events the webhook responds to. All events are listed below |
| failed_deliveries: integer |
The number of times a non 2XX response has been returned |
| last_delivered_at: datetime |
The timestamp of when we last sucessfully delivered the webhook |
| name: string |
The name of the webhook so users can identify it within Dentally |
| successful_deliveries: integer |
The total number of times a 2XX response has been returned |
| url: string |
The URL of where the webhook payload will be delivered |
Webhook events
| Appointments | appointment.created |
| appointment.updated | |
| appointment.deleted | |
| Patients | patient.created |
| patient.updated | |
| patient.deleted | |
| Payments | payment.created |
| payment.updated | |
| payment.deleted |
Create a webhook
Creates a new webhook
DEFINITION
POST https://api.dentally.co/v1/webhooks
EXAMPLE REQUEST
curl --include \
--request POST \
--header "Content-Type: application/json" \
--data-binary '{
"webhook": {
"active": true,
"events": [
"patient.created",
"patient.updated",
"patient.deleted"
],
"name": "My example webhook",
"secret": "pLjUpNQu8a4YjeCrf2KseA",
"url": "https://example.com/webhooks"
}
}' \
https://api.dentally.co/v1/webhooks
Parameters
Parameters must be wrapped by a webhook object
| active: boolean |
If the webhook is active. Only active webhooks will be delivered |
| events: array |
The events the webhook responds to. |
| name: string |
The name of the webhook so users can identify it within Dentally |
| secret: string |
A secret string that is used to sign the webhooks |
| url: string |
The URL of where the webhook payload will be delivered. Must be HTTPS. |
EXAMPLE RESPONSE
{
"webhook": {
"id": 2,
"active": true,
"events": [
"patient.created",
"patient.updated",
"patient.deleted"
],
"failed_deliveries": 0,
"last_delivered_at": null,
"name": "My example webhook",
"successful_deliveries": 0,
"url": "https://example.com/webhooks"
}
}
Returns
The newly created webhook object
Get a single webhook
Retrieves the details of a webhook
DEFINITION
GET https://api.dentally.co/v1/webhooks/{WEBHOOK_ID}
EXAMPLE REQUEST
curl https://api.dentally.co/v1/webhooks/1
Parameters
| id: | required |
Returns
The existing webhook object
EXAMPLE RESPONSE
{
"webhook": {
"id": 1,
"active": true,
"events": [
"appointment.created",
"appointment.updated",
"appointment.deleted"
],
"failed_deliveries": 0,
"last_delivered_at": "2017-12-13T12:34:56.000+00:00",
"name": "My example webhook",
"successful_deliveries": 343,
"url": "https://example.com/webhooks"
}
}
Delete a webhook
Deletes a webhook
DEFINITION
DELETE https://api.dentally.co/v1/webhooks/{WEBHOOK_ID}
EXAMPLE REQUEST
curl --include \
--request DELETE \
https://api.dentally.co/v1/webhooks/1
Parameters
| id: integer |
required |
Returns
Returns a 204 response
List all webhooks
DEFINITION
GET https://api.dentally.co/v1/webhooks
EXAMPLE REQUEST
curl http://api.dentally.co/v1/webhooks
EXAMPLE RESPONSE:
{
"webhooks": [
{
"webhook": {
"id": 1,
"active": true,
"events": [
"appointment.created",
"appointment.updated",
"appointment.deleted"
],
"failed_deliveries": 0,
"last_delivered_at": "2017-12-13T12:34:56.000+00:00",
"name": "My example webhook",
"successful_deliveries": 343,
"url": "https://example.com/webhooks"
}
},
{...},
{...}
],
"meta": {
"current_page": 1,
"total": 3
}
}
Returns
Returns a list of webhooks
Scopes
Scopes let you specify exactly what type of access you need. Scopes limit access for OAuth tokens, they do not grant any additional permission beyond that which the user already has.
The requested scopes will be displayed to the user on the authorization form.
You should only request the scopes that are required for your application. Applications requesting unnecessary scopes may have their access tokens revoked.
You can find the current OAuth scopes in the X-OAuth-Scopes header.
$ curl -H "Authorization: Bearer ACCESS_TOKEN" https://api.dentally.co -I
HTTP/1.1 200 OK
X-OAuth-Scopes: user:read patient:read patient:update
| Name | Description |
|---|---|
| appointment | All appointment actions. This scope includes appointment:read, appointment:create, appointment:update and appointment:delete |
| appointment:create | Create appointments |
| appointment:delete | Delete appointments |
| appointment:read | View appointment data |
| appointment:update | Update appointments |
| financials | All financial actions. This scope includes financials:read, financials:create and financials:delete |
| financials:create | Create payments and payment explanations. |
| financials:delete | Delete payments and payment explanations. |
| financials:read | Read account, payment and invoice data |
| patient | All patient actions. This scope includes patient:read, patient:create, patient:update and patient:delete |
| patient:create | Create patients |
| patient:delete | Archive patients |
| patient:read | View patient data |
| patient:update | Update patients |
| practice | All practice actions. This scope includes practice:read and practice:update. In addition to the practice endpoint this scope includes access to payment plan, sites and webhooks. |
| practice:read | View practice data |
| practice:update | Update practice data |
| treatments | All treatment related resources. This scope includes treatments, treatment_plans and treatment_plan_items. |
| user | All user & practitioner actions. This scope includes user:read and user:update |
| user:read | Read user & practitioner data |
| user:update | Update user & practitioner data |
Errors
Dentally uses HTTP response codes to indicate the success or failure of the API request
EXAMPLE RESPONSE
{
"error": {
"type": "invalid_access_error",
"message": "API access is not enabled for this user",
"documentation_url": "https://developer.dentally.co"
}
}
EXAMPLE RESPONSE
{
"error": {
"type": "invalid_request_error",
"message": "The patient could not be saved",
"params": {
"first_name": [
"seems to be missing"
]
}
}
}
Attributes
Attributes will be wrapped in an error object
| type: string |
The type of error returned. This can be invalid_request_error or invalid_access_error |
| message: string |
A human readable message providing more details about the error. These can be displayed to your users |
| params: hash, optional |
The parameters the error(s) relate to and associated message(s). You can use this to display more detailed errors to your users |
HTTP Response Codes
| Code | Reason |
|---|---|
| 200 | OK – Everything worked as expected |
| 204 | No Content – Everything worked as expected but we’re not returning any content |
| 400 | Bad Request – Often missing a required parameter |
| 401 | Unauthorized – Your API key is not valid |
| 403 | Forbidden – The user does not have access to the requested item |
| 404 | Not Found – The requested item could not be found |
| 410 | Gone – The requested resource has been removed |
| 422 | Unprocessable Entity – The requested item could not be processed. The reason will be included in the response |
| 500 | Internal Server Error – We had a problem with our server. Try again later or check our status page |
| 503 | Service Unavailable – We’re temporarily offline for maintenance. Please try again later |
Rate Limits
The Dentally API is rate limited on a per user basis. Each user is allowed to make 3,600 requests per hour however the Appointment availability endpoint is restricted to 200 requests per hour and you are restricted to sending 100 SMS per day.
You can check the returned HTTP headers of any API request to see your current rate limit status:
EXAMPLE HEADERS
curl -i https://api.dentally.co/users
HTTP/1.1 200 OK
X-RateLimit-Limit: 3600
X-RateLimit-Remaining: 3278
X-RateLimit-Reset: 1494590400
| Header Name | Description |
|---|---|
| X-RateLimit-Limit | The maximum number of requests that the user is permitted to make per hour. |
| X-RateLimit-Remaining | The number of requests remaining in the current rate limit window. |
| X-RateLimit-Reset | The time at which the current rate limit window resets in UTC epoch seconds. |
Once you go over the rate limit you will receive an error response.
EXAMPLE ERROR
HTTP/1.1 403 Forbidden
X-RateLimit-Limit: 3600
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1494590400
{
"error": {
"type": "invalid_access_error",
"message": "Rate limit exceeded"
}
}
Checking your rate limit
DEFINITION
GET https://api.dentally.co/rate_limit
EXAMPLE RESPONSE
{
"resources": {
"core": {
"limit": 3600,
"remaining": 3595,
"reset": 1494590400
},
"appointment_availability": {
"limit": 200,
"remaining": 190,
"reset": 1494590400
},
"sms": {
"limit": 100,
"remaining": 92,
"reset": 1494590400
}
}
}
You can check your current rate limit status at any point using the rate limit API. Accessing this endpoint does not count against your rate limit.
Data Formatting
| Time zones / dates | All timestamps are formatted as ISO8601 with timezone information. For endpoints that allow for a timestamp to be specified, we use that exact timestamp. These timestamps look something like 2017-02-03T13:14:15.123Z.For endpoints that require dates, we expect a date string in the format YYYY-MM-DD, where an example would look like 2017-02-03. |
| Email addresses | Must comply with RFC 2822 and RFC 3696 |
Changelog
API Changelog
We try and make changes as backwards compatible as possible however, occasionally, breaking changes may be required.
| 2024-06-03 | Added owner to treatments responses. |
| 2024-06-03 | Correct payment_plan_id to integer type in patients endpoint. |
| 2024-05-09 | Added appointment_cancellation_reason_id to appointment endpoint. |
| 2024-05-03 | Added breaks to rota_practitioner_diaries endpoint. |
| 2024-05-02 | Added appointment_cancellation_reasons endpoint. |
| 2024-05-02 | Added prsi_eligibilites endpoint. |
| 2024-05-02 | Added pps_number to patients. |
| 2024-04-19 | Added emergency contact name, relationship, phone, phone_country and phone_normalized to patients. |
| 2024-03-26 | Added active to single and list treatment responses. Also added active parameter to treatments. |
| 2024-01-16 | Added updated_after, updated_before, created_after, created_before parameters to treatment_appointments endpoint. |
| 2024-01-12 | Added sorting description and items to invoices endpoint. |
| 2023-10-06 | Added updated_after filtering to invoice items. |
| 2023-10-06 | Added custom_fields attributes to patients and treatment_plan_items endpoints |
| 2023-10-05 | Added custom_fields endpoint. |
| 2023-08-03 | Added acquisition_sources |
| 2023-08-03 | Added acquisition_source_id to patient response. |
| 2022-07-07 | Added booked_via_api to appointments response. |
| 2022-06-15 | Added rooms endpoint and room_id to appointments response. |
| 2022-03-09 | Added contract_targets to practitioners response. |
| 2021-12-21 | Added optional site_id and active parameters to the payment_plan endpoint. |
| 2021-12-03 | Added ortho and continuation_part_number fields to the NHS claims API. |
| 2021-10-27 | Added approval_date field to NHS claims API. |
| 2021-10-18 | Added patient_stats endpoint. |
| 2021-10-09 | Added Treatment Categories endpoint and removed erroneous treatment_category_name from Treatments endpoint. |
| 2021-09-30 | Added Recalls endpoint. |
| 2021-08-06 | Added ids filter to the treatment_plans endpoint. |
| 2021-08-03 | Added practitioner_id filters to the treatment_plans and treatment_plan_items endpoints. |
| 2021-07-19 | Added allowed_sites and site_id to user endpoint. |
| 2021-07-19 | Added payment_plan_id filter to patient endpoint. |
| 2021-07-19 | Added site_id to payment_plan endpoint. |
| 2021-07-19 | Added default_payment_plan_id to site endpoint. |
| 2021-05-18 | Deprecate updated_since, in favour of updated_after. updated_since support is continued for backwards compatibility. |
| 2021-05-07 | Added completed_on, updated_after & updated_before filters to TreatmentPlanItems endpoint. |
| 2021-04-21 | Added Payment Explanations GET endpoint. |
| 2021-03-17 | Added NHS claims endpoint. |
| 2021-03-17 | Added Contracts endpoint. |
| 2021-03-17 | Added site_id filter to Payments endpoint. |
| 2021-03-17 | Added created_after & site_id filter to Patients endpoint. |
| 2021-03-17 | Added updated_after & site_id filter to Invoices endpoint. |
| 2021-03-12 | Added updated_after & site_id filters to Appointments endpoint. |
| 2021-03-10 | Added created_after, updated_after & site_id filter to Practitioners endpoint. |
| 2021-03-08 | Added title for users endpoint & embedded responses. |
| 2020-11-18 | Added endpoint for invoices, invoice_items and sundries. |
| 2020-11-18 | Added appointment_reasons endpoint. |
| 2020-10-08 | Added email_address to site endpoint. |
| 2020-10-26 | Added payment plan id to the payment endpoint. |
| 2020-08-20 | Added home, mobile & work phone country iso code to the patient endpoint. |
| 2020-03-16 | Added logo_url to the site endopoint. |
| 2020-03-10 | Added opening_hours to the site endopoint. Added active to the site endpoint. Clarified the practice opening hours. |
| 2019-08-09 | Added treatments, treatment plans, treatment appointments and treatment plan items endpoints. Also added new treatments scope. |
| 2018-11-13 | Added session appointments endpoint |
| 2018-10-09 | Added opening_hours to the practice endpoint |
| 2018-03-06 | Added new marketing attribute to the patient endpoint |
| 2018-02-19 | Added optional updated_since parameter to the patient list endpoint |
| 2017-12-14 | Added IDs to practices. Added sites endpoint and site_id attribute to patients, payments and practitioners. Added webhooks endpoint to allow you to view, create, update and delete webhooks through the API. |
| 2017-02-03 | Added metadata attributes to patients and appointments. Payments and payment explanations can now be created and deleted. |
| 2015-02-02 | Added payments and accounts (read only) |
| 2015-02-12 | Added custom fields \ labels to the patient and practice objects |