GP Connect FHIR API

openapi: 3.2.0
info:
  title: '[DRAFT]gp-connect-update-record FHIR API'
  version: draft
  description: "# Overview\nUse this API to send structured data to a patient's GP record. You can send data related to the patient for the following areas:\n- medications\n- encounters\n- observations\n\nFor the first iteration of this API, only a pharmacy use-case has been approved. Common use cases for this capability include:\n\n- a pharmacy informing the GP that a patient has been prescribed antibiotics\n- a pharmacy informing a GP that a patient has had their blood pressure checked\n\n# Who can use this API\nThis API can be used by developers of clinical systems who have the need to update a patient's GP record.\n\nMake sure you have a valid use case before you go too far with your development.\nYou must do this before you can go live (see 'Onboarding' below).\n## Prerequisites\n### Technical \n\nYou must:\n\n- have access to the [Health and Social Care Network (HCSN)](https://digital.nhs.uk/services/health-and-social-care-network)\n - 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\n - 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\n### Information governance\n You must:\n - be compliant with the GP Connect Direct Care API Information Governance Model\n - be using the GP Connect APIs for direct care purposes for NHS patients in England\n \n ### Clinical safety\nYou must:\n- 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.\nIf you are confident that you can meet the prerequisites, contact us to express your interest. See 'Onboarding' below.\n# Related APIs\n  The following APIs are related to this API:\n  - [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.\n  - [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.\n\n# API status and roadmap\nThis API is in [development](https://digital.nhs.uk/developer/guides-and-documentation/reference-guide#statuses).\n# Service level\nThis 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.\nFor more details, see [service levels](https://digital.nhs.uk/developer/guides-and-documentation/reference-guide#service-levels).\n# Technology\nThis 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.  \n\nThe API requires the provider to send a HTTP request containing a FHIR payload to the provider endpoint. \n\nThe payload will contain clinical information about the patient - for example, medications,  encounters and observations.\nFor more details, see [Update Record implementation guide](https://simplifier.net/guide/gp-connect-update-record?version=current) to assist with your development.\n# Network access\nYou can access this API via the [Health and Social Care Network](https://digital.nhs.uk/services/health-and-social-care-network).\n\nThe API is not currently available over the internet, but we plan to enable public internet access in the future.\nFor more details, see [Network access for APIs.](https://digital.nhs.uk/developer/guides-and-documentation/network-access-for-apis)\n# Security and authorisation\n## Security\nAccess to the GP Connect APIs is controlled and protected by the Spine Secure Proxy (SSP), a forward HTTP proxy.\n\nIt 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.\n\nAll 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.\n\n## Authorisation\nAuthorisation takes place in two locations: \n\n- the consumer system\n- the SSP\n\nThe 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:\n-  details of users, including role\n-  where smartcards are used in the consumer system, including SDS user and role IDs\n- details of the consumer system\n- details of the consumer’s organisation, including ODS code\n\nThe information in the JWT is retained for audit purposes.\n\nThe SSP checks data-sharing agreements to ensure that the consumer system is authorised to communicate with the provider system.\n\n# Environments and testing\n\nTBD\n\n# Onboarding\n\nThis API is currently not available for onboarding.\n\n## Expressing an interest\n\nIf 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. \n\nThe 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. \n\nYou should email your use case to us at gpconnect@nhs.net. Your use case should include the following information as a minimum:\n- the business problem you are intending to solve using GP Connect\n- how GP Connect will be used in practice to benefit patients and staff\n- which of the GP Connect products you will use to benefit patients and staff\n- any end user organisations you are currently working with\n- who your clinical safety officer is and, where available, your clinical risk management process documentation\n\n## Consumer assurance process\n\nOnce 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\n\nStart 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. \n\n# Errors\n\nWe use standard HTTP status codes to show whether an API request succeeded or not. They are usually in the range:\n\n- 200 to 299 if it succeeded, including code 202 if it was accepted by an API that needs to wait for further action\n\n- 400 to 499 if it failed because of a client error by your application\n\n- 500 to 599 if it failed because of an error on our server\n\nErrors 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.\n"
tags:
- name: FHIR
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:\n - [Patient](https://simplifier.net/guide/gpconnect-data-model/Home/FHIR-Assets/All-assets/Profiles/Profile--CareConnect-GPC-Patient-1?version=current)\n - [Encounter](https://simplifier.net/guide/gpconnect-data-model/Home/FHIR-Assets/All-assets/Profiles/Profile--CareConnect-GPC-Encounter-1?version=current)\n - [Medication Statement](https://simplifier.net/guide/gpconnect-data-model/Home/FHIR-Assets/All-assets/Profiles/Profile--CareConnect-GPC-MedicationStatement-1?version=current)\n - [Observation](https://simplifier.net/guide/gpconnect-data-model/Home/FHIR-Assets/All-assets/Profiles/Profile--CareConnect-GPC-Observation-1?version=current)\n"
            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:\n\n\n| HTTP Status | Spine error code   | Description\n|-------------|--------------------|------------\n| 400         | INVALID_RESOURCE   | \n  400         | MISSING_FIELD      |\n  400         | MISSING_RESOURCE   |\n| 400         | INVALID_NHS_NUMBER |\n| 422         | UNPROCESSABLE      | \n"
          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
      tags:
      - FHIR