Skip to main content

GP Registrations Management Information API

Send real-time management information about GP registrations to us at NHS Digital.

Overview

Use this API to send real-time management information about GP registrations to us at NHS Digital.

  • You can send us Management Information using the Pre-transfer API.
  • If your practice uses the GP2GP protocol you can send us Management Information using the GP2GP API.
  • If your practice uses the GP Connect protocol you can send us Management Information using the GP Connect API.

Pre-transfer

Before a patient record transfer is in progress you can send us information about the following type of events:

  • when the requesting practice starts the GP2GP registration - the first message initiated as part of the GP2GP or GP Connect protocol
  • when a patient is being registered and a practice searches for and selects the patient from PDS
  • when the SDS lookup is performed to identify whether the previous practice is GP2GP or GP Connect compatible
  • when PDS has been updated with the new practice information

GP2GP

Using this protocol you can send us information about the following type of events:

  • when the sending practice generates the electronic health record
  • when the requesting practice requests an EHR
  • when the sending practice sends an EHR
  • when the requesting practice validates an EHR
  • when the requesting practice integrates an EHR
  • when an error occurs

This API replaces the weekly submission of GP2GP information sent to us via a MESH mailbox, as required by GP2GP V2.2b.

GP Connect

Using this protocol you can send us information about the following type of events:

  • when the request is sent to migrate the structured record
  • when the response has been received from migrating the structured record
  • when a request is sent to migrate a document
  • when a response has been received from migrating a document
  • when the EHR is ready to integrate
  • when the EHR has been integrated
  • when an internal transfer of an EHR has been completed between two GP practices using the same software supplier system
  • when an error occurs

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


Use GP2GP - HL7 API to learn more the GP2GP protocol.

Use the following to learn more about the GP Connect protocol:


API status and roadmap

This API is in alpha, meaning:

  • it is available for testing in the integration environment, but not for production use
  • we might make breaking changes, but only if we cannot avoid it, and we will give advance notice

Roadmap

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.


Service level

This plan is for this API to be a silver service, meaning it is operational 24 x 7 x 365 but only supported during business hours (8am to 6pm), Monday to Friday excluding bank holidays.

For more details, see 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).

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 access mode, use the following security pattern:


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:

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

Contact gp-registrations-data@nhs.net to onboard.


Endpoints: Pre-transfer

Submit Registration Started event

post /preTransfer/registrationStarted

Use this endpoint to submit GP registration management information for when a registration is started.

Request Body example:

Request

Headers
Name Description
apikey

String

API key to authenticate with.

Required
Body
Required

Content type: application/json

Schema

Name Description
object
allOf
object
eventId
string uuid
required

Unique identifier for this event

Max length: 16
Min length: 16
eventGeneratedDateTime
string date-time
required

The ISO 8601 Date time in UTC of when this MI event was generated by the system

Example: 2020-02-08T09:30:26Z
reportingSystemSupplier
string
required

The system supplier who generated the event. A unique identifier given to you as a supplier by NHSD

Example: supplierOne
reportingPracticeOdsCode
string
required

The ODS code of the practice generating this event

Example: ABC1234
conversationId
string

The ConversationID used in the GP2GP process for this registration

Example: 4345-9869-4930-6840
transferEventDateTime
string date-time

The ISO 8601 Date time in UTC that this patient transfer event occurred

Example: 2020-02-08T08:30:27Z
object
payload
object
required

An object that contains the detailed payload of the event

registration
object
required

An object that contains information about the registration process

registrationType
string
required

The type of this registration (newRegistrant, etc...)

Example: newRegistrant
registrationStartedDateTime
string
required

The ISO 8601 Date time in UTC of when the registration started

Example: 2020-02-08T08:30:26+00:00
requestingPracticeOdsCode
string
required

The ODS code of the practice requesting the EHR

Example: ABC1234

Response

HTTP status: 200

OK. Expected response to a valid request

Body

Content type: application/json

Example

Schema

Name Description
object
Example:
{
  "eventId" : "1234-1234-1234-1234"
}
eventId
string
Example: 1234-1234-1234-1234
HTTP status: 400

Bad request

Body

Content type: application/json

Example

Schema

Name Description
object
Example:
{
  "status" : "BAD_REQUEST",
  "message" : "Failed to validate fields",
  "errors" : [ "reportingPracticeOdsCode must not be empty" ]
}
status
string
required
Example: BAD_REQUEST
message
string
required
Example: Failed to validate fields
errors
array
required
string
Example: reportingPracticeOdsCode must not be empty
HTTP status: 500

Internal Server Error

Body

Content type: application/json

Example

Schema

Name Description
object
Example:
{
  "status" : "INTERNAL_SERVER_ERROR",
  "message" : "Something went wrong",
  "errors" : [ "aws is down" ]
}
status
string
required
Example: INTERNAL_SERVER_ERROR
message
string
required
Example: Something went wrong
errors
array
required
string

Submit PDS Trace event

post /preTransfer/pdsTrace

When a patient is being registered, the new practice performs a search in PDS to find the patient that matches their personal information. This event should be sent when the practice has selected a match

Request Body example:

Request

Headers
Name Description
apikey

String

API key to authenticate with.

Required
Body
Required

Content type: application/json

Schema

