API Specification

Overview

Use this API to access Registration Applications on the Register with a Register with a GP Surgery Service.

The API provides:

Access to patients' registration application information
- Demographic Details
- Health / Lifestyle questions
- Metadata

You cannot use this API to:

Submit a new Registration Application

Please click here to view the Register with a GP Surgery Questionnaire definition.

API Status and Roadmap

This access mode is in design meaning:

The API is not currently available

You can view progress of our roadmap item here.

Service Level

This API is a Silver service, meaning it is operational 24 hours a day, 365 days a year and supported 8am to 6pm, Monday to Friday excluding bank holidays

For more details, see service levels.

Technology

This API adheres to the RESTful architecture style, a standardized approach to building web services. It conforms with the FHIR global standard for exchanging healthcare data, specifically FHIR R4 (v4.0.1), with the exception of lacking support for the capabilities interaction.

The API incorporates certain FHIR extensions specific to particular countries, in this case, conforming to FHIR UK Core standards, specifically fhir.r4.ukcore.stu1 0.5.1.

It's worth noting that familiarity with FHIR isn't necessary to utilize this API, as FHIR APIs essentially function as RESTful APIs with defined guidelines. For instance:

Resource names are singular and capitalized (e.g., /Endpoint not /endpoints)

Regarding error handling, the API follows NHS guidelines. Examples illustrating error handling are provided in the Error section below.

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, meaning we authenticate the calling application but not the end user.

To use this API, use the following security pattern:

Application-restricted RESTful APIs - Signed JWT authentication

Operations

Request

Get the registration details of an application

GET /v1/applications/{Id}?odsCode={OdsCode}

URL Parameters

Id   :           - Unique Registration Application ID
odsCode:         - Unique Organisation Code to identify GP Practice

Example Request

curl -X GET "https://placeholder.nhs.uk/comms/v1/applications/{Id}?odsCode={odsCode}" \
 -H "accept: application/json"\
 -H "authorization: Bearer {Signed JSON Web Token}\

Reponse

Response Scenarios

Scenario	Response	Description
Application Exists	200	The Application has been submitted and is available to the requester.
Invalid JWT token	401	Authorisation is incorrect, invalid JWT.
Application Not Found	404	This indicates that an Application does not exist, it may never have existed or it may have been deleted.
Application Retrieved	410	Application has been retrieved by the GP Surgery.
Application Superseded	410	A new application has been submitted for this patient.
Application Expired	410	The application has expired and is no longer available.
Invalid ODS Code	422	The ODS code in the request must match that of associated Registration Application.

Response 200 - Application available

Response - The registration application has been found and its details are contained within the response body.

The Form definition is defined on the FHIR Development and Testing Tools (Skunkworks) (nhsdigital.github.io). Which allows users to create example payloads.

Errors We use standard HTTP status codes to show whether an API request succeeded or not. They are usually in the range:

200 to 299 if it succeeded
400 to 499 if it failed because of a client error by your application
500 to 599 if it failed because of an error on our server

Error 401 -Your request was not authorized, invalid JWT

➤ Example

{
   "errors":[
      {
         "id":"{errorId}",
         "code":"UNAUTHORIZED",
         "links":{
            "about":"{LINK TO API DOCUMENTATION}"
         },
         "status":"401",
         "title":"Unauthorized",
         "detail":"Authentication credentials are missing or invalid. Please provide a valid JWT.",
         "source":{
            "parameter":"Authorization"
         }
      }
   ]
}

➤ Schema


errors:           - Min Items: 1 Max Items: 1
id: string        - Type_ErrorIdentifier
code: enum        - Enum_Error_Unauthorized:
                    Allowed: UNAUTHORIZED
status: enum      - Allowed: 401
title: enum       - Allowed: Unauthorized
detail: enum      - Allowed: Authentication credentials are missing or invalid. Please provide a valid JWT
source:           - parameter: {Id}

Error 404 -The registration application has not been found, check the application ID passed in the URL

➤ Example

{
   "errors":[
      {
         "id":"{errorId}",
         "code":"NO_SUCH_APPLICATION_ID",
         "links":{
            "about":"{LINK TO API DOCUMENTATION}"
         },
         "status":"404",
         "title":"Registration Application Not Found",
         "detail":"The registration application has not been found, check the application ID and ODS Code passed in the URL.",
         "source":{
            "parameter":"{Id}"
         }
      }
   ]
}

