HomeGuidesAPI Reference
Log In

API Overview

This page will help you get started with the Ally API

Ally 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 Ally 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 Ally 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 Ally API doesn't support bulk updates. You can work on only one object per request.


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


The Ally API uses API keys to authenticate requests. You can view and manage your API keys in the Ally Dashboard.

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.allyhealth.co.uk/v1/organisations' \
  -H 'Authorization: test_sdfo723rKk1l2jdak72l4jJk.f8pikalsfkjlaweirpwef8sdlfadsf'

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.


Ally 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 Ally'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.

200 - OKEverything worked as expected.
400 - Bad RequestThe request was unacceptable, often due to missing a required parameter.
401 - UnauthorisedNo valid API key provided.
402 - Request FailedThe parameters were valid but the request failed.
403 - ForbiddenThe API key doesn't have permissions to perform the request.
404 - Not FoundThe requested resource doesn't exist.
500, 502, 503, 504 - Server ErrorsSomething went wrong on Ally's end.

Handling Errors

Our Client libraries raise exceptions for many reasons, such as invalid parameters, authentication errors, and network unavailability. We recommend writing code that gracefully handles all possible API exceptions.

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 these three parameters: limit, starting_after, and ending_before.

🚦 OpenAPI specification

We develop our API services following the latest OpenAPI Specification

πŸ“ˆ Know your users

We are working on providing access to the granular metrics dashboard on Google Cloud to all our partners. It will provide secure access to all the data points and metrics for your API usage and for end-users usage of the frontend application.

πŸ’¬ We're here to help!

If you get stuck, shoot us an email

We're excited you're here! πŸ’™