Name Description
object
allOf
object
eventId
string uuid
required

Unique identifier for this event

Max length: 16
Min length: 16
eventGeneratedDateTime
string date-time
required

The ISO 8601 Date time in UTC of when this MI event was generated by the system

Example: 2020-02-08T09:30:26Z
reportingSystemSupplier
string
required

The system supplier who generated the event. A unique identifier given to you as a supplier by NHSD

Example: supplierOne
reportingPracticeOdsCode
string
required

The ODS code of the practice generating this event

Example: ABC1234
conversationId
string

The ConversationID used in the GP2GP process for this registration

Example: 4345-9869-4930-6840
transferEventDateTime
string date-time

The ISO 8601 Date time in UTC that this patient transfer event occurred

Example: 2020-02-08T08:30:27Z
object
payload
object
required

An object that contains the detailed payload of the event

smartcardPresent
boolean
required

Denotes whether a smartcard has been used to perform the PDS trace

Example: true
demographicTraceStatus
object
required
status
string
required

The status

Allowed values: SUCCESS, FAILURE
reason
string

The reason for the status

Example: Could not retrieve record

Response

HTTP status: 200

OK. Expected response to a valid request

Body

Content type: application/json

Example

Schema

Name Description
object
Example:
{
  "eventId" : "1234-1234-1234-1234"
}
eventId
string
Example: 1234-1234-1234-1234
HTTP status: 400

Bad request

Body

Content type: application/json

Example

Schema

Name Description
object
Example:
{
  "status" : "BAD_REQUEST",
  "message" : "Failed to validate fields",
  "errors" : [ "reportingPracticeOdsCode must not be empty" ]
}
status
string
required
Example: BAD_REQUEST
message
string
required
Example: Failed to validate fields
errors
array
required
string
Example: reportingPracticeOdsCode must not be empty
HTTP status: 500

Internal Server Error

Body

Content type: application/json

Example

Schema

Name Description
object
Example:
{
  "status" : "INTERNAL_SERVER_ERROR",
  "message" : "Something went wrong",
  "errors" : [ "aws is down" ]
}
status
string
required
Example: INTERNAL_SERVER_ERROR
message
string
required
Example: Something went wrong
errors
array
required
string

Submit SDS Lookup event

post /preTransfer/sdsLookup

Once the PDS trace has happened, an SDS lookup is performed to identify whether the previous practice is GP2GP compatible. This event should be triggered once the SDS lookup is done

Request Body example:

Request

Headers
Name Description
apikey

String

API key to authenticate with.

Required
Body
Required

Content type: application/json

Schema

Name Description
object
allOf
object
eventId
string uuid
required

Unique identifier for this event

Max length: 16
Min length: 16
eventGeneratedDateTime
string date-time
required

The ISO 8601 Date time in UTC of when this MI event was generated by the system

Example: 2020-02-08T09:30:26Z
reportingSystemSupplier
string
required

The system supplier who generated the event. A unique identifier given to you as a supplier by NHSD

Example: supplierOne
reportingPracticeOdsCode
string
required

The ODS code of the practice generating this event

Example: ABC1234
conversationId
string

The ConversationID used in the GP2GP process for this registration

Example: 4345-9869-4930-6840
transferEventDateTime
string date-time

The ISO 8601 Date time in UTC that this patient transfer event occurred

Example: 2020-02-08T08:30:27Z
object
payload
object
required

An object that contains the detailed payload of the event

transferCompatibilityStatus
object
required
status
string
required

The status

Allowed values: SUCCESS, FAILURE
reason
string

The reason for the status

Example: Could not retrieve record

Response

HTTP status: 200

OK. Expected response to a valid request

Body

Content type: application/json

Example

Schema

Name Description
object
Example:
{
  "eventId" : "1234-1234-1234-1234"
}
eventId
string
Example: 1234-1234-1234-1234
HTTP status: 400

Bad request

Body

Content type: application/json

Example

Schema

Name Description
object
Example:
{
  "status" : "BAD_REQUEST",
  "message" : "Failed to validate fields",
  "errors" : [ "reportingPracticeOdsCode must not be empty" ]
}
status
string
required
Example: BAD_REQUEST
message
string
required
Example: Failed to validate fields
errors
array
required
string
Example: reportingPracticeOdsCode must not be empty
HTTP status: 500

Internal Server Error

Body

Content type: application/json

Example

Schema

Name Description
object
Example:
{
  "status" : "INTERNAL_SERVER_ERROR",
  "message" : "Something went wrong",
  "errors" : [ "aws is down" ]
}
status
string
required
Example: INTERNAL_SERVER_ERROR
message
string
required
Example: Something went wrong
errors
array
required
string

Submit PDS General Update event

post /preTransfer/pdsGeneralUpdate

Once a patient is found and linked, PDS should be updated to the new practice’s information. This event should be sent once the the update has been triggered

Request Body example:

Request

Headers
Name Description
apikey

String

API key to authenticate with.

Required
Body
Required

Content type: application/json

Schema

Name Description
object
allOf
object
eventId
string uuid
required

Unique identifier for this event

Max length: 16
Min length: 16
eventGeneratedDateTime
string date-time
required

The ISO 8601 Date time in UTC of when this MI event was generated by the system

Example: 2020-02-08T09:30:26Z
reportingSystemSupplier
string
required

