openapi: "3.0.3" servers: - url: 'https://int.api.service.nhs.uk/gp-registrations-mi' description: Integration Environment - url: 'https://api.service.nhs.uk/gp-registrations-mi' description: Production Environment components: securitySchemes: app-level0: $ref: https://proxygen.prod.api.platform.nhs.uk/components/securitySchemes/app-level0 x-nhsd-apim: temporary: false access: $ref: x-nhsd-apim/access.yaml target: $ref: x-nhsd-apim/target.yaml info: version: 0.0.1 title: GP Registrations Management Information API description: | ## Overview Use this API to send real-time GP registrations metrics to NHS for service monitoring of patient EHR transfers between GP Practices. This API replaces the weekly submission of GP2GP information sent to us via a MESH mailbox, as required by [GP2GP V2.2b](https://gpitbjss.atlassian.net/wiki/spaces/DCSDCS/pages/1391134336/GP2GP). You can send us Management Information for registrations regardless of the transfer protocol used (GP2GP or GP Connect). Using the API, you can send us information about the following: * when a requesting practice completes a registration * the compatibility of that registration with an electronic transfer * when the requesting practice requests an EHR * when the sending practice sends an EHR * when the requesting practice received attachments/documents * when the requesting practice is ready for the user to integrate the transfer * when the requesting practice has integrated the EHR received * when an error, or negative acknowledgement occurs * degrades You cannot: * read any management information data submitted to us ## Who can use this API 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 [GP2GP - HL7 API](https://digital.nhs.uk/developer/api-catalogue/gp2gp) to learn more the GP2GP protocol. Use the following to learn more about the GP Connect protocol: * [GP Connect Access Document - FHIR API](https://digital.nhs.uk/developer/api-catalogue/gp-connect-access-document-fhir) * [GP Connect Access Record: HTML - FHIR API](https://digital.nhs.uk/developer/api-catalogue/gp-connect-access-record-html-fhir) * [GP Connect Access Record: Structured - FHIR API](https://digital.nhs.uk/developer/api-catalogue/gp-connect-access-record-structured-fhir) * [GP Connect Send Document - FHIR API](https://digital.nhs.uk/developer/api-catalogue/gp-connect-send-document-fhir) ## API status and roadmap This API is [in production, beta](https://digital.nhs.uk/developer/guides-and-documentation/reference-guide#statuses). ## Service level This API is a silver service, meaning it is operational 24 hours a day, 365 days a year but only supported during business hours (8am to 6pm), Monday to Friday excluding bank holidays. For more details, see [service levels](https://digital.nhs.uk/developer/guides-and-documentation/reference-guide#service-levels). ## Technology This API uses HTTP POST to submit data. ## Network access This API is available on the internet and, indirectly, on the [Health and Social Care Network (HSCN)](https://digital.nhs.uk/services/health-and-social-care-network). For more details, see [Network access for APIs](https://digital.nhs.uk/developer/guides-and-documentation/network-access-for-apis#internet-only-apis). ## Security and authorisation This API is [application-restricted](https://digital.nhs.uk/developer/guides-and-documentation/security-and-authorisation#application-restricted-apis), meaning we authenticate the calling application but not the end user. To use this access mode, use the following security pattern: * [Application-restricted RESTful APIs - API key authentication](https://digital.nhs.uk/developer/guides-and-documentation/security-and-authorisation/application-restricted-restful-apis-api-key-authentication) ## Environments and testing | Environment | Base URL | | ----------------- | ---------------------------------------------------------------------- | | Integration test | `https://int.api.service.nhs.uk/gp-registrations-mi/` | | Production | `https://api.service.nhs.uk/gp-registrations-mi/` | ### Integration testing Our [integration test environment](https://digital.nhs.uk/developer/guides-and-documentation/testing#integration-testing): * is for formal integration testing or early developer testing * includes authorisation ## 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. As part of this process, you need to demonstrate your technical conformance to the requirements for this API. To understand how our online digital onboarding process works, see [digital onboarding](https://digital.nhs.uk/developer/guides-and-documentation/digital-onboarding).

