Aerona API Specification (1.0)

Download OpenAPI specification:Download

Overview

This is the documentation for the Aerona API. Aerona provides a secure set of APIs to integrate with Aerona Clinic from third party software. These APIs use a combination of RESTful URIs and JSON objects to pass the data back to the client. They will be only accessible via a Secure Socket Layer (HTTPS) connection meaning all data communicated between the two systems will be encrypted using TLS.

Usage

To use the API, the Login API must be called first to retrieve a token. This token is returned in the AERONA-AUTH-TOKEN header in the Login response. This token must be subsequently passed to all other API requests in a header field called AERONA-AUTH-TOKEN.

Rate Limit

This token is valid for a period of one hour after which it expires and you will have to log in again. A rate limit of 300 requests per 15 minute period is in place. If you exceed this rate limit, your token will be invalidated.

Webhooks

Webhooks can be setup to notify you when an event happens in Aerona (e.g. when a new appointment has been created). Each Webhook can be sent to a different URL, however you must use an SSL/TLS URL. A response should be returned from your webhook handler with a 200-status code, to tell Aerona that the request was successful. If no response is received or a response other than a status code of 200 is received then Aerona will retry the webhook up to 24 more times (once each hour).

Webhooks are available for the following types of objects.
  • Patient
  • Appointment
  • Treatment

Appointment

Appointment related endpoints

Update the status of an existing appointment.

This API is used to update the status of an appointment in Aerona.

path Parameters
appointmentId
required
number <long> <= 11 characters

The ID of the appointment whose status is to be updated.

header Parameters
AERONA-AUTH-TOKEN
required
string

Header containing the Aerona Authorization token. This token is generated after a call to the Login API is successfully validated. The token must be sent back to the server in the header of each subsequent call for that user.

The token is valid for 1 hour.

Request Body schema: application/json
appointmentStatusId
required
integer <int32> <= 11 characters

This is the updated appointment status id.

1 - Unconfirmed, 2 - Confirmed, 3 - Arrived, 4 - Failed to Attend, 5 - Cancelled by Practice, 6 - In Clinic, 7 - Completed, 8 - Online Booking Request, 9 - Reminder Sent, 10 - Scheduled, 11 - Unscheduled, 12 - Cancelled by Patient, 13 - Deleted, 14 - Late Cancellation, 16 - Was Not Brought.

Responses

Request samples

Content type
application/json
{
  • "appointmentStatusId": 7
}

Response samples

Content type
application/json

True if appointment status was successfully updated.
False otherwise.

true

Create a new Appointment

Appointments created using this API will have a flag set against them to show that the appointment originated from the APIs.

header Parameters
AERONA-AUTH-TOKEN
required
string

Header containing the Aerona Authorization token. This token is generated after a call to the Login API is successfully validated. The token must be sent back to the server in the header of each subsequent call for that user.

The token is valid for 1 hour.

Request Body schema: application/json
practiceId
required
integer <int64> <= 11 characters

The ID of the Practice. This is taken from the Practice list.

userId
required
integer <int64> <= 11 characters

This is the ID of the Patient's preferred Clinician. This is taken from the Clinician list.

appointmentTypeId
required
integer <int64> <= 11 characters

This is the Appointment Type ID. This is taken from the Appointment Type list.

appointmentStatusId
required
integer <int32> <= 11 characters

This is the Appointment Status ID.

1 - Unconfirmed, 2 - Confirmed, 3 - Arrived, 4 - Failed to Attend, 5 - Cancelled by Practice, 6 - In Clinic, 7 - Completed, 8 - Online Booking Request, 9 - Reminder Sent, 10 - Scheduled, 11 - Unscheduled, 12 - Cancelled by Patient, 13 - Deleted, 14 - Late Cancellation, 16 - Was Not Brought.

appointmentTime
required
string <date-time>

The date of the Appointment.

emergency
boolean

This is the identifier for stating if an Appointment is an emergency or not.

appointmentNotes
string

Any additional notes related to the Appointment.

Note: This is not clinical notes.

