EXACT API v1.0

EXACT is an on-premises dental practice management system, where our customers host the software on their own servers. This API suite allows remote connection to these servers through a single entrypoint, as if it was a cloud-native API.

The EXACT API suite offers our partners access to our customers through the cloud, allowing the development and integration of products by trusted third parties. Our marketplace product system allows end customers to remain in control, requiring explicit consent through subscriptions to a product before third parties may access their data.

Note

This suite of APIs is for partner integrators under contract with us - we are not currently accepting new partners.

Using the APIs

All API endpoints are authenticated, and each endpoint will require special permissions that are assigned by us to your client - which is enforced by the tokens that the integrating application receives. Some endpoints will also return extended data based on these permissions.

Most endpoints require a specific target customer, known as a practice id. These identifiers direct the request through our servers toward the customer's server to handle, with the response being returned at the end of the request.

In order to be able to make a request to a practice, they must have first given the requesting application permission to access their data through these APIs. This is done through a subscription via our marketplace product system where practice administrators may self serve (if the product is publicly listed), or be managed on their behalf by our sales and integrations team.

To see who is currently subscribed to the contextually authorised application, the ListActiveSubscriptions endpoint may be used. In conjunction with the GetPracticeDetails endpoint, this could be used as part of an automatic onboarding system.

Endpoints

We operate two completely disconnected environments - one for production, and another for QA (pre-prod, staging). The environments make use of different endpoints in order to access.

Real customers exist on the production environment, and so are only accessible through the production environment API suite. The same goes for the QA environment, which hosts simulated/fake practices - including instances of our software that may have been set up for the integrator to test with. You must make requests using the same environment as the target you wish to communicate with, the environments are not connected in any way.

The different API environments also make use of different authentication environments (authorities), and will likely have different client secrets to requests tokens with.

API endpoints

Environment Url
QA https://qa-api.ex.softwareofexcellence.com
Production https://api.ex.softwareofexcellence.com

Authentication endpoints

Environment Url
QA https://qa-auth.softwareofexcellence.com/connect/token
Production https://auth.softwareofexcellence.com/connect/token

Considerations

Software versioning

Given that EXACT is hosted on-premises by the customer, the customer is also responsible for keeping our software up to date. We make extensive use of automatic updates, where versions are released through a ring rollout system - but some customers opt out of updates altogether.

Endpoints that we create are often associated with a released version of EXACT, and require that each target be on that version of the software before the server is able to handle the request.

We denote these considerations for each endpoint. When discussing the requirements of the application, we can include and enforce a minimum EXACT version before allowing subscriptions to the product based on the endpoints needed.

Error handling

The EXACT API allows a remote cloud connection into the software that our customers operate on their own servers, with permission.

Not all customers operate fully-equipped datacenters, and so special consideration need to be taken to ensure that your application can handle the transient errors when their servers are inaccessible or otherwise encounter errors - we do not manage customer servers.

When the EXACT API is unable to communicate with the requested customer, our endpoints will respond with the status code HTTP 503 Service Unavailable - the best action would be to exponentially backoff and try again later. Note that this does not necessarily mean that other customers are inaccessible.

An error when handling a specific request on a customer's server software will respond with the status code HTTP 502 Bad Gateway.

Authentication

The API authentication follows the OAuth 2.0 Client Credentials grant flow for protecting API resources.

The general sequence for authentication is:

  • The caller requests an access token from the authorization server using the Client Id and Client Secret issued to you by HSO along with the scopes required for subsequent API requests.
  • The Identity server verifies Client Id and Client Secret and issues an access token to the caller if verification succeeds.
  • The caller receives the issued access token to use for subsequent API calls to access resources.
  • The access token is used on all calls to the API as a header (Bearer Token)
    • Parameter Name: Authorization, in: header. JWT Bearer Token.

Requesting a Token

As the HSO Identity Server implements the OIDC standard, all the information related to the authentication process can be obtained through the endpoint .well-known/openid-configuration.

To request a token, the ClientId and ClientSecret must joined by a colon (ClientId:ClientSecret), encoded in Base64, and passed as a Basic authentication header.

import http.client

conn = http.client.HTTPSConnection("qa-auth.softwareofexcellence.com")
payload = 'grant_type=client_credentials&scope=appointment.list%20practice.get'
headers = {
  'Authorization': 'Basic [base64(clientId:clientSecret)]',
  'Content-Type': 'application/x-www-form-urlencoded'
}
conn.request("POST", "/connect/token", payload, headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))