➤ Schema


errors:           - Min Items: 1 Max Items: 1
id: string        - Type_ErrorIdentifier
code: enum        - Enum_Error_NoSuchApplicationId:
                    Allowed: NO_SUCH_APPLICATION_ID
status: enum      - Allowed: 404
title: enum       - Allowed: The registration application has not been found.
detail: enum      - Allowed: The registration application has not been found, check the application ID and ODS Code passed in the URL.
source:           - parameter: {Id}

Error 410 -The registration application is no longer available to retrieve. This may be because the Application has been retrieved by the GP Surgery, a new application has been submitted for this patient or the application has expired

➤ Example

{
   "errors":[
      {
         "id":"{errorId}",
         "code":"APPLICATION_EXPIRED",
         "links":{
            "about":"{LINK TO API DOCUMENTATION}"
         },
         "status":"410",
         "title":"Gone",
         "detail":"The registration application has expired and is no longer available",
         "source":{
            "parameter":"{Id}"
         }
      },
       {
         "id":"{errorId}",
         "code":"APPLICATION_SUPERSEDED",
         "links":{
            "about":"{LINK TO API DOCUMENTATION}"
         },
         "status":"410",
         "title":"Gone",
         "detail":"The registration application has been superseded by a new application and is no longer available",
         "source":{
            "parameter":"{Id}"
         }
      }, 
        {
         "id":"{errorId}",
         "code":"APPLICATION_ALREADY_RETRIEVED",
         "links":{
            "about":"{LINK TO API DOCUMENTATION}"
         },
         "status":"410",
         "title":"Gone",
         "detail":"The registration application has already been retrieved and is no longer available",
         "source":{
            "parameter":"{Id}"
         }
      }
 
   ]
}

➤ Schema


errors:           - Min Items: 1 Max Items: 1
id: string        - Type_ErrorIdentifier
code: enum        - Enum_Error_Gone:
                    Allowed: APPLICATION_EXPIRED
                             APPLICATION_SUPERSEDED
                             APPLICATION_ALREADY_RETRIEVED
status: enum      - Allowed: 410
title: enum       - Allowed: Gone
detail: enum      - Allowed: The registration application has expired and is no longer available
                             The registration application has been superseded by a new application and is no longer available
                             The registration application has already been retrieved and is no longer available
source:           - parameter: {Id}

Error 422 - The ODS code in the request must match that of associated Registration Application

➤ Example

{
   "errors":[
      {
         "id":"{errorId}",
         "code":"UNPROCESSIBLE_ENTITY",
         "links":{
            "about":"{LINK TO API DOCUMENTATION}"
         },
         "status":"422",
         "title":"Unprocessible Entity",
         "detail":"The ODS code does not match the ODS code in the registration application.",
         "source":{
            "parameter":"{Id}"
         }
      }
   ]
}

➤ Schema


errors:           - Min Items: 1 Max Items: 1
id: string        - Type_ErrorIdentifier
code: enum        - Enum_Error_Unprocessible_Entity:
                    Allowed: UNPROCESSIBLE_ENTITY
status: enum      - Allowed: 422
title: enum       - Allowed: Unprocessible Entity
detail: enum      - Allowed: The ODS code does not match the ODS code in the registration application.
source:           - parameter: {Id}

Error 429 - You have made too many requests too quickly, you must send requests at a slower rate.

➤ Example

{
   "errors":[
      {
         "id":"{errorId}",
         "code":"TOO_MANY_REQUESTS",
         "links":{
            "about":"{LINK TO API DOCUMENTATION}"
         },
         "status":"429",
         "title":"Too Many Requests",
         "detail":"You have made too many requests.",
         "source":{
            "parameter":"{Id}"
         }
      }
   ]
}

➤ Schema


errors:           - Min Items: 1 Max Items: 1
id: string        - Type_ErrorIdentifier
code: enum        - Enum_Too_Many_Requests:
                    Allowed: TOO_MANY_REQUESTS
status: enum      - Allowed: 429
title: enum       - Allowed: Too Many Requests
detail: enum      - Allowed: You have made too many requests.
source:           - parameter: {Id}