duration
required
integer <int32> <= 6 characters

This is the length of the Appointment in minutes.

patientId
required
integer <int64> <= 11 characters

This is the Patient ID of the Patient requesting the Appointment.

Responses

Request samples

Content type
application/json
{
  • "practiceId": 9876,
  • "userId": 34567,
  • "appointmentTypeId": 1864,
  • "appointmentStatusId": 7,
  • "appointmentTime": "2023-01-19T13:30:00Z",
  • "emergency": false,
  • "appointmentNotes": "Patient is nervous.",
  • "duration": 45,
  • "patientId": 426909
}

Response samples

Content type
application/json

The newly created Appointment ID.

34234

Find Free Appointment Slots

Use to retrieve a list of available appointment slots when booking an appointment. The next 50 available appointment slots will be returned which meet the search criteria.

Either the clinicianId or clinicianTypeId must be supplied in the request, but not both.

query Parameters
clinicianId
number <long> <= 11 characters

The ID of the Clinician.

clinicianTypeId
number <long> <= 2 characters

The ID of the Clinician Type.

1 - General Dentist, 2 - Specialist Dentist, 3 - Hygienist, 4 - Orthodontist, 5 - Periodontist, 6 - Psychiatrist, 7 - Psychologist, 8 - Physiotherapist, 9 - Audiologist, 10 - Optometrist, 11 - Therapist, 12 - Beautician, 13 - GP, 14 - Dietician, 15 - Sports Rehabilitation Therapist, 16 - Personal Trainer.

practiceId
number <long> <= 11 characters

The ID of the Practice. This is found within the Practice list.

This must be supplied if you have added the Clinician Type ID, as we need to know which practice you want all appointments from.

appointmentTypeId
required
number <long> <= 11 characters

This is the Appointment Type ID. This is taken from Appointment Type list.

searchStart
required
string <date>
Example: searchStart=2022-04-01

This is the date that the appointment search will begin from.

timeOfDay
required
number <integer>

This is the time of day identifier which is selected from the find appointment search field.

0 - any, 1 - before 12pm, 2 - between 12pm and 5pm, 3 - after 5pm.

header Parameters
AERONA-AUTH-TOKEN
required
string

Header containing the Aerona Authorization token. This token is generated after a call to the Login API is successfully validated. The token must be sent back to the server in the header of each subsequent call for that user.

The token is valid for 1 hour.

Responses

Request samples

curl https://aeronadental.com/AeronaAPI/v1/find-appointment-slots?clinicianId=34567&practiceId=9876&appointmentTypeId=1864&searchStart=2022-04-01&timeOfDay=0  -H "AERONA-AUTH-TOKEN: <your token>" -H "Content-Type: application/json"

Response samples

Content type
application/json
[
  • {
    }
]

Appointment Type

Appointment Type related endpoints

Get the List of Appointment Types

Used to retrieve a list of Appointment Types.

If a practice ID is supplied then Appointment Types which are used by that practice will be returned. Otherwise Appointment Types of the practice of the authorised user will be returned.

If the practice uses Appointment Types based on the master practice, the Appointment Types of the master practice will be returned.

query Parameters
practiceId
integer <int64>
Example: practiceId=9876

The practice ID.

clinicianTypeId
number <long> <= 2 characters

The ID of the Clinician Type.

Set this if you want a list of Appointment Types for a specific Clinician Type.

1 - General Dentist, 2 - Specialist Dentist,3 - Hygienist, 4 - Orthodontist, 5 - Periodontist, 6 - Psychiatrist, 7 - Psychologist, 8 - Physiotherapist, 9 - Audiologist, 10 - Optometrist, 11 - Therapist, 12 - Beautician, 13 - GP, 14 - Dietician, 15 - Sports Rehabilitation Therapist, 16 - Personal Trainer.

includeDisabled
boolean
Example: includeDisabled=true

Should disabled Appointment Types be included? Default value is false.

onsiteOnly
boolean
Example: onsiteOnly=true

Do you want onsite Appointment Types only? Default value is false.