The system supplier who generated the event. A unique identifier given to you as a supplier by NHSD

Example: supplierOne
reportingPracticeOdsCode
string
required

The ODS code of the practice generating this event

Example: ABC1234
conversationId
string

The ConversationID used in the GP2GP process for this registration

Example: 4345-9869-4930-6840
transferEventDateTime
string date-time

The ISO 8601 Date time in UTC that this patient transfer event occurred

Example: 2020-02-08T08:30:27Z
object
payload
object
required

An object that contains the detailed payload of the event

demographicTraceStatus
object
required
status
string
required

The status

Allowed values: SUCCESS, FAILURE
reason
string

The reason for the status

Example: Could not retrieve record

Response

HTTP status: 200

OK. Expected response to a valid request

Body

Content type: application/json

Example

Schema

Name Description
object
Example:
{
  "eventId" : "1234-1234-1234-1234"
}
eventId
string
Example: 1234-1234-1234-1234
HTTP status: 400

Bad request

Body

Content type: application/json

Example

Schema

Name Description
object
Example:
{
  "status" : "BAD_REQUEST",
  "message" : "Failed to validate fields",
  "errors" : [ "reportingPracticeOdsCode must not be empty" ]
}
status
string
required
Example: BAD_REQUEST
message
string
required
Example: Failed to validate fields
errors
array
required
string
Example: reportingPracticeOdsCode must not be empty
HTTP status: 500

Internal Server Error

Body

Content type: application/json

Example

Schema

Name Description
object
Example:
{
  "status" : "INTERNAL_SERVER_ERROR",
  "message" : "Something went wrong",
  "errors" : [ "aws is down" ]
}
status
string
required
Example: INTERNAL_SERVER_ERROR
message
string
required
Example: Something went wrong
errors
array
required
string

Endpoints: GP2GP

Submit EHR Requested event

post /gp2gp/ehrRequested

Use this endpoint to submit GP registration management information for when an Electronic Health Record (EHR) is requested:

Request Body example:

Request

Headers
Name Description
apikey

String

API key to authenticate with.

Required
Body
Required

Content type: application/json

Schema

Name Description
object
allOf
object
eventId
string uuid
required

Unique identifier for this event

Max length: 16
Min length: 16
eventGeneratedDateTime
string date-time
required

The ISO 8601 Date time in UTC of when this MI event was generated by the system

Example: 2020-02-08T09:30:26Z
reportingSystemSupplier
string
required

The system supplier who generated the event. A unique identifier given to you as a supplier by NHSD

Example: supplierOne
reportingPracticeOdsCode
string
required

The ODS code of the practice generating this event

Example: ABC1234
conversationId
string

The ConversationID used in the GP2GP process for this registration

Example: 4345-9869-4930-6840
transferEventDateTime
string date-time

The ISO 8601 Date time in UTC that this patient transfer event occurred

Example: 2020-02-08T08:30:27Z
object
payload
object
required

An object that contains the detailed payload of the event

registration
object
requestingPracticeOdsCode
string
required

The ODS code of the practice requesting the EHR

Example: ABC1234
sendingPracticeOdsCode
string
required

The ODS code of the practice sending the EHR

Example: XYZ4567

Response

HTTP status: 200

OK. Expected response to a valid request

Body

Content type: application/json

Example

Schema

Name Description
object
Example:
{
  "eventId" : "1234-1234-1234-1234"
}
eventId
string
Example: 1234-1234-1234-1234
HTTP status: 400

Bad request

Body

Content type: application/json

Example

Schema

Name Description
object
Example:
{
  "status" : "BAD_REQUEST",
  "message" : "Failed to validate fields",
  "errors" : [ "reportingPracticeOdsCode must not be empty" ]
}
status
string
required
Example: BAD_REQUEST
message
string
required
Example: Failed to validate fields
errors
array
required
string
Example: reportingPracticeOdsCode must not be empty
HTTP status: 500

Internal Server Error

Body

Content type: application/json

Example

Schema

Name Description
object
Example:
{
  "status" : "INTERNAL_SERVER_ERROR",
  "message" : "Something went wrong",
  "errors" : [ "aws is down" ]
}
status
string
required
Example: INTERNAL_SERVER_ERROR
message
string
required
Example: Something went wrong
errors
array
required
string

Submit EHR Generated event

post /gp2gp/ehrGenerated

Use this endpoint to submit GP registration management information for when an Electronic Health Record (EHR) is generated.

Request Body example:

Request

Headers
Name Description
apikey

String

API key to authenticate with.

Required
Body
Required

Content type: application/json

Schema

Name Description
object
allOf
object
eventId
string uuid
required

Unique identifier for this event

Max length: 16
Min length: 16
eventGeneratedDateTime
string date-time
required

The ISO 8601 Date time in UTC of when this MI event was generated by the system

Example: 2020-02-08T09:30:26Z
reportingSystemSupplier
string
required

The system supplier who generated the event. A unique identifier given to you as a supplier by NHSD

Example: supplierOne
reportingPracticeOdsCode
string
required

The ODS code of the practice generating this event

Example: ABC1234
conversationId
string

The ConversationID used in the GP2GP process for this registration

Example: 4345-9869-4930-6840
transferEventDateTime
string date-time