To get started, sign in or create a developer account, then select 'product onboarding'.

## 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, including code 202 if it was accepted by an API that needs to wait for further action * 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 Errors specific to each API are shown in the Endpoints section, under Response. See our [reference guide](https://digital.nhs.uk/developer/guides-and-documentation/reference-guide#http-status-codes) for more on errors. ## Contact us For help and support connecting to our APIs and to join our developer community, see [Help and support building healthcare software](https://digital.nhs.uk/developer/help-and-support). license: name: MIT contact: email: gp-registrations-data@nhs.net tags: - name: Registration description: Endpoints to submit events for all stages of the patient registration. x-spec-publication: operation-order: - group: Registration operations: - method: POST path: /registrations - method: POST path: /transfer-compatibility-statuses - method: POST path: /ehr-requests - method: POST path: /ehr-responses - method: POST path: /document-responses - method: POST path: /ready-to-integrate-statuses - method: POST path: /ehr-degrades - method: POST path: /ehr-integrations - method: POST path: /errors try-this-api: disabled: true paths: /registrations: post: tags: - Registration summary: Submit Registrations event operationId: registrations description: | This event captures the details of the registration before the electronic transfer is initiated. It includes information about the: - sending practice - status of the PDS trace - type of registration - GPLinks information **Submitted by:** Requesting practice **When to send:** When the user completes the registration. This event should be submitted for every regular patient registration. Including, but not limited to, the following scenarios: - The patient is new to the practice - The patient is returning to the practice, - The patient is already registered as a non-regular patient type (e.g. temporary, private etc) and is changing to a regular patient status (e.g. from temporary to regular patient) - Registrations that will not trigger an electronic transfer of the EHR (e.g. the patient does not have a previous practice, or the previous practice is in Scotland) - Registrations when a PDS trace is not performed **Notes:** If a technical error or negative acknowledgment occurs, an Error event must be submitted, including the response code if applicable. ### Request Body example: ```json { "conversationId": "4345-986959-4930-684038", "registrationEventDateTime": "2020-02-08T08:30:25Z", "reportingSystemSupplier": "SUPPLIER_ODS_CODE", "reportingPracticeOdsCode": "ABC1234", "requestingPracticeOdsCode": "ABC1234", "sendingPracticeOdsCode": "XYZ4567", "payload": { "registration": { "type": "NEW_GP_REGISTRATION", "returningPatient": false, "multifactorAuthenticationPresent": true }, "demographicTraceStatus": { "matched": false, "reason": "no PDS trace results returned", "multifactorAuthenticationPresent": true }, "gpLinks": { "gpLinksComplete": true } } } ``` security: - app-level0: [] requestBody: description: | The request body required for the Registrations event. required: true content: application/json: schema: type: object allOf: - $ref: components/schemas/BaseEventWithOptionalSendingPracticeOdsCode.yaml - type: object required: - payload properties: payload: description: An object that contains the detailed payload of the event. type: object required: - registration - demographicTraceStatus - gpLinks properties: registration: $ref: components/schemas/RegistrationWithAdditionalDetails.yaml demographicTraceStatus: $ref: components/schemas/DemographicTraceStatus.yaml gpLinks: $ref: components/schemas/GPLinks.yaml responses: '200': $ref: components/responses/OK.yaml '400': $ref: components/responses/BadRequest.yaml '500': $ref: components/responses/InternalServerError.yaml /transfer-compatibility-statuses: post: tags: - Registration summary: Submit Transfer Compatibility Statuses operationId: transfer-compatibility-statuses description: | This event captures whether or not the registration is compatible with an electronic transfer of the patient’s record. This event should be submitted for all registrations where a sending (previous) practice ODS code is present. **Submitted by:** Requesting practice **When to send:** When it is determined that an electronic transfer will or will not be triggered. **Notes:** If a technical error or negative acknowledgment occurs, an Error event must be submitted, including the response code if applicable. ### Request Body example: ```json { "conversationId": "4345-986959-4930-684038", "registrationEventDateTime": "2020-02-08T08:30:25Z", "reportingSystemSupplier": "SUPPLIER_ODS_CODE", "reportingPracticeOdsCode": "ABC1234", "requestingPracticeOdsCode": "ABC1234", "sendingPracticeOdsCode": "XYZ4567", "payload": { "transferCompatibilityStatus": { "internalTransfer": false, "transferCompatible": false, "reason": "Previous practice not eligible for transfer" } } } ``` security: - app-level0: [] requestBody: description: | The request body required for the Transfer Compatability Statuses event. required: true content: application/json: schema: type: object allOf: - $ref: components/schemas/BaseEvent.yaml - type: object required: - payload properties: payload: description: An object that contains the detailed payload of the event. type: object required: - transferCompatibilityStatus properties: transferCompatibilityStatus: $ref: components/schemas/TransferCompatibilityStatus.yaml responses: '200': $ref: components/responses/OK.yaml '400': $ref: components/responses/BadRequest.yaml '500': $ref: components/responses/InternalServerError.yaml /ehr-requests: post: tags: - Registration summary: Submit EHR Requests operationId: ehr-requests description: | This event logs when the EHR request has been sent to the sending practice. **Submitted by:** Requesting practice **When to send:** When the EHR request has been sent to the sending practice. **Notes:** If a technical error or negative acknowledgment occurs, an Error event must be submitted, including the response code if applicable. ### Request Body example: ```json { "conversationId": "4345-986959-4930-684038", "registrationEventDateTime": "2020-02-08T08:30:25Z", "reportingSystemSupplier": "SUPPLIER_ODS_CODE", "reportingPracticeOdsCode": "ABC1234", "requestingPracticeOdsCode": "ABC1234", "sendingPracticeOdsCode": "XYZ4567" } ``` security: - app-level0: [] requestBody: description: | The request body required for the EHR Requests event. required: true content: application/json: schema: type: object allOf: - $ref: components/schemas/BaseEvent.yaml responses: '200': $ref: components/responses/OK.yaml '400': $ref: components/responses/BadRequest.yaml '500': $ref: components/responses/InternalServerError.yaml /ehr-responses: post: tags: - Registration summary: Submit EHR Responses operationId: ehr-responses description: | This event logs when a response to the EHR request has been sent. It contains details of the EHR and attachment placeholders. **Submitted by:** Sending practice **When to send:** When the EHR response has been sent by the sending practice. **Notes:** If a technical error or negative acknowledgment occurs, an Error event must be submitted, including the response code if applicable. ### Request Body example: ```json { "conversationId": "4345-986959-4930-684038", "registrationEventDateTime": "2020-02-08T08:30:25Z", "reportingSystemSupplier": "SUPPLIER_ODS_CODE", "reportingPracticeOdsCode": "ABC1234", "requestingPracticeOdsCode": "ABC1234", "sendingPracticeOdsCode": "XYZ4567", "payload": { "ehr": { "ehrStructuredSizeBytes": 4096, "placeholders": [ { "generatedBy": "PRE_EXISTING", "clinicalType": "SCANNED_DOCUMENT", "reason": "FILE_NOT_FOUND", "originalMimeType": "application/pdf" }, { "generatedBy": "SENDER", "clinicalType": "AUDIO_DICTATION", "reason": "FILE_DELETED", "originalMimeType": "audio/mpeg" } ] } } } ``` security: - app-level0: [] requestBody: description: | The request body required for the EHR Responses event. required: true content: application/json: schema: type: object allOf: - $ref: components/schemas/BaseEvent.yaml - type: object required: - payload properties: payload: description: An object that contains the detailed payload of the event. type: object required: - ehr properties: ehr: properties: ehrStructuredSizeBytes: type: integer description: The total size in bytes of structured part of the GP2GP message (attachments are NOT to be included). example: 4956 placeholders: $ref: components/schemas/Placeholder.yaml responses: '200': $ref: components/responses/OK.yaml '400': $ref: components/responses/BadRequest.yaml '500': $ref: components/responses/InternalServerError.yaml /document-responses: post: tags: - Registration summary: Submit Document Responses operationId: document-responses description: | This event records the addition of an attachment to the patient record. **Submitted by:** Requesting practice **When to send:** As each document is processed and saved into the clinical system. For HL7 v3 EHRs, this will be when the attachments are decoded from the message fragments. For FHIR EHRs, this will be when the attachment transfer is complete. **Notes:** If a technical error or negative acknowledgment occurs, an Error event must be submitted, including the response code if applicable. ### Request Body example: ```json { "conversationId": "4345-986959-4930-684038", "registrationEventDateTime": "2020-02-08T08:30:25Z", "reportingSystemSupplier": "SUPPLIER_ODS_CODE", "reportingPracticeOdsCode": "ABC1234", "requestingPracticeOdsCode": "ABC1234", "sendingPracticeOdsCode": "XYZ4567", "payload": { "attachment": { "clinicalType": "SCANNED_DOCUMENT", "mimeType": "application/pdf", "sizeBytes": 3084322 }, "documentMigration": { "successful": false, "reason": "Large file size" } } } ``` security: - app-level0: [] requestBody: description: | The request body required for the Document Responses event. required: true content: application/json: schema: type: object allOf: - $ref: components/schemas/BaseEvent.yaml - type: object required: - payload properties: payload: description: An object that contains the detailed payload of the event. type: object required: - attachment - documentMigration properties: attachment: $ref: components/schemas/Attachment.yaml documentMigration: $ref: components/schemas/DocumentMigration.yaml responses: '200': $ref: components/responses/OK.yaml '400': $ref: components/responses/BadRequest.yaml '500': $ref: components/responses/InternalServerError.yaml /ready-to-integrate-statuses: post: tags: - Registration summary: Submit Ready to Integrate Statuses operationId: /ready-to-integrate-statuses description: | This event logs when the EHR has been received and is awaiting the user in the receiving practice to integrate or reject. **Submitted by:** Requesting practice **When to send:** When the EHR has been received and has been make available for the user in the receiving practice to integrate or reject. **Notes:** If a technical error or negative acknowledgment occurs, an Error event must be submitted, including the response code if applicable. ### Request Body example: ```json { "conversationId": "4345-986959-4930-684038", "registrationEventDateTime": "2020-02-08T08:30:25Z", "reportingSystemSupplier": "SUPPLIER_ODS_CODE", "reportingPracticeOdsCode": "ABC1234", "requestingPracticeOdsCode": "ABC1234", "sendingPracticeOdsCode": "XYZ4567" } ``` security: - app-level0: [] requestBody: description: | The request body required for the Ready to Integrate Statuses event. required: true content: application/json: schema: type: object allOf: - $ref: components/schemas/BaseEvent.yaml responses: '200': $ref: components/responses/OK.yaml '400': $ref: components/responses/BadRequest.yaml '500': $ref: components/responses/InternalServerError.yaml /ehr-degrades: post: tags: - Registration summary: Submit EHR Degrades operationId: ehr-degrades description: | This event gathers information about the degraded data within an EHR once it has been received. The following information **MUST NOT** be sent: - conversationID - registrationEventDateTime - reportingPracticeODSCode - requestingPracticeODSCode - sendingPracticeODSCode **Submitted by:** Requesting practice **When to send:** When the degrades for the EHR have been identified. **Notes:** Submit Errors events **MUST NOT** be sent in relation to degrades. **No information that relates the degrade to a particular transfer may be sent.** ### Request Body example: ```json { "reportingSystemSupplier": "SUPPLIER_ODS_CODE", "payload": { "degrades": [ { "type": "RECORD_ENTRY", "reason": "CODE", "coding": [ { "code": "1676331000000110", "system": "http://snomed.info/sct" } ] } ] } } ``` security: - app-level0: [] requestBody: description: | The request body required for the EHR Degrades event. required: true content: application/json: schema: type: object allOf: - type: object required: - reportingSystemSupplier - payload properties: reportingSystemSupplier: type: string description: The system supplier who generated the event. The ODS code assigned to you as a supplier by NHSD. example: SupplierOdsCode payload: description: An object that contains the detailed payload of the event. type: object required: - degrades properties: degrades: $ref: components/schemas/Degrade.yaml responses: '200': $ref: components/responses/OK.yaml '400': $ref: components/responses/BadRequest.yaml '500': $ref: components/responses/InternalServerError.yaml /ehr-integrations: post: tags: - Registration summary: Submit EHR Integrations operationId: ehr-integrations description: | This event gathers information about the success or failure of the integration of the record into the requesting practice clinical system. **Submitted by:** Requesting practice **When to send:** When the EHR has been integrated by the user at the requesting practice. For HL7 v3 EHRs, this will be when the attachments are decoded from the message fragments. For FHIR EHRs, this will be when the attachment transfer is complete. **Notes:** If a technical error or negative acknowledgment occurs, an Error event must be submitted, including the response code if applicable. ### Request Body example: ```json { "conversationId": "4345-986959-4930-684038", "registrationEventDateTime": "2020-02-08T08:30:25Z", "reportingSystemSupplier": "SUPPLIER_ODS_CODE", "reportingPracticeOdsCode": "ABC1234", "requestingPracticeOdsCode": "ABC1234", "sendingPracticeOdsCode": "XYZ4567", "payload": { "integration": { "outcome": "INTEGRATED" } } } ``` security: - app-level0: [] requestBody: description: | The request body required for the EHR Integrations event. required: true content: application/json: schema: type: object allOf: - $ref: components/schemas/BaseEvent.yaml - type: object required: - payload properties: payload: description: An object that contains the detailed payload of the event. type: object required: - integration properties: integration: $ref: components/schemas/Integration.yaml responses: '200': $ref: components/responses/OK.yaml '400': $ref: components/responses/BadRequest.yaml '500': $ref: components/responses/InternalServerError.yaml /errors: post: tags: - Registration summary: Submit Errors operationId: errors description: | This event gathers information about all errors and events that trigger the sending of a negative acknowledgement that occur during a registration. The error codes referenced should match the values described in [NPFIT-PC-BLD-0083.08 GP2GP Response Codes.pdf](https://gpitbjss.atlassian.net/wiki/download/attachments/12665978882/NPFIT-PC-BLD-0083.08%20GP2GP%20Response%20Codes.pdf?version=1&modificationDate=1703173853480&cacheVersion=1&api=v2) which is found on [GP2GP v6.0.0](https://gpitbjss.atlassian.net/wiki/spaces/DCSDCS/pages/12665978882/GP2GP+v6.0.0). This is used to understand errors and prioritise their resolution to support the successful transfer of patient EHRs. **Submitted by:** Requesting practice or Sending practice, whichever encounters the issue **When to send:** When an issue occurs that prevents the successful processing of the patient EHR (or a component of the EHR) then this endpoint should be called. **Notes:** All negative acknowledgement defined in the specification must be reported as errors. However, this endpoint is not limited to negative acknowledgements. Anytime a technical error occurs that prevents the transfers from starting or completing, this must be reported using this endpoint. Error events **MUST NOT** be submitted for failures or errors relating to Degrades. ### Request Body example: ```json { "conversationId": "4345-986959-4930-684038", "registrationEventDateTime": "2020-02-08T08:30:26Z", "reportingSystemSupplier": "SUPPLIER_ODS_CODE", "reportingPracticeOdsCode": "ABC1234", "requestingPracticeOdsCode": "ABC1234", "sendingPracticeOdsCode": "XYZ4567", "payload": { "error": { "errorCode": "99", "errorDescription": "unexpected error", "failurePoint": "EHR_RESPONSE" } } } ``` security: - app-level0: [] requestBody: description: | The request body required for the Errors event. required: true content: application/json: schema: type: object allOf: - $ref: components/schemas/BaseEventWithOptionalSendingPracticeOdsCode.yaml - type: object required: - payload properties: payload: description: An object that contains the detailed payload of the event. type: object required: - error properties: error: $ref: components/schemas/Error.yaml responses: '200': $ref: components/responses/OK.yaml '400': $ref: components/responses/BadRequest.yaml '500': $ref: components/responses/InternalServerError.yaml