remoteOnly
boolean

Do you want remote Appointment Types only? Default value is false.

header Parameters
AERONA-AUTH-TOKEN
required
string

Header containing the Aerona Authorization token. This token is generated after a call to the Login API is successfully validated. The token must be sent back to the server in the header of each subsequent call for that user.

The token is valid for 1 hour.

Responses

Request samples

curl https://aeronadental.com/AeronaAPI/v1/appointment-types?practiceId=9876&clinicianTypeId=2349&includeOnly=true&onsiteOnly=true -H "AERONA-AUTH-TOKEN: <your token>" -H "Content-Type: application/json"

Response samples

Content type
application/json
[
  • {
    }
]

Payment

Payment related endpoints

Get Payment by ID

Allows you to get the Payment details for a given Payment.

path Parameters
paymentId
required
number <long> <= 11 characters

The ID of the Payment.

header Parameters
AERONA-AUTH-TOKEN
required
string

Header containing the Aerona Authorization token. This token is generated after a call to the Login API is successfully validated. The token must be sent back to the server in the header of each subsequent call for that user.

The token is valid for 1 hour.

Responses

Request samples

curl https://aeronadental.com/AeronaAPI/v1/payments/187941 -H "AERONA-AUTH-TOKEN: <your token>" -H "Content-Type: application/json"

Response samples

Content type
application/json
{
  • "id": 187941,
  • "patientId": 426709,
  • "practiceId": 9876,
  • "practiceName": "My Dentist Inc.",
  • "paymentType": "1",
  • "paymentMethod": "Credit Card",
  • "amount": 140.5,
  • "cancellation": 140.5,
  • "refund": 25,
  • "refundReference": 1,
  • "paymentNote": "Paid in full.",
  • "paymentDate": "2022-01-19T13:34:21Z",
  • "cancellationNote": "Cancelled by patient.",
  • "cancellationDate": "2022-01-22T10:22:56Z",
  • "patientPlan": false,
  • "patientCarePlanId": 1254,
  • "createdUserId": 34567,
  • "dateModified": "2022-01-24T08:25:34Z",
  • "thirdPartyProviderName": "My Insurance Co."
}

Get Payments by search criteria

This API allows you to get the payment details for payment(s) based on certain search criteria.

We recommend that you always set the fromDate and toDate in your searches. If you do not provide a search start date, it will default to the first day of the current month. If you do not provide a search end date, it will default to the current date.

query Parameters
patientId
integer <int64>
Example: patientId=426709

The Patient ID.

fromDate
string <date>
Example: fromDate=2021-01-01

The search start date.

toDate
string <date>
Example: toDate=2022-02-01

The search end date.

header Parameters
AERONA-AUTH-TOKEN
required
string

Header containing the Aerona Authorization token. This token is generated after a call to the Login API is successfully validated. The token must be sent back to the server in the header of each subsequent call for that user.

The token is valid for 1 hour.

Responses

Request samples

curl https://aeronadental.com/AeronaAPI/v1/payments/search?patientId=426709&fromDate=2021-01-01&toDate=2022-04-01 -H "AERONA-AUTH-TOKEN: <your token>" -H "Content-Type: application/json"

Response samples

Content type
application/json
[
  • {
    }
]

Invoice

Invoice related endpoints

Get Invoice by ID

This API allows you to get an Invoice for a given ID.

path Parameters
invoiceId
required
number <long> <= 11 characters

The Invoice ID.

header Parameters
AERONA-AUTH-TOKEN
required
string

Header containing the Aerona Authorization token. This token is generated after a call to the Login API is successfully validated. The token must be sent back to the server in the header of each subsequent call for that user.

The token is valid for 1 hour.

Responses

Request samples

curl https://aeronadental.com/AeronaAPI/v1/invoices/337292 -H "AERONA-AUTH-TOKEN: <your token>" -H "Content-Type: application/json"

Response samples