The ISO 8601 Date time in UTC that this patient transfer event occurred

Example: 2020-02-08T08:30:27Z
object
payload
object
required

An object that contains the detailed payload of the event

registration
object
requestingPracticeOdsCode
string
required

The ODS code of the practice requesting the EHR

Example: ABC1234
sendingPracticeOdsCode
string
required

The ODS code of the practice sending the EHR

Example: XYZ4567
ehr
ehrTotalSizeBytes
integer

The total size in bytes of the GP2GP message BEFORE it is split for transfer including all attachments

Example: 5699433
ehrStructuredSizeBytes
integer

The total size in bytes of structured part of the GP2GP message (attachments are NOT to be included)

Example: 4096
attachment
array

A list that contains information about ALL the attachments contained in the EHR. This should include all attachments that are either directly attached OR that are linked to from within the EHR

object
attachmentId
string
required

A unique id for the attachment that can be resolved in the clinical system

Example: 3424-342456-3424-342456
clinicalType
string

The text value corresponding to the value used in EhrAttachmentCode in the code element of ExternalDocument as defined in the MIM

Example: Scanned document
mimeType
string
required

The mime type of the attachment as used as part of the text element in ExternalDocument as defined in the MIM

Example: application/pdf
sizeBytes
integer
required

The size in bytes of the attachment

Example: 3084322
placeholder
array

A list that contains information about the attachments that were in the EHR but not contained in the GP2GP message

object
placeholderId
string
required

A unique id for the placeholder that can be resolved in the clinical system

Example: 9876-987654-9876-987654
attachmentId
string
required

A reference to the attachment that the placeholder replaces (should be contained in the list of attachments)

Example: 1323-132345-1323-132345
generatedBy
string
required

The ODS code of the practice that generated the placeholder

Example: XYZ4567
reason
integer
required

The reason the placeholder was generated. These codes should match the values described in NPFIT-PC-BLD-0099.04 GP2GP Handling Missing Attachments

Example: 1
originalMimeType
string
required

The original mime type of the attachment this placeholder is for

Example: audio/mpeg
unsupportedDataItem
array
object
type
string
required

The type/category of the unsupported data item

Example: allergy/flag
uniqueIdentifier
string
required

A unique id for the unsupported data item that can be resolved in the clinical system

Example: 1323-132345-1323-132345
reason
string
required

The reason for being unsupported / why is it unsupported in gp2gp? / what would have to change in gp2gp to express this?

Example: Doesn't map properly

Response

HTTP status: 200

OK. Expected response to a valid request

Body

Content type: application/json

Example

Schema

Name Description
object
Example:
{
  "eventId" : "1234-1234-1234-1234"
}
eventId
string
Example: 1234-1234-1234-1234
HTTP status: 400

Bad request

Body

Content type: application/json

Example

Schema

Name Description
object
Example:
{
  "status" : "BAD_REQUEST",
  "message" : "Failed to validate fields",
  "errors" : [ "reportingPracticeOdsCode must not be empty" ]
}
status
string
required
Example: BAD_REQUEST
message
string
required
Example: Failed to validate fields
errors
array
required
string
Example: reportingPracticeOdsCode must not be empty
HTTP status: 500

Internal Server Error

Body

Content type: application/json

Example

Schema

Name Description
object
Example:
{
  "status" : "INTERNAL_SERVER_ERROR",
  "message" : "Something went wrong",
  "errors" : [ "aws is down" ]
}
status
string
required
Example: INTERNAL_SERVER_ERROR
message
string
required
Example: Something went wrong
errors
array
required
string

Submit EHR Sent event

post /gp2gp/ehrSent

Use this endpoint to submit GP registration management information for when an Electronic Health Record (EHR) is sent.

Request Body example:

Request

Headers
Name Description
apikey

String

API key to authenticate with.

Required
Body
Required

Content type: application/json

Schema

Name Description
object
allOf
object
eventId
string uuid
required

Unique identifier for this event

Max length: 16
Min length: 16
eventGeneratedDateTime
string date-time
required

The ISO 8601 Date time in UTC of when this MI event was generated by the system

Example: 2020-02-08T09:30:26Z
reportingSystemSupplier
string
required

The system supplier who generated the event. A unique identifier given to you as a supplier by NHSD

Example: supplierOne
reportingPracticeOdsCode
string
required

The ODS code of the practice generating this event

Example: ABC1234
conversationId
string

The ConversationID used in the GP2GP process for this registration

Example: 4345-9869-4930-6840
transferEventDateTime
string date-time

The ISO 8601 Date time in UTC that this patient transfer event occurred

Example: 2020-02-08T08:30:27Z
object
payload
object
required

An object that contains the detailed payload of the event

registration
object
requestingPracticeOdsCode
string
required

The ODS code of the practice requesting the EHR

Example: ABC1234
sendingPracticeOdsCode
string
required

The ODS code of the practice sending the EHR

Example: XYZ4567

Response

HTTP status: 200

OK. Expected response to a valid request

Body

Content type: application/json

Example

Schema

Name Description
object
Example:
{
  "eventId" : "1234-1234-1234-1234"
}
eventId
string
Example: 1234-1234-1234-1234
HTTP status: 400

Bad request

Body

Content type: application/json

Example

Schema

