Heim brings you a comprehensive API to request clinical care tasks in any location across the United Kingdom. The API is designed for any health organisation that needs a physical care task as part of their care pathway.

The Heim API is organised around REST. Our API has predictable resource-oriented URLs, accepts form-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs.

You can use the Heim API in test mode, which doesn't affect your live data or dispatch a health practitioner to carry out a real care task. The API key you use to authenticate the request determines whether the request is live mode or test mode.

The Heim API doesn't support bulk updates. You can work on only one object per request.

Sign-up

You can sign up and use the test environment immediately to let you try out the API and see the data you create in the Heim dashboard. The test environment will not request real care tasks or affect your live data.

Once you have signed-up, you can activate your organisation by providing your businesses information. Once your organisation is validated, your live API keys will appear in your account and you can create real care tasks.

Authentication

The Heim API uses API keys to authenticate requests. You can view and manage your API keys in the Heim Dashboard (requires Administrator role to view keys)

Test mode secret keys have the prefix "test_" and live mode secret keys have the prefix "live_"

Your API keys carry many privileges, so be sure to keep them secure! Do not share your secret API keys in publicly accessible areas such as GitHub, client-side code, and so forth.

Authentication to the API is performed via a HTTP header. Provide a header Authorization with value of your API key.

All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail.

curl -X 'GET' \
  'https://api.heim.health/v1/organisations' \
  -H 'Authorization: test_sdfo723rKk1l2jdak72l4jJk.f8pikalsfkjlawejsdkwef8sdlfadsf'

Please read our guide on Authentication options for other authentication methods should you decide to authenticate requests to our API directly from your front-end applications.

Using our API playground

You can try out the API in this playground. Just click "Log In" in the top right corner and we will fetch your test API key, and log you in to the playground.

By default this login will only return a test_ API key, although the playground will also work with live_ keys.

Errors

Heim uses conventional HTTP response codes to indicate the success or failure of an API request. In general: Codes in the 2xx range indicate success. Codes in the 4xx range indicate an error that failed given the information provided (e.g., a required parameter was omitted, an appointment creation request failed, etc.). Codes in the 5xx range indicate an error with Heim's servers (these are rare).

Some 4xx errors that could be handled programmatically (e.g., an appointment window is no longer available) include an error code that briefly explains the error reported.

Handling Errors

Our API raises exceptions for many reasons, such as invalid parameters, authentication errors, and resource unavailability. We recommend writing code that gracefully handles all possible API exceptions. A typical error response is:

{
  "error": {
    "message": "The parameter or request body property provided is not valid",
    "traceRequestId": "c2c71152-73e1-45f7-a8f9-840d59336ea2",
    "issues": [
      {
        "code": "custom",
        "message": "Invalid phone number",
        "path": [
          "phoneNumber"
        ]
      }
    ]
  }
}

If possible, please store the traceRequestId we return in any error message in your logs so that we can trace the full transaction across our platform and provide effective debugging and support.

Pagination

All top-level API resources have support for bulk fetches via "list" API methods. For instance, you can list patients, list appointments, and list tasks. These list API methods share a common structure, taking at least two parameters: limit and offset, and returning totalCount to represent the total number of objects available.

The typical response of a bulk fetch endpoint is:

{
  "object": "list",
  "url": "/v1/apipath",
  "data": [
         {...},
         {...}
    ],
  "traceRequestId": "84ac53d4-70e2-4463-befe-6d9f20d159fc",
  "totalCount": 68
}

For further information, please see Filters & Sorting

💪 Advanced topics

For a complete integration consider using:

• Webooks to update your system efficiently with the latest state from the Heim platform
• Metadata to send information to customise messaging or the steps taken during the Appointment
• Data to receive back data such as biometric readings recorded during the appointment

🚦 OpenAPI specification

We develop our API services following OpenAPI Version 3.1 specification. If you wish to use the specification of our API to generate client libraries for your system please contact your account manager or integration lead and we can supply you with the definition file.

💬 We're here to help!

If you get stuck, shoot us an email

We're excited you're here! 💙