Content type
application/json
{
  • "id": 337292,
  • "patientId": 426709,
  • "date": "2022-01-19",
  • "quantity": 3,
  • "dateCompleted": "2022-01-19T13:34:21Z",
  • "price": 25,
  • "status": "Planned",
  • "saleItem": "Mouthwash",
  • "userId": 337292,
  • "discount": 5,
  • "discountAmount": 20,
  • "refundAmount": 50,
  • "refundNote": "Payment for treatment refunded",
  • "refundDate": "2022-01-19T13:34:00Z",
  • "refundMethod": "Credit Card",
  • "patientCarePlan": "Comprehensive",
  • "vatRate": 15,
  • "insurerFee": 50,
  • "adjustmentType": "Write Off",
  • "adjustmentNote": "Payment for treatment adjusted.",
  • "adjustmentAmount": 15,
  • "prechargeDate": "2022-01-19",
  • "trackingFee": 10
}

Get Invoices by search criteria

This API allows you to get the invoice details for treatment(s)/shop items, based on certain search criteria.We recommend that you always set the fromDate and toDate in your searches. If you do not provide a search start date, it will default to the first day of the current month. If you do not provide a search end date, it will default to the current date.

query Parameters
patientId
integer <int64>
Example: patientId=426709

The patient ID.

fromDate
string <date>
Example: fromDate=2021-01-01

The search start date.

toDate
string <date>
Example: toDate=2021-12-31

The search end date.

header Parameters
AERONA-AUTH-TOKEN
required
string

Header containing the Aerona Authorization token. This token is generated after a call to the Login API is successfully validated. The token must be sent back to the server in the header of each subsequent call for that user.

The token is valid for 1 hour.

Responses

Request samples

curl https://aeronadental.com/AeronaAPI/v1/invoices/search?patientId=426709&fromDate=2021-01-01&toDate=2021-12-31 -H "AERONA-AUTH-TOKEN: <your token>" -H "Content-Type: application/json"

Response samples

Content type
application/json
[
  • {
    }
]

Clinician

Clinician related endpoints

Retrieve a List of Clinicians

Used to retrieve the List of Clinicians for optional Practice ID and Appointment Type ID.

query Parameters
practiceId
number <long> <= 11 characters
Example: practiceId=9876

The ID of the Practice.

appointmentTypeId
number <long> <= 11 characters
Example: appointmentTypeId=1864

The Appointment Type ID.

header Parameters
AERONA-AUTH-TOKEN
required
string

Header containing the Aerona Authorization token. This token is generated after a call to the Login API is successfully validated. The token must be sent back to the server in the header of each subsequent call for that user.

The token is valid for 1 hour.

Responses

Request samples

curl https://aeronadental.com/AeronaAPI/v1/clinicians?practiceId=9876&appointmentTypeId=1864 -H "AERONA-AUTH-TOKEN: <your token>" -H "Content-Type: application/json"

Response samples

Content type
application/json
[
  • {
    }
]

Patient

Patient related endpoints

Get a Patient's details

This API can be used to get the complete Patient record of an existing Patient from Aerona.

path Parameters
patientId
required
number <long> <= 11 characters

The ID of the Patient.

header Parameters
AERONA-AUTH-TOKEN
required
string

Header containing the Aerona Authorization token. This token is generated after a call to the Login API is successfully validated. The token must be sent back to the server in the header of each subsequent call for that user.

The token is valid for 1 hour.

Responses

Request samples

curl https://aeronadental.com/AeronaAPI/v1/patients/426709 -H "AERONA-AUTH-TOKEN: <your token>" -H "Content-Type: application/json"

Response samples

Content type
application/json
{
  • "practiceId": 9876,
  • "patientTypeId": 1,
  • "sourceId": 4,
  • "referrerId": 28,
  • "genderId": 2,
  • "titleId": 0,
  • "forename": "Mary",
  • "surname": "Simpson",
  • "maidenName": "Jones",
  • "occupation": "Teacher",
  • "dob": "2000-09-13",
  • "knownAs": "Tom",
  • "address1": "The Cottage",
  • "address2": "Killylane",
  • "address3": "Eglint