Name Description
object
Example:
{
  "status" : "BAD_REQUEST",
  "message" : "Failed to validate fields",
  "errors" : [ "reportingPracticeOdsCode must not be empty" ]
}
status
string
required
Example: BAD_REQUEST
message
string
required
Example: Failed to validate fields
errors
array
required
string
Example: reportingPracticeOdsCode must not be empty
HTTP status: 500

Internal Server Error

Body

Content type: application/json

Example

Schema

Name Description
object
Example:
{
  "status" : "INTERNAL_SERVER_ERROR",
  "message" : "Something went wrong",
  "errors" : [ "aws is down" ]
}
status
string
required
Example: INTERNAL_SERVER_ERROR
message
string
required
Example: Something went wrong
errors
array
required
string

Submit EHR Validated event

post /gp2gp/ehrValidated

Use this endpoint to submit GP registration management information for when an Electronic Health Record (EHR) is validated.

Request Body example:

Request

Headers
Name Description
apikey

String

API key to authenticate with.

Required
Body
Required

Content type: application/json

Schema

Name Description
object
allOf
object
eventId
string uuid
required

Unique identifier for this event

Max length: 16
Min length: 16
eventGeneratedDateTime
string date-time
required

The ISO 8601 Date time in UTC of when this MI event was generated by the system

Example: 2020-02-08T09:30:26Z
reportingSystemSupplier
string
required

The system supplier who generated the event. A unique identifier given to you as a supplier by NHSD

Example: supplierOne
reportingPracticeOdsCode
string
required

The ODS code of the practice generating this event

Example: ABC1234
conversationId
string

The ConversationID used in the GP2GP process for this registration

Example: 4345-9869-4930-6840
transferEventDateTime
string date-time

The ISO 8601 Date time in UTC that this patient transfer event occurred

Example: 2020-02-08T08:30:27Z
object
payload
object
required

An object that contains the detailed payload of the event

registration
object
requestingPracticeOdsCode
string
required

The ODS code of the practice requesting the EHR

Example: ABC1234
sendingPracticeOdsCode
string
required

The ODS code of the practice sending the EHR

Example: XYZ4567
ehr
ehrTotalSizeBytes
integer

The total size in bytes of the GP2GP message as reconstituted by the receiving system including all attachments received

Example: 5699433
ehrStructuredSizeBytes
integer

The total size in bytes of structured part of the GP2GP message as received by the receiving system (attachments are NOT to be included)

Example: 4096
attachment
array

A list that contains information about ALL the attachments contained in the EHR. This should include all attachments that are either directly attached OR that are linked to from within the EHR

object
attachmentId
string
required

A unique id for the attachment that can be resolved in the clinical system

Example: 3424-342456-3424-342456
clinicalType
string

The text value corresponding to the value used in EhrAttachmentCode in the code element of ExternalDocument as defined in the MIM

Example: Scanned document
mimeType
string
required

The mime type of the attachment as used as part of the text element in ExternalDocument as defined in the MIM

Example: application/pdf
sizeBytes
integer
required

The size in bytes of the attachment

Example: 3084322
placeholder
array

A list that contains information about the attachments that were in the EHR but not contained in the GP2GP message

object
placeholderId
string
required

A unique id for the placeholder that can be resolved in the clinical system

Example: 9876-987654-9876-987654
attachmentId
string
required

A reference to the attachment that the placeholder replaces (should be contained in the list of attachments)

Example: 1323-132345-1323-132345
generatedBy
string
required

The ODS code of the practice that generated the placeholder

Example: XYZ4567
reason
integer
required

The reason the placeholder was generated. These codes should match the values described in NPFIT-PC-BLD-0099.04 GP2GP Handling Missing Attachments

Example: 1
originalMimeType
string
required

The original mime type of the attachment this placeholder is for

Example: audio/mpeg
degrade
array

A list that contains information about ALL the degrades contained in the EHR that occurred due to the gp2gp transfer

object
type
string
required

The type/category of this degrade

Example: core_ehr / attachment
metadata
string
required

Any additional metadata that provides valuable intel on this degrade

Example: other degrades metadata
code
object
required
coding
array
required
code
string
required

The designated code for this particular degrade

Example: 886721000000107
system
string
required

The system in which this degrade occurred

Example: http://snomed.info/sct

Response

HTTP status: 200

OK. Expected response to a valid request

Body

Content type: application/json

Example

Schema

Name Description
object
Example:
{
  "eventId" : "1234-1234-1234-1234"
}
eventId
string
Example: 1234-1234-1234-1234
HTTP status: 400

Bad request

Body

Content type: application/json

Example

Schema

Name Description
object
Example:
{
  "status" : "BAD_REQUEST",
  "message" : "Failed to validate fields",
  "errors" : [ "reportingPracticeOdsCode must not be empty" ]
}
status
string
required
Example: BAD_REQUEST
message
string
required
Example: Failed to validate fields
errors
array
required
string
Example: reportingPracticeOdsCode must not be empty
HTTP status: 500

Internal Server Error

Body

Content type: application/json

Example

Schema

Name Description
object
Example:
{
  "status" : "INTERNAL_SERVER_ERROR",
  "message" : "Something went wrong",
  "errors" : [ "aws is down" ]
}
status
string
required
Example: INTERNAL_SERVER_ERROR
message
string
required
Example: Something went wrong
errors
array
required
string

