Overview

Healthcode provides HTTP-based APIs which follow the principles of REST. The subsections below detail some of the common interface aspects.

Discovering the APIs

Healthcode publishes a large number of APIs across multiple bundles. To simplify integration and increase flexibility, discovery documents are used. A discovery document is a JSON document hosted at a well-known location, containing key-value pairs providing details about API configurations, including URIs, for the various REST APIs.

The discovery document is hosted at https://api.healthcode.co.uk/.well-known/discovery-document.json*

* – A special case is the discovery document for our single sign-on APIs which is hosted at https://auth.healthcode.co.uk/.well-known/openid-configuration

It’s VITAL that discovery documents are used by the integrating systems for ALL Healthcode APIs rather than hard-coding API endpoint addresses, as the URL addresses may change in the future. Healthcode reserves the right to partially or fully alter API endpoint locations without notice. In such cases the discovery document at the well-known location will be updated to reflect the new and correct endpoint URIs.

How to integrate

The Healthcode API interfaces and integration workflows are designed to align with common technology standards to enable easier integration. Simply follow the below step-by-step instructions.

  1. Ensure you have relevant subscription.
    Accessing the APIs require you to have relevant subscription. If you are an existing customer contact your Healthcode business development contact for support if needed. If you are a new customer, explore our available products at https://www.healthcode.co.uk and use the contact options available to get in touch with us.

  1. Know the site id.
    Healthcode uses a construct called site to enable secure storage and access of customer data. When calling the APIs, the integrating systems need to specify the site to create, or query, the data under. The site id needs to be supplied under the SU-SiteId header. Refer instructions here for details.
  1. Obtain API credentials.
    The Healthcode APIs support connection through OAuth 2.0 workflow. You will need to obtain an API key pair (an API Key Id and corresponding API Key) to establish connection. Refer instructions here for details.
  1. Integrate with the Healthcode SSO Server for authentication.
    Once you have API credentials and know the site you would like to operate on, you are ready to integrate. The programmatic implementation need to use a two-step connection workflow wherein first, you obtain an access token by integrating with the Healthcode Single Sign-on (SSO) server, and subsequently call the APIs you need, supplying the access token as input.

    Refer here for instructions on obtaining access token. Pay special attention to the recommended best practices for handling the API credentials.

    Note, you need not have to obtain a new token for each API call. We recommend you maintain an authentication session on your end wherein you obtain an access token from the Healthcode SSO server once, continue using it for making API calls, and when the current token expires, obtain a new token from the SSO server again.
  1. Integrate with the APIs.
    You can call the individual APIs by supplying the access token and site id details along with any API-specific input parameters. Following are some of the common interface standards.
    • The access token needs to be supplied within the Authorization HTTP header.
    • The site id needs to be supplied within the SU-SiteId HTTP header.
    • Where not specified otherwise, the APIs support standard CRUD interface (ref here).
    • There could be multiple versions of same API in operation. You need to specify the version using the HC-API-Version HTTP header (ref here). Where the header is not specified, version 1 is assumed – however, you are strongly recommended to explicitly specify the version to avoid accidental or unexpected breaks of the integration.
    • All Healthcode APIs conform to HL7 FHIR standards (ref here), except in specific cases (for example, the authentication APIs align with OAuth 2.0 specification instead). Accordingly, the Content-Type HTTP header should be set to application/fhir+json.
    • The Healthcode APIs accept and return data in UTC timezone (ref here). The integrating systems need to ensure they handle any relevant conversion to local timezones where applicable.

Additional information

Additional information on the general rules and guidelines applicable to integrating with the Healthcode APIs are documented within below subsections.