Overview

Use this API to submit ambulance analytics data to our Data Processing Service (DPS) so that it can be made available for analysis and review by NHS England and ambulance trusts.

Ambulance analytics data is information relating to emergency calls (999, 111 and others), received at an Emergency Operations Centre (EOC) and processed into a Computer Aided Despatch (CAD) system, including:

• call details
• response details - including response times and episode outcome times patient
• contact details - including patient demographics, patient response details, patient information, injury information, patient assessment, medication, observations, diagnoses, conveying outcome, safeguarding and public health information

You can:

• post ambulance analytics data individually or in batches

You cannot:

• read any of the records stored in DPS

The API is asynchronous - to receive error notifications, you need to use MESH. The following diagram illustrates the end-to-end process:

The following describes the end-to-end process:

1. the Ambulance Trust System sends the ambulance analytics data to the Ambulance Analytics API
2. the Ambulance Analytics API forwards the ambulance analytics data to our Data Processing System (DPS)
3. if there is an error, DPS sends an error notification to MESH
4. the Ambulance Trust System retrieves the error notification from MESH
5. an Analytics User views ambulance analytics data in our NHS Digital Analytics Dashboards
6. the NHS Digital Analytics Dashboards get the ambulance analytics data from DPS

Legal Use

This API can only be used where there is a legal basis to do so. Make sure you have a valid use case before you go too far with your development. You must do this before you can go live (see ‘Onboarding’ below).

Related APIs

Use Messaging Exchange for Social care and Health (MESH) to receive error notifications from DPS for this API

API status and roadmap

This API is in private beta, meaning:

• we might make breaking changes, but only if we can't avoid it, and we'll give advance notice
• we can't guarantee availability or performance
• it is available for production use, but only to a small group of ambulance trusts in England

To see our roadmap, or to suggest, comment or vote on features for this API, see our interactive product backlog.

If you have any other queries, please contact us.

Technology

This API uses HTTP POST to submit data.

The data payload conforms to the FHIR global standard for health care data exchange. Specifically, it is aligned with FHIR UK Core, which is built on FHIR Release 4. To see the FHIR message payload, see the Ambulance Data Set FHIR Implementation Guide

Network access

This API is available on the internet and, indirectly, on the Health and Social Care Network (HSCN).

For more details, see Network access for APIs.

Security and authorisation

This API is application-restricted - we authenticate the calling application but not the end user. In particular, it uses signed JWT authentication - you authenticate your application by sending a signed JSON web token (JWT) to our OAuth 2.0 authorisation server. For more details see Application-restricted RESTful APIs - signed JWT authentication.

Detailed integration instructions

This API follows the OAuth 2.0 protocol, the authentication method (unattended access) is designed for authentication without a user being present. You can authenticate by sending a JSON Web Token (JWT) token signed with a private key with the RS512 algorithm. Once the target server receives the JWT token it will lookup for a set of public keys from either a URL or store. The target server will then check each public key until it finds one that matches. The current flow to use this API is:

• POST request with a signed JWT token and other required headers to the /token endpoint
• POST request with the access token in the Authorisation header to the /submission endpoint

Generate a Private/Public Key Pair

Run the following commands on the command prompt to generate a private/public key pair on a UNIX system (Linux, MacOS):

ssh-keygen -t rsa -b 4096 -m PEM -f jwtRS512.key
openssl rsa -in jwtRS512.key -pubout -outform PEM -out jwtRS512.key.pub

The resulting files, jwtRS512.key and jwtRS512.key.pub are the private and public keys, respectively.

Create a Key Identifier (KID), a unique name to identify the key pair in use. This KID will be used to refer to the key pair when constructing and posting the JWT.

Register a Public Key with API Management

Email API Management with your KID and your public key as an attachment. The unattended access public key management process is currently not self-service, however we do aim to provide this in the future as part of our product roadmap.

Your public key will be associated with your test app in the environment of your choice. You will receive an email once this has been completed successfully. Now use your KID and private key to sign your JWT requests.

Generate a JWT and sign it

A JWT is a token that consists of three parts: a header, a payload and a signature. The header details the algorithm and token type. The payload consists of data (detailed below) and the signature is used to verify the token itself. More details on generating a JWT Token.

Note: We strongly recommend that you use a library to generate your JWT tokens, as this can be a complicated process to perform by hand.

Header

The header for the JWT details the authentication and token type used. The algorithm used is RS512, matching the algorithm used to generate the private/public key pair.

Example:

{
  "alg": "RS512",
  "typ": "JWT",
  "kid": "test"
}

Payload

The payload consists of the following mandatory claims encoded as a JSON structure:

Example:

{
  "iss": "<test-app-api-key>",
  "sub": "<test-app-api-key>",
  "aud": "https://int.api.service.nhs.uk/ambulance-analytics/token",
  "jti": "<unique-per-request-id>",
  "exp": <current-time-plus-5mins-from-jwt-creation>
}

The Signature

The signature consists of the private key signed contents of the header and payload.

Assemble the JWT

The JWT consists of the base64 encoded header (separated by a period), the base64 encoded payload (separated by a period), followed by the base64 encoded signature.

For more details see generating a JWT Token.

Submit the access token request

The access token request consists of a Hypertext Transfer Protocol Secure (HTTPS) request to the following endpoint, along with the x-www-form-urlencoded body consisting of four fields:

POST /ambulance-analytics/token HTTP/1.1
Host: int.api.service.nhs.uk
Content-Type: application/x-www-form-urlencoded
client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer&client_assertion=<jwt_token>&grant_type=client_credentials

The response consists of a JSON structure, the most important aspect being the “access_token” key. To submit the data into DPS, use this OAuth 2.0 access token in subsequent requests to the /submission endpoint. The request fields are detailed below.

Using the access token to submit data into DPS

Once you have received the ”access_token”, you can make data submissions to DPS via POST request to the /submission endpoint, with the authorisation header set to bearer and the access token.

Environments and testing

Sandbox testing

Our sandbox environment:

• is for early developer testing
• only covers a limited set of scenarios
• is stateless, so it does not actually persist any updates
• is open access, so does not allow you to test authorisation

For more details on sandbox testing, or to try out the sandbox using our "Try this API" feature, see the documentation for each endpoint.

Integration testing

Our integration test environment:

• is for formal integration testing

Onboarding

You need to get your software approved by us before it can go live with this API. We call this onboarding. The onboarding process can sometimes be quite long, so it’s worth planning well ahead.

To onboard for this API, follow the Supplier Conformance Assessment List (SCAL) process.

When following the SCAL process, note that:

• In step 8: you need to review and complete the Ambulance Analytics API risk log to show that you have understood and mitigated the various risks. You might be asked to provide some evidence to prove that controls have been put in place. You’ll find the risk log embedded within the Ambulance Analytics API tab in the SCAL.
• In step 10: when you complete the Service Desk Registration Form, send it to api.management@nhs.net.
• In step 11: submit your completed SCAL to api.management@nhs.net.
• In step 14: to request production access, contact us at api.management@nhs.net.

Endpoint: PostAmbulanceData