Submit EHR Integrated event

post /gp2gp/ehrIntegrated

Use this endpoint to submit GP registration management information for when an Electronic Health Record (EHR) is integrated.

Request Body example:

Request

Headers
Name Description
apikey

String

API key to authenticate with.

Required
Body
Required

Content type: application/json

Schema

Name Description
object
allOf
object
eventId
string uuid
required

Unique identifier for this event

Max length: 16
Min length: 16
eventGeneratedDateTime
string date-time
required

The ISO 8601 Date time in UTC of when this MI event was generated by the system

Example: 2020-02-08T09:30:26Z
reportingSystemSupplier
string
required

The system supplier who generated the event. A unique identifier given to you as a supplier by NHSD

Example: supplierOne
reportingPracticeOdsCode
string
required

The ODS code of the practice generating this event

Example: ABC1234
conversationId
string

The ConversationID used in the GP2GP process for this registration

Example: 4345-9869-4930-6840
transferEventDateTime
string date-time

The ISO 8601 Date time in UTC that this patient transfer event occurred

Example: 2020-02-08T08:30:27Z
object
payload
object
required

An object that contains the detailed payload of the event

registration
object
requestingPracticeOdsCode
string
required

The ODS code of the practice requesting the EHR

Example: ABC1234
sendingPracticeOdsCode
string
required

The ODS code of the practice sending the EHR

Example: XYZ4567
integration
object
integrationStatus
string
required

The status of this integration, (filed as attachment/ suppressed/ merged/ rejected)

Allowed values: FILED_AS_ATTACHMENT, SUPPRESSED, MERGED, REJECTED
reason
string

The reason for this integration status

Example: Could not find EHR

Response

HTTP status: 200

OK. Expected response to a valid request

Body

Content type: application/json

Example

Schema

Name Description
object
Example:
{
  "eventId" : "1234-1234-1234-1234"
}
eventId
string
Example: 1234-1234-1234-1234
HTTP status: 400

Bad request

Body

Content type: application/json

Example

Schema

Name Description
object
Example:
{
  "status" : "BAD_REQUEST",
  "message" : "Failed to validate fields",
  "errors" : [ "reportingPracticeOdsCode must not be empty" ]
}
status
string
required
Example: BAD_REQUEST
message
string
required
Example: Failed to validate fields
errors
array
required
string
Example: reportingPracticeOdsCode must not be empty
HTTP status: 500

Internal Server Error

Body

Content type: application/json

Example

Schema

Name Description
object
Example:
{
  "status" : "INTERNAL_SERVER_ERROR",
  "message" : "Something went wrong",
  "errors" : [ "aws is down" ]
}
status
string
required
Example: INTERNAL_SERVER_ERROR
message
string
required
Example: Something went wrong
errors
array
required
string

Submit Error event

post /gp2gp/error

Use this endpoint to submit GP registration management information immediately after an error has occurred, or has been detected by the Supplier System.

Request Body example:

Request

Headers
Name Description
apikey

String

API key to authenticate with.

Required
Body
Required

Content type: application/json

Schema

Name Description
object
allOf
object
eventId
string uuid
required

Unique identifier for this event

Max length: 16
Min length: 16
eventGeneratedDateTime
string date-time
required

The ISO 8601 Date time in UTC of when this MI event was generated by the system

Example: 2020-02-08T09:30:26Z
reportingSystemSupplier
string
required

The system supplier who generated the event. A unique identifier given to you as a supplier by NHSD

Example: supplierOne
reportingPracticeOdsCode
string
required

The ODS code of the practice generating this event

Example: ABC1234
conversationId
string

The ConversationID used in the GP2GP process for this registration

Example: 4345-9869-4930-6840
transferEventDateTime
string date-time

The ISO 8601 Date time in UTC that this patient transfer event occurred

Example: 2020-02-08T08:30:27Z
object
payload
object
required

An object that contains the detailed payload of the event

registration
object
requestingPracticeOdsCode
string
required

The ODS code of the practice requesting the EHR

Example: ABC1234
sendingPracticeOdsCode
string
required

The ODS code of the practice sending the EHR

Example: XYZ4567
error
object
errorCode
string
required

The error code associated with this error

Example: FD34
errorDescription
string
required

The description of the error that has occurred

Example: Could not connect to sending practice

Response

HTTP status: 200

OK. Expected response to a valid request

Body

Content type: application/json

Example

Schema

Name Description
object
Example:
{
  "eventId" : "1234-1234-1234-1234"
}
eventId
string
Example: 1234-1234-1234-1234
HTTP status: 400

Bad request

Body

Content type: application/json

Example

Schema

Name Description
object
Example:
{
  "status" : "BAD_REQUEST",
  "message" : "Failed to validate fields",
  "errors" : [ "reportingPracticeOdsCode must not be empty" ]
}
status
string
required
Example: BAD_REQUEST
message
string
required
Example: Failed to validate fields
errors
array
required
string
Example: reportingPracticeOdsCode must not be empty
HTTP status: 500

Internal Server Error

Body

Content type: application/json

Example

Schema

