NAV Navbar
Logo
shell

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.

Appointments

The appointment object

Appointments belong to a practice and can be used for patient appointments, lunch breaks etc.

EXAMPLE RESPONSE

{
  "appointment": {
    "id": 2,
    "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
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,
    "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,
    "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,
    "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,
      "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": "[email protected]",
    "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",
    "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"
  }
}

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

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

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"
    }
}

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": "[email protected]",
    "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",
    "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"
  }
}

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

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",
    "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"
  }
}

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:
uuid, 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": "[email protected]",
      "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",
      "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"
    },
    {...},
    {...}

  ],
  "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": "[email protected]",
      "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": "[email protected]",
      "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": "[email protected]",
      "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": "[email protected]",
        "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

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"
  }
}

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

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"
    }
  ],
  "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": "[email protected]",
    "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": "[email protected]",
    "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,
    "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&nbsp;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",
    "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
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
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,
    "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&nbsp;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",
    "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,
      "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&nbsp;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",
      "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

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": "[email protected]",
    "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": "[email protected]",
    "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": "[email protected]",
    "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": "[email protected]",
    "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": "[email protected]",
      "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": "[email protected]",
    "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": "[email protected]",
    "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": "[email protected]",
    "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": "[email protected]",
    "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": "[email protected]",
    "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:

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