# This is an OpenAPI Specification (https://swagger.io/specification/) # for gp-connect-update-record-fhir owned by NHS Digital (https://digital.nhs.uk/) openapi: '3.0.0' info: title: '[DRAFT]gp-connect-update-record-fhir' version: 'draft' description: | # Overview Use this API to send structured data to a patient's GP record. You can send data related to the patient for the following areas: - medications - encounters - observations For the first iteration of this API, only a pharmacy use-case has been approved. Common use cases for this capability include: - a pharmacy informing the GP that a patient has been prescribed antibiotics - a pharmacy informing a GP that a patient has had their blood pressure checked # Who can use this API This API can be used by developers of clinical systems who have the need to update a patient's GP record. 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). ## Prerequisites ### Technical You must: - have access to the [Health and Social Care Network (HCSN)](https://digital.nhs.uk/services/health-and-social-care-network) - be [Personal Demographics Service (PDS)](https://digital.nhs.uk/services/demographics) compliant or capable of performing a PDS search to obtain the patient's registered GP - be [Spine Directory Service (SDS)](https://developer.nhs.uk/apis/gpconnect-0-5-0/integration_spine_directory_service.html) compliant to be able to obtain the endpoint of the registered GP ### Information governance You must: - be compliant with the GP Connect Direct Care API Information Governance Model - be using the GP Connect APIs for direct care purposes for NHS patients in England ### Clinical safety You must: - have a clinical safety officer (CSO) who is responsible for DCB0129 and, if necessary, DCB0160. For more details on clinical risk management, see Clinical risk management standards. If you are confident that you can meet the prerequisites, contact us to express your interest. See 'Onboarding' below. # Related APIs The following APIs are related to this API: - [GP Connect Access Record: Structured - FHIR API](https://digital.nhs.uk/developer/api-catalogue/gp-connect-access-record-structured-fhir) - retrieve structured information from a patient's GP practice record. - [GP Connect Send Document - FHIR API](https://digital.nhs.uk/developer/api-catalogue/gp-connect-send-document-fhir) - send a PDF consultation summary to a registered GP practice. # API status and roadmap This API is in [development](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 is a FHIR API which conforms to the [FHIR](https://digital.nhs.uk/developer/guides-and-documentation/our-api-technologies#fhir) global standard for health care data exchange. Specifically, it is aligned with the GP Connect Data Model which is a FHIR STU3 representation. The API requires the provider to send a HTTP request containing a FHIR payload to the provider endpoint. The payload will contain clinical information about the patient - for example, medications, encounters and observations. For more details, see [Update Record implementation guide](https://simplifier.net/guide/gp-connect-update-record?version=current) to assist with your development. # Network access You can access this API via the [Health and Social Care Network](https://digital.nhs.uk/services/health-and-social-care-network). The API is not currently available over the internet, but we plan to enable public internet access in the future. For more details, see [Network access for APIs.](https://digital.nhs.uk/developer/guides-and-documentation/network-access-for-apis) # Security and authorisation ## Security Access to the GP Connect APIs is controlled and protected by the Spine Secure Proxy (SSP), a forward HTTP proxy. It provides a single security point for both authentication and authorisation for consuming systems. Additional responsibilities include auditing of requests, checking data sharing agreements and transaction logging. All HTTP communications are secured using [TLS-MA](https://digital.nhs.uk/developer/guides-and-documentation/security-and-authorisation#application-restricted-apis). This includes both legs of the request, from consumer system to the proxy and then from the proxy to provider system. ## Authorisation Authorisation takes place in two locations: - the consumer system - the SSP The consumer system must have local [RBAC](https://digital.nhs.uk/developer/guides-and-documentation/security-and-authorisation/national-rbac-for-developers) in place and restrict GP Connect APIs to authorised users. With each request, a JSON Web Token (JWT) must be included with the following information: - details of users, including role - where smartcards are used in the consumer system, including SDS user and role IDs - details of the consumer system - details of the consumer’s organisation, including ODS code The information in the JWT is retained for audit purposes. The SSP checks data-sharing agreements to ensure that the consumer system is authorised to communicate with the provider system. # Environments and testing TBD # Onboarding This API is currently not available for onboarding. ## Expressing an interest If you meet the prerequisites and have a product that can integrate with GP Connect, you should express an interest with us by submitting a use case. The main purpose of the use case is to help us understand how you plan to use GP Connect APIs and the business issue you are looking to address. You should email your use case to us at gpconnect@nhs.net. Your use case should include the following information as a minimum: - the business problem you are intending to solve using GP Connect - how GP Connect will be used in practice to benefit patients and staff - which of the GP Connect products you will use to benefit patients and staff - any end user organisations you are currently working with - who your clinical safety officer is and, where available, your clinical risk management process documentation ## Consumer assurance process Once we approve your use case, we support you through the assurance process to go live. We will discuss the assurance process and artefacts with you to hel you understand our requirements Start your development work within 6 months of use case approval. If you miss this date, a review or new submission of the use case will be required. Changes or additional development will also require a review or new use case submission. # 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 are returned as a [GP Connect-OperationOutcome-1](https://simplifier.net/guide/gpconnect-data-model/Home/FHIR-Assets/All-assets/Profiles/Profile--GPConnect-OperationOutcome-1?version=current) resource in the event of an error. This provides additional detail to the user on the cause of the error. paths: /FHIR/STU3/Bundle: post: operationId: post-update summary: Post an update to the patients record description: > parameters: - in: header name: SSP-Trace-ID description: | The provider's Trace ID (normally a GUID or UUID) required: true schema: type: string - in: header name: SSP-From description: | The provider's ASID required: true schema: type: string - in: header name: SSP-To description: | The consumer's ASID required: true schema: type: string - in: header name: SSP-InteractionID description: | urn:nhs:names:services:gpconnect:fhir:bundle required: true schema: type: string - in: header name: EncounterId required: true schema: type: string requestBody: required: true description: Successful Request. content: application/fhir+json: schema: type: object description: > A [bundle](https://hl7.org/fhir/stu3/bundle.html) is posted to the endpoint consisting of four resources: - [Patient](https://simplifier.net/guide/gpconnect-data-model/Home/FHIR-Assets/All-assets/Profiles/Profile--CareConnect-GPC-Patient-1?version=current) - [Encounter](https://simplifier.net/guide/gpconnect-data-model/Home/FHIR-Assets/All-assets/Profiles/Profile--CareConnect-GPC-Encounter-1?version=current) - [Medication Statement](https://simplifier.net/guide/gpconnect-data-model/Home/FHIR-Assets/All-assets/Profiles/Profile--CareConnect-GPC-MedicationStatement-1?version=current) - [Observation](https://simplifier.net/guide/gpconnect-data-model/Home/FHIR-Assets/All-assets/Profiles/Profile--CareConnect-GPC-Observation-1?version=current) example: resourceType: Bundle meta: versionId: '1' lastUpdated: '2023-02-14T11:58:27.1516395+00:00' type: collection entry: - resource: resourceType: Patient id: e461896a-b0c8-457d-9397-b276c9aec312 meta: versionId: '1' lastUpdated: '2023-02-14T11:58:27.1516395+00:00' profile: - https://fhir.nhs.uk/STU3/StructureDefinition/CareConnect-GPC-Patient-1 active: true name: - use: official family: Test given: - Roger gender: male birthDate: '1975-12-25' - resource: meta: versionId: '1' lastUpdated: '2023-01-24T11:58:38.4899643+00:00' profile: - https://fhir.nhs.uk/STU3/StructureDefinition/CareConnect-GPC-Encounter-1 resourceType: Encounter reason: - coding: - extension: - extension: - valueId: '86591008' url: descriptionId - valueString: PharmacyVisit url: descriptionDisplay url: https://fhir.hl7.org.uk/STU3/StructureDefinition/Extension-coding-sctdescid display: Upset Stomach system: http://snomed.info/sct code: '271681002' type: - coding: - display: Face to face encounter code: '1258986006' system: http://snomed.info/sct subject: identifier: extension: - valueCodeableConcept: text: Number present and verified coding: - display: Number present and verified code: '01' system: https://fhir.hl7.org.uk/STU3/CodeSystem/CareConnect-NHSNumberVerificationStatus-1 url: https://fhir.hl7.org.uk/STU3/StructureDefinition/Extension-CareConnect-NHSNumberVerificationStatus-1 system: https://fhir.nhs.uk/Id/nhs-number value: '9989453456' participant: - period: start: '2022-12-25T14:01:31+00:00' individual: identifier: system: https://fhir.hl7.org.uk/Id/gmc-number value: '0054272' type: - text: recorder coding: - system: https://fhir.nhs.uk/STU3/ValueSet/GPConnect-ParticipantType-1 code: REC period: start: '2022-12-25T10:42:12+00:00' identifier: - system: https://hospital.example/visit-number value: visit-00425123 - resource: resourceType: MedicationStatement id: 359d0a53-f1ef-4c0b-9d58-01cabbc48413 meta: versionId: '1' lastUpdated: '2023-01-24T13:29:33.7462714+00:00' profile: - https://fhir.nhs.uk/STU3/StructureDefinition/CareConnect-GPC-MedicationStatement-1 extension: - url: https://fhir.nhs.uk/STU3/StructureDefinition/Extension-CareConnect-GPC-PrescribingAgency-1 valueCodeableConcept: coding: - system: https://fhir.nhs.uk/STU3/CodeSystem/CareConnect-PrescribingAgency-1 code: prescribed-by-another-organisation text: Prescribed by another organisation identifier: - system: https://hospital.example/medication-statement value: rx-0281156 context: identifier: system: https://hospital.example/visit-number value: visit-00425123 status: completed medicationCodeableConcept: coding: code: '39732311000001104' system: https://dmd.nhs.uk display: Amoxicillin 250mg capsules effectivePeriod: start: '2023-01-20' end: '2023-01-27' dateAsserted: '2023-01-24T13:29:33.7477005+00:00' informationSource: identifier: system: https://fhir.nhs.uk/Id/ods-organization-code value: RFR subject: identifier: extension: - url: https://fhir.hl7.org.uk/STU3/StructureDefinition/Extension-CareConnect-NHSNumberVerificationStatus-1 valueCodeableConcept: coding: - system: https://fhir.hl7.org.uk/STU3/CodeSystem/CareConnect-NHSNumberVerificationStatus-1 code: '01' display: Number present and verified text: Number present and verified system: https://fhir.nhs.uk/Id/nhs-number value: '9989453456' taken: 'y' note: - authorReference: identifier: system: https://fhir.hl7.org.uk/Id/gmc-number value: '00143922' time: '2023-01-24T13:29:33.7491725+00:00' text: Free text... R4 of the FHIR standard supports GitHub Flavoured Markdown (GFM) dosage: - text: 10 milligram - two times a day - oral - Swallow your capsules whole with a glass of water. DO NOT break, crush or chew them patientInstruction: Swallow your capsules whole with a glass of water. DO NOT break, crush or chew them timing: repeat: frequency: 1 period: 2 periodUnit: d when: - C route: coding: - system: https://snomed.info/sct code: '26643006' text: oral doseQuantity: value: 10 unit: milligram system: https://unitsofmeasure.org code: mg - resourceType: Observation status: final id: e461896a-b0c8-457d-9397-b276c9aec312 meta: versionId: '1' lastUpdated: '2023-02-14T11:58:27.1516395+00:00' profile: - https://fhir.nhs.uk/STU3/StructureDefinition/CareConnect-GPC-Observation-1 comment: Patient has high Temperature subject: identifier: extension: - valueCodeableConcept: text: Number present and verified coding: - display: Number present and verified code: '01' system: https://fhir.hl7.org.uk/STU3/CodeSystem/CareConnect-NHSNumberVerificationStatus-1 url: https://fhir.hl7.org.uk/STU3/StructureDefinition/Extension-CareConnect-NHSNumberVerificationStatus-1 system: https://fhir.nhs.uk/Id/nhs-number value: '9989453456' valueQuantity: code: cel unit: C system: http://unitsofmeasure.org value: 40 effectiveDateTime: '2023-02-14T11:58:27.153001+00:00' performer: - identifier: system: https://fhir.hl7.org.uk/Id/gmc-number value: '00143922' issued: '2023-02-14T11:58:27.1530896+00:00' category: - text: Vital signs coding: - display: vital-signs code: Vital signs system: http://terminology.hl7.org/CodeSystem/observation-category code: text: High Temperature coding: - display: High Temperature code: '285717004' system: http://snomed.info/sct context: reference: visit-00425123 responses: '200': description: Successful response content: application/fhir+json: schema: type: object description: > FILL THIS OUT examples: example: description: Succesful bundle post value: resourceType: Bundle id: e461896x-b0cx-4x7d-9344-b276c9aec312 meta: versionId: '1' lastUpdated: '2023-02-14T11:58:27.1516395+00:00' type: collection entry: - resource: resourceType: Patient id: e461896a-b0c8-457d-9397-b276c9aec312 meta: versionId: '1' lastUpdated: '2023-02-14T11:58:27.1516395+00:00' profile: - https://fhir.nhs.uk/STU3/StructureDefinition/CareConnect-GPC-Patient-1 active: true name: - use: official family: Test given: - Roger gender: male birthDate: '1975-12-25' - resource: meta: versionId: '1' lastUpdated: '2023-01-24T11:58:38.4899643+00:00' profile: - https://fhir.nhs.uk/STU3/StructureDefinition/CareConnect-GPC-Encounter-1 resourceType: Encounter reason: - coding: - extension: - extension: - valueId: '86591008' url: descriptionId - valueString: PharmacyVisit url: descriptionDisplay url: https://fhir.hl7.org.uk/STU3/StructureDefinition/Extension-coding-sctdescid display: Upset Stomach system: http://snomed.info/sct code: '271681002' type: - coding: - display: Face to face encounter code: '1258986006' system: http://snomed.info/sct subject: identifier: extension: - valueCodeableConcept: text: Number present and verified coding: - display: Number present and verified code: '01' system: https://fhir.hl7.org.uk/STU3/CodeSystem/CareConnect-NHSNumberVerificationStatus-1 url: https://fhir.hl7.org.uk/STU3/StructureDefinition/Extension-CareConnect-NHSNumberVerificationStatus-1 system: https://fhir.nhs.uk/Id/nhs-number value: '9989453456' participant: - period: start: '2022-12-25T14:01:31+00:00' individual: identifier: system: https://fhir.hl7.org.uk/Id/gmc-number value: '0054272' type: - text: recorder coding: - system: https://fhir.nhs.uk/STU3/ValueSet/GPConnect-ParticipantType-1 code: REC period: start: '2022-12-25T10:42:12+00:00' identifier: - system: https://hospital.example/visit-number value: visit-00425123 - resource: resourceType: MedicationStatement id: 359d0a53-f1ef-4c0b-9d58-01cabbc48413 meta: versionId: '1' lastUpdated: '2023-01-24T13:29:33.7462714+00:00' profile: - https://fhir.nhs.uk/STU3/StructureDefinition/CareConnect-GPC-MedicationStatement-1 extension: - url: https://fhir.nhs.uk/STU3/StructureDefinition/Extension-CareConnect-GPC-PrescribingAgency-1 valueCodeableConcept: coding: - system: https://fhir.nhs.uk/STU3/CodeSystem/CareConnect-PrescribingAgency-1 code: prescribed-by-another-organisation text: Prescribed by another organisation identifier: - system: https://hospital.example/medication-statement value: rx-0281156 context: identifier: system: https://hospital.example/visit-number value: visit-00425123 status: completed medicationCodeableConcept: coding: code: '39732311000001104' system: https://dmd.nhs.uk display: Amoxicillin 250mg capsules effectivePeriod: start: '2023-01-20' end: '2023-01-27' dateAsserted: '2023-01-24T13:29:33.7477005+00:00' informationSource: identifier: system: https://fhir.nhs.uk/Id/ods-organization-code value: RFR subject: identifier: extension: - url: https://fhir.hl7.org.uk/STU3/StructureDefinition/Extension-CareConnect-NHSNumberVerificationStatus-1 valueCodeableConcept: coding: - system: https://fhir.hl7.org.uk/STU3/CodeSystem/CareConnect-NHSNumberVerificationStatus-1 code: '01' display: Number present and verified text: Number present and verified system: https://fhir.nhs.uk/Id/nhs-number value: '9989453456' taken: 'y' note: - authorReference: identifier: system: https://fhir.hl7.org.uk/Id/gmc-number value: '00143922' time: '2023-01-24T13:29:33.7491725+00:00' text: Free text... R4 of the FHIR standard supports GitHub Flavoured Markdown (GFM) dosage: - text: 10 milligram - two times a day - oral - Swallow your capsules whole with a glass of water. DO NOT break, crush or chew them patientInstruction: Swallow your capsules whole with a glass of water. DO NOT break, crush or chew them timing: repeat: frequency: 1 period: 2 periodUnit: d when: - C route: coding: - system: https://snomed.info/sct code: '26643006' text: oral doseQuantity: value: 10 unit: milligram system: https://unitsofmeasure.org code: mg - resourceType: Observation status: final id: e461896a-b0c8-457d-9397-b276c9aec312 meta: versionId: '1' lastUpdated: '2023-02-14T11:58:27.1516395+00:00' profile: - https://fhir.nhs.uk/STU3/StructureDefinition/CareConnect-GPC-Observation-1 comment: Patient has high Temperature subject: identifier: extension: - valueCodeableConcept: text: Number present and verified coding: - display: Number present and verified code: '01' system: https://fhir.hl7.org.uk/STU3/CodeSystem/CareConnect-NHSNumberVerificationStatus-1 url: https://fhir.hl7.org.uk/STU3/StructureDefinition/Extension-CareConnect-NHSNumberVerificationStatus-1 system: https://fhir.nhs.uk/Id/nhs-number value: '9989453456' valueQuantity: code: cel unit: C system: http://unitsofmeasure.org value: 40 effectiveDateTime: '2023-02-14T11:58:27.153001+00:00' performer: - identifier: system: https://fhir.hl7.org.uk/Id/gmc-number value: '00143922' issued: '2023-02-14T11:58:27.1530896+00:00' category: - text: Vital signs coding: - display: vital-signs code: Vital signs system: http://terminology.hl7.org/CodeSystem/observation-category code: text: High Temperature coding: - display: High Temperature code: '285717004' system: http://snomed.info/sct context: reference: visit-00425123 4XX: description: | An error occured as follows: | HTTP Status | Spine error code | Description |-------------|--------------------|------------ | 400 | INVALID_RESOURCE | 400 | MISSING_FIELD | 400 | MISSING_RESOURCE | | 400 | INVALID_NHS_NUMBER | | 422 | UNPROCESSABLE | content: application/fhir+json: schema: type: object description: Link examples: example: value: resourceType: OperationOutcome meta: profile: - https://fhir.hl7.org.uk/StructureDefinition/GPConnect-OperationOutcome-1 issue: - severity: error code: value details: coding: - system: https://fhir.nhs.uk/STU3/ValueSet/Spine-ErrorOrWarningCode-1 code: INVALID_NHS_NUMBER display: Invalid NHS Number /meta: get: operationId: get-capabilitystatement summary: Get update record FHIR capability statement description: > parameters: - in: header name: SSP-Trace-ID description: | The provider's Trace ID (normally a GUID or UUID) required: true schema: type: string - in: header name: SSP-From description: | The provider's ASID required: true schema: type: string - in: header name: SSP-To description: | The consumer's ASID required: true schema: type: string - in: header name: SSP-InteractionID description: | urn:nhs:names:services:gpconnect:structured:fhir:rest:read:metadata-1 required: true schema: type: string responses: '200': description: Successful response content: application/fhir+json: schema: type: object description: > FILL THIS OUT examples: example: description: Succesful capability statement retrieval value: resourceType: CapabilityStatement version: 1.0.0 name: GP Connect API - Update Record status: active date: '2020-02-10' publisher: '[Provider Software Vendor Name]' contact: - name: '[Provider Software Vendor Contact Name]' description: This server implements the GP Connect API - Update Record version 1.0.0 copyright: Copyright NHS Digital 2016-21 kind: capability software: name: '[Provider Software Name]' version: '[Provider Software Version]' releaseDate: '[Provider Software Release Date]' fhirVersion: 3.0.1 acceptUnknown: both format: - application/fhir+json - application/fhir+xml profile: - reference: https://fhir.nhs.uk/STU3/StructureDefinition/CareConnect-GPC-Patient-1/_history/1.8 - reference: https://fhir.nhs.uk/STU3/StructureDefinition/CareConnect-GPC-Organization-1/_history/1.4 - reference: https://fhir.nhs.uk/STU3/StructureDefinition/CareConnect-GPC-Practitioner-1/_history/1.2 - reference: https://fhir.nhs.uk/STU3/StructureDefinition/CareConnect-GPC-MedicationStatement-1/_history/1.7 - reference: https://fhir.nhs.uk/STU3/StructureDefinition/GPConnect-StructuredRecord-Bundle-1/_history/1.3 - reference: https://fhir.nhs.uk/STU3/StructureDefinition/GPConnect-OperationOutcome-1/_history/1.2 - reference: https://fhir.nhs.uk/STU3/StructureDefinition/CareConnect-GPC-Encounter-1/_history/1.5 - reference: https://fhir.nhs.uk/STU3/StructureDefinition/CareConnect-GPC-Observation-1/_history/1.7 rest: - mode: server security: cors: true 4XX: description: | An error occured as follows: | HTTP Status | Error code | Description |-------------|--------------------|------------ | 403 | ACCESS DENIED | GP Connect is not enabled at the practice 403 | ACCESS DENIED | The Update Record Structured capability is not enabled at the practice content: application/fhir+json: schema: type: object description: Link examples: example: value: resourceType: OperationOutcome meta: profile: - https://fhir.hl7.org.uk/StructureDefinition/GPConnect-OperationOutcome-1 issue: - severity: error code: value details: coding: - system: https://fhir.nhs.uk/STU3/ValueSet/Spine-ErrorOrWarningCode-1 code: ACCESS DENIED display: GP Connect is not enabled at the practice