Name Description
object
Example:
{
  "status" : "INTERNAL_SERVER_ERROR",
  "message" : "Something went wrong",
  "errors" : [ "aws is down" ]
}
status
string
required
Example: INTERNAL_SERVER_ERROR
message
string
required
Example: Something went wrong
errors
array
required
string

Endpoints: GP Connect

Submit Migrate Structured Record Request event

post /gpconnect/migrateStructuredRecordRequest

Use this endpoint to submit GP registration management information immediately after the Requesting System will make a request via GP Connect using the ‘Migrate Structured Record’ end point using the previous Health Care Provider code that was cached

Request Body example:

Request

Headers
Name Description
apikey

String

API key to authenticate with.

Required
Body
Required

Content type: application/json

Schema

Name Description
object
allOf
object
eventId
string uuid
required

Unique identifier for this event

Max length: 16
Min length: 16
eventGeneratedDateTime
string date-time
required

The ISO 8601 Date time in UTC of when this MI event was generated by the system

Example: 2020-02-08T09:30:26Z
reportingSystemSupplier
string
required

The system supplier who generated the event. A unique identifier given to you as a supplier by NHSD

Example: supplierOne
reportingPracticeOdsCode
string
required

The ODS code of the practice generating this event

Example: ABC1234
conversationId
string

The ConversationID used in the GP2GP process for this registration

Example: 4345-9869-4930-6840
transferEventDateTime
string date-time

The ISO 8601 Date time in UTC that this patient transfer event occurred

Example: 2020-02-08T08:30:27Z
object
payload
object
required

An object that contains the detailed payload of the event

registration
object
requestingPracticeOdsCode
string
required

The ODS code of the practice requesting the EHR

Example: ABC1234
sendingPracticeOdsCode
string
required

The ODS code of the practice sending the EHR

Example: XYZ4567

Response

HTTP status: 200

OK. Expected response to a valid request

Body

Content type: application/json

Example

Schema

Name Description
object
Example:
{
  "eventId" : "1234-1234-1234-1234"
}
eventId
string
Example: 1234-1234-1234-1234
HTTP status: 400

Bad request

Body

Content type: application/json

Example

Schema

Name Description
object
Example:
{
  "status" : "BAD_REQUEST",
  "message" : "Failed to validate fields",
  "errors" : [ "reportingPracticeOdsCode must not be empty" ]
}
status
string
required
Example: BAD_REQUEST
message
string
required
Example: Failed to validate fields
errors
array
required
string
Example: reportingPracticeOdsCode must not be empty
HTTP status: 500

Internal Server Error

Body

Content type: application/json

Example

Schema

Name Description
object
Example:
{
  "status" : "INTERNAL_SERVER_ERROR",
  "message" : "Something went wrong",
  "errors" : [ "aws is down" ]
}
status
string
required
Example: INTERNAL_SERVER_ERROR
message
string
required
Example: Something went wrong
errors
array
required
string

Submit Migrate Structured Record Response event

post /gpconnect/migrateStructuredRecordResponse

Use this endpoint to submit GP registration management information immediately after the Requesting System has received a response from the request made via GP Connect using the ‘Migrate Structured Record’ end point. In a happy-path scenario, the response should contain the "Migrate Patient Record Bundle"

Request Body example:

Request

Headers
Name Description
apikey

String

API key to authenticate with.

Required
Body
Required

Content type: application/json

Schema

Name Description
object
allOf
object
eventId
string uuid
required

Unique identifier for this event

Max length: 16
Min length: 16
eventGeneratedDateTime
string date-time
required

The ISO 8601 Date time in UTC of when this MI event was generated by the system

Example: 2020-02-08T09:30:26Z
reportingSystemSupplier
string
required

The system supplier who generated the event. A unique identifier given to you as a supplier by NHSD

Example: supplierOne
reportingPracticeOdsCode
string
required

The ODS code of the practice generating this event

Example: ABC1234
conversationId
string

The ConversationID used in the GP2GP process for this registration

Example: 4345-9869-4930-6840
transferEventDateTime
string date-time

The ISO 8601 Date time in UTC that this patient transfer event occurred

Example: 2020-02-08T08:30:27Z
object
payload
object
required

An object that contains the detailed payload of the event

registration
object
requestingPracticeOdsCode
string
required

The ODS code of the practice requesting the EHR

Example: ABC1234
sendingPracticeOdsCode
string
required

The ODS code of the practice sending the EHR

Example: XYZ4567
structuredRecordMigration
object
status
string
required

The status

Allowed values: SUCCESS, FAILURE
reason
string

The reason for the status

Example: Could not retrieve record

Response

HTTP status: 200

OK. Expected response to a valid request

Body

Content type: application/json

Example

Schema

Name Description
object
Example:
{
  "eventId" : "1234-1234-1234-1234"
}
eventId
string
Example: 1234-1234-1234-1234
HTTP status: 400

Bad request

Body

Content type: application/json

Example

Schema

Name Description
object
Example:
{
  "status" : "BAD_REQUEST",
  "message" : "Failed to validate fields",
  "errors" : [ "reportingPracticeOdsCode must not be empty" ]
}
status
string
required
Example: BAD_REQUEST
message
string
required
Example: Failed to validate fields
errors
array
required
string
Example: reportingPracticeOdsCode must not be empty
HTTP status: 500

Internal Server Error

Body

Content type: application/json

Example

Schema

Name Description
object
Example:
{
  "status" : "INTERNAL_SERVER_ERROR",
  "message" : "Something went wrong",
  "errors" : [ "aws is down" ]
}
status
string
required
Example: INTERNAL_SERVER_ERROR
message
string
required
Example: Something went wrong
errors
array
required
string

Submit Migrate Document Request event

post /gpconnect/migrateDocumentRequest

Use this endpoint to submit GP registration management information immediately after the Requesting System makes an individual request to retrieve each document via GP Connect using the ‘Migrate Document’ end point

Request Body example:

Request

Headers
Name Description
apikey

String

API key to authenticate with.

Required
Body
Required

Content type: application/json

Schema

Name Description
object
allOf
object
eventId
string uuid
required

Unique identifier for this event

Max length: 16
Min length: 16
eventGeneratedDateTime
string date-time
required

The ISO 8601 Date time in UTC of when this MI event was generated by the system

Example: 2020-02-08T09:30:26Z
reportingSystemSupplier
string
required

The system supplier who generated the event. A unique identifier given to you as a supplier by NHSD

Example: supplierOne
reportingPracticeOdsCode
string
required

The ODS code of the practice generating this event

Example: ABC1234
conversationId
string

The ConversationID used in the GP2GP process for this registration

Example: 4345-9869-4930-6840
transferEventDateTime
string date-time

The ISO 8601 Date time in UTC that this patient transfer event occurred

Example: 2020-02-08T08:30:27Z
object
payload
object
required

An object that contains the detailed payload of the event

registration
object
requestingPracticeOdsCode
string
required

The ODS code of the practice requesting the EHR

Example: ABC1234
sendingPracticeOdsCode
string
required

The ODS code of the practice sending the EHR

Example: XYZ4567
attachment
object
attachmentId
string
required

A unique id for the attachment that can be resolved in the clinical system

Example: 3424-342456-3424-342456
clinicalType
string

The text value corresponding to the value used in EhrAttachmentCode in the code element of ExternalDocument as defined in the MIM

Example: Scanned document
mimeType
string
required

The mime type of the attachment as used as part of the text element in ExternalDocument as defined in the MIM

Example: application/pdf
sizeBytes
integer
required

The size in bytes of the attachment

Example: 3084322

Response

HTTP status: 200

OK. Expected response to a valid request

Body

Content type: application/json

Example

Schema

Name Description
object
Example:
{
  "eventId" : "1234-1234-1234-1234"
}
eventId
string
Example: 1234-1234-1234-1234
HTTP status: 400

Bad request

Body

Content type: application/json

Example

Schema

Name Description
object
Example:
{
  "status" : "BAD_REQUEST",
  "message" : "Failed to validate fields",
  "errors" : [ "reportingPracticeOdsCode must not be empty" ]
}
status
string
required
Example: BAD_REQUEST
message
string
required
Example: Failed to validate fields
errors
array
required
string
Example: reportingPracticeOdsCode must not be empty
HTTP status: 500

Internal Server Error

Body

Content type: application/json

Example

Schema

Name Description
object
Example:
{
  "status" : "INTERNAL_SERVER_ERROR",
  "message" : "Something went wrong",
  "errors" : [ "aws is down" ]
}
status
string
required
Example: INTERNAL_SERVER_ERROR
message
string
required
Example: Something went wrong
errors
array
required
string

Submit Migrate Document Response event

post /gpconnect/migrateDocumentResponse

Use this endpoint to submit GP registration management information immediately after the Requesting System receives a response on every individual request to retrieve each document via GP Connect using the ‘Migrate Document’ end point

Request Body example:

Request

Headers
Name Description
apikey

String

API key to authenticate with.

Required
Body
Required

Content type: application/json

Schema

Name Description
object
allOf
object
eventId
string uuid
required

Unique identifier for this event

Max length: 16
Min length: 16
eventGeneratedDateTime
string date-time
required

The ISO 8601 Date time in UTC of when this MI event was generated by the system

Example: 2020-02-08T09:30:26Z
reportingSystemSupplier
string
required

The system supplier who generated the event. A unique identifier given to you as a supplier by NHSD

Example: supplierOne
reportingPracticeOdsCode
string
required

The ODS code of the practice generating this event

Example: ABC1234
conversationId
string

The ConversationID used in the GP2GP process for this registration

Example: 4345-9869-4930-6840
transferEventDateTime
string date-time

The ISO 8601 Date time in UTC that this patient transfer event occurred

Example: 2020-02-08T08:30:27Z
object
payload
object
required

An object that contains the detailed payload of the event

registration
object
requestingPracticeOdsCode
string
required

The ODS code of the practice requesting the EHR

Example: ABC1234
sendingPracticeOdsCode
string
required

The ODS code of the practice sending the EHR

Example: XYZ4567
attachment
object
attachmentId
string
required

A unique id for the attachment that can be resolved in the clinical system

Example: 3424-342456-3424-342456
clinicalType
string

The text value corresponding to the value used in EhrAttachmentCode in the code element of ExternalDocument as defined in the MIM

Example: Scanned document
mimeType
string
required

The mime type of the attachment as used as part of the text element in ExternalDocument as defined in the MIM

Example: application/pdf
sizeBytes
integer
required

The size in bytes of the attachment