GP Connect Slot API

openapi: 3.2.0
info:
  title: gp-connect/patient-facing/appointments-management-fhir/FHIR/STU3 Slot API
  version: Computed and injected at build time by `scripts/set_version.py`
  description: "## Overview\n\n![Appointments Overview](https://raw.githubusercontent.com/NHSDigital/gp-connect-appointments-management-fhir/master/specification/diagrams/GP-Connect-PFS-Appointment-Management.svg)\nUse this API to book and manage patient appointments at their GP practice.\n\nYou can:\n\n - search for free slots\n - book an appointment\n - retrieve a patient’s appointments\n - get details of a single appointment\n - cancel an appointment\n\nYou cannot:\n\n - amend a patient's appointments beyond cancelling\n - re-schedule a patient's appointments (this must be done by cancelling and re-booking)\n\nTo use this API, the end user must be a patient who is:\n\n - registered with the GP practice\n - registered with NHS login to P9 identity verification level\n\n## Who can use this API\n\nThis API can be used by developers of clinical systems. It is a patient-facing API.\nThis API:\n\n- is only intended for use by patient-facing applications\n- can only be used where there is a legal basis to do so\n\nMake sure you have a valid use case before you go too far with your development. To do this, contact us.\nYou must do this before you can go live (see 'Onboarding' below).\n\n### Prerequisites\n\n#### Information governance (IG)\n\n You must:\n\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\n\nYou must:\n\n- have a clinical safety officer (CSO) who is responsible for DCB0129 and, if necessary, DCB0160. For more on clinical risk management, visit Clinical risk management standards.\n\nIf you are confident that you can meet the prerequisites, contact us to express your interest. See 'Onboarding' below.\n\n## Related APIs\n\n  The following APIs are related to this API:\n\n  - [GP Connect Access Document - FHIR API](https://digital.nhs.uk/developer/api-catalogue/gp-connect-access-document-fhir) - retrieve unstructured documents from a patient's GP practice record.\n  - [GP Connect Access Record: HTML - FHIR API](https://digital.nhs.uk/developer/api-catalogue/gp-connect-access-record-html-fhir) - view a patient's GP practice record, with read-only access.\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 Appointment Management - FHIR API](https://digital.nhs.uk/developer/api-catalogue/gp-connect-appointment-management-fhir) - manage GP practice appointments between different systems.\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  - [GP Connect (Patient Facing) Access Record - FHIR API](https://digital.nhs.uk/developer/api-catalogue/gp-connect-patient-facing-access-record-fhir) - access a patient's GP records with the GP Connect (patient facing) Access Record - FHIR API.\n  - [GP Connect (Patient Facing) Appointment Management - FHIR API](https://digital.nhs.uk/developer/api-catalogue/gp-connect-patient-facing-appointment-management-fhir) - manage a patient's GP appointments using the GP Connect (patient facing) Appointment Management - FHIR API.\n  - [GP Connect (Patient Facing) Prescriptions - FHIR API](https://digital.nhs.uk/developer/api-catalogue/gp-connect-patient-facing-prescriptions-fhir) - manage a patient's prescriptions using the GP Connect (patient facing) Prescriptions - FHIR API.\n\n## API status and roadmap\n\nThis API is in [development](https://digital.nhs.uk/developer/guides-and-documentation/reference-guide#statuses).\n\n## Service level\n\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\n## Technology\n\nThis API is a FHIR API.\nIt sends a FHIR STU3 payload.\nFor more details, see [FHIR](https://digital.nhs.uk/developer/guides-and-documentation/our-api-technologies#fhir).\n\n## Network access\n\nThis API is available on the internet and indirectly over HSCN.\nFor more details, see [Network access for APIs](https://digital.nhs.uk/developer/guides-and-documentation/network-access-for-apis).\n\n## Security and authorisation\n\nThis API is [user-restricted](https://digital.nhs.uk/developer/guides-and-documentation/security-and-authorisation#user-restricted-apis), meaning an end user must be present and authenticated to use it.\nThe end user must be:\n\n- a patient\n- authenticated with NHS login to P9 identity verification level\n\nThe API uses Open ID Connect to authenticate the end user and OAuth 2.0 to authorise the calling system. It supports the following security pattern using NHS login:\n\n- [User-restricted RESTful APIs - NHS login separate authentication and authorisation](https://digital.nhs.uk/developer/guides-and-documentation/security-and-authorisation/user-restricted-restful-apis-nhs-login-separate-authentication-and-authorisation)\n\nYou should manage access to your system locally using local role-based access control (RBAC). This does not need to be compliant with the national RBAC model and GP Connect products do not require smartcards to control access, though they can be used if already implemented.\n\n## Environments and testing\n\n| Purpose          | URL                                                   |\n| -------          | ---                                                   |\n| Sandbox          | `https://sandbox.api.service.nhs.uk/gp-connect/patient-facing/appointments-management-fhir/FHIR/STU3`\n| Integration test | Not yet available                                     |\n| Production       | Not yet available                                     |\n\n### Sandbox testing (not yet available)\n\nOur [sandbox environment](https://digital.nhs.uk/developer/guides-and-documentation/testing#sandbox-testing):\n\n- is for early developer testing\n- only covers a limited set of scenarios\n- is stateless, so it does not store data\n- is open access, so does not allow you to test authorisation\n\nFor more details on sandbox testing, or to try out the sandbox using our\n\"Try this API\" feature, see the documentation for each endpoint.\n\nAlternatively, you can try out the sandbox using our Postman collection:\n\n[![Run in Postman](https://run.pstmn.io/button.svg)](https://god.gw.postman.com/run-collection/23494791-85645b5a-6ad4-48f1-9509-8118a8cb6fb7?action=collection%2Ffork&source=rip_markdown&collection-url=entityId%3D23494791-85645b5a-6ad4-48f1-9509-8118a8cb6fb7%26entityType%3Dcollection%26workspaceId%3De0e123ef-5780-42f5-bae8-23b5785694d0)\n\n### Integration testing (not yet available)\n\nOur [integration test environment](https://digital.nhs.uk/developer/guides-and-documentation/testing#integration-testing):\n\n- is for formal integration testing\n- is stateful, so it does persist data\n- includes authorisation\n\nFor more details see [integration testing with our RESTful APIs](https://digital.nhs.uk/developer/guides-and-documentation/testing#integration-testing-with-our-restful-apis).\n\n## Errors\n\nWe use standard HTTP status codes to show whether an API request succeeded\nor not. They are usually in the range:\n\n- 200 to 299 if it succeeded, including code 202 if it was accepted by an\nAPI that needs to wait for further action\n- 400 to 499 if it failed because of a client error by your application\n- 500 to 599 if it failed because of an error on our server\n\nErrors specific to each API are shown in the Endpoints section, under Response. See our [reference guide](https://digital.nhs.uk/developer/guides-and-documentation/reference-guide#http-status-codes) for more on errors.\nAPI Specific errors can be found [here.](https://simplifier.net/guide/pfs-appointments/guides-pfs-appointments-home-build-error-handling?version=current)\n\n## Onboarding\n\nThis API is not yet 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.\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. You should email your use case to us at gpconnect@nhs.net.\nYour use case should include the following information as a minimum:\n\n- the business problem you are intending to solve using GP wConnect\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\nOnce we receive your use case, we'll respond within 14 days.\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 help you understand our requirements.\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"
  contact:
    name: gp-connect/patient-facing/appointments-management-fhir/FHIR/STU3 API Support
    url: https://digital.nhs.uk/developer/help-and-support
    email: api.management@nhs.net
servers:
- description: Sandbox environment.
  url: https://sandbox.api.service.nhs.uk/gp-connect/patient-facing/appointments-management-fhir/FHIR/STU3/
- description: Integration test environment.
  url: https://int.api.service.nhs.uk/gp-connect/patient-facing/appointments-management-fhir/FHIR/STU3/
- description: Production environment.
  url: https://api.service.nhs.uk/gp-connect/patient-facing/appointments-management-fhir/FHIR/STU3/
tags:
- name: Slot
paths:
  /Slot:
    get:
      summary: Search for free slots
      description: Search the patient's GP system for free slots that are available for appointment bookings.
      parameters:
      - $ref: '#/components/parameters/BearerAuthorization'
      - $ref: '#/components/parameters/CorrelationID'
      - $ref: '#/components/parameters/RequestID'
      - name: start
        in: query
        description: Slot start date/time
        required: true
        schema:
          type: string
        example: ge2020-05-09
      - name: end
        in: query
        description: Slot end date/time
        required: true
        schema:
          type: string
        example: le2020-05-10
      - name: status
        in: query
        description: Slot status
        required: true
        schema:
          type: string
          default: free
          enum:
          - free
      - name: _include
        in: query
        description: Include
        required: true
        schema:
          type: string
          default: Slot:schedule
          enum:
          - Slot:schedule
      - in: query
        name: _include:recurse
        description: 'Schedule:actor:Practitioner Include Practitioner resources referenced in Schedule:actor

          Schedule:actor:Location Include Location resources referenced in Schedule:actor

          Location:managingOrganization Include managingOrganization resources referenced in Location

          '
        schema:
          type: array
          items:
            type: string
            enum:
            - Schedule:actor:Practitioner
            - Schedule:actor:Location
            - Location:managingOrganization
      - name: searchFilter
        in: query
        description: Search filter
        style: form
        explode: true
        schema:
          type: array
          items:
            type: string
            enum:
            - https://fhir.nhs.uk/STU3/CodeSystem/GPConnect-OrganisationType-1|gp-practice
            - https://fhir.nhs.uk/Id/ods-organization-code|A20047
      responses:
        200:
          description: OK
          content:
            application/fhir+json:
              schema:
                type: object
                description: Link to GPConnect-Slot-1 resource population guidance [here](https://simplifier.net/guide/gpconnect-data-model/Home/FHIR-Assets/All-assets/Profiles/Profile--GPConnect-Slot-1?version=current).
              examples:
                example:
                  value:
                    resourceType: Bundle
                    type: searchset
                    entry:
                    - resource:
                        resourceType: Slot
                        id: '1584'
                        meta:
                          versionId: '1471219260000'
                          profile:
                          - https://fhir.nhs.uk/STU3/StructureDefinition/GPConnect-Slot-1
                        extension:
                        - url: https://fhir.nhs.uk/STU3/StructureDefinition/Extension-GPConnect-DeliveryChannel-2
                          valueCode: In-person
                        serviceType:
                        - text: General GP Appointment
                        schedule:
                          reference: Schedule/14
                        status: free
                        start: '2016-08-15T11:30:00+01:00'
                        end: '2016-08-15T11:40:00+01:00'
                    - resource:
                        resourceType: Slot
                        id: '1644'
                        meta:
                          versionId: '1471219260112'
                          profile:
                          - https://fhir.nhs.uk/STU3/StructureDefinition/GPConnect-Slot-1
                        extension:
                        - url: https://fhir.nhs.uk/STU3/StructureDefinition/Extension-GPConnect-DeliveryChannel-2
                          valueCode: In-person
                        serviceType:
                        - text: NHS Health Check
                        schedule:
                          reference: Schedule/14
                        status: free
                        start: '2016-08-15T11:40:00+01:00'
                        end: '2016-08-15T11:50:00+01:00'
                    - resource:
                        resourceType: Schedule
                        id: '14'
                        meta:
                          versionId: '1469444400000'
                          profile:
                          - https://fhir.nhs.uk/STU3/StructureDefinition/GPConnect-Schedule-1
                        extension:
                        - url: https://fhir.nhs.uk/STU3/StructureDefinition/Extension-GPConnect-PractitionerRole-1
                          valueCodeableConcept:
                            coding:
                            - system: https://fhir.nhs.uk/STU3/CodeSystem/CareConnect-SDSJobRoleName-1
                              code: R0260
                              display: General Medical Practitioner
                        serviceCategory:
                          text: General GP Appointments
                        actor:
                        - reference: Location/17
                        - reference: Practitioner/2
                        planningHorizon:
                          start: '2016-08-15T09:00:00+01:00'
                          end: '2016-08-15T12:00:00+01:00'
                    - resource:
                        resourceType: Practitioner
                        id: '2'
                        meta:
                          versionId: '636064088099800115'
                          profile:
                          - https://fhir.nhs.uk/STU3/StructureDefinition/CareConnect-GPC-Practitioner-1
                        identifier:
                        - system: https://fhir.nhs.uk/Id/sds-user-id
                          value: '111122223333'
                        name:
                        - family: Black
                          given:
                          - Sarah
                          prefix:
                          - Mrs
                        gender: female
                    - resource:
                        resourceType: Location
                        id: '17'
                        meta:
                          versionId: '636064088100870233'
                          profile:
                          - https://fhir.nhs.uk/STU3/StructureDefinition/CareConnect-GPC-Location-1
                        name: The Trevelyan Practice
                        address:
                          line:
                          - Trevelyan Square
                          - Boar Ln
                          - Leeds
                          postalCode: LS1 6AE
                        telecom:
                          system: phone
                          value: 03003035678
                          use: work
                        managingOrganization:
                          reference: Organization/23
                    - resource:
                        resourceType: Organization
                        id: '23'
                        meta:
                          versionId: '636064088098730113'
                          profile:
                          - https://fhir.nhs.uk/STU3/StructureDefinition/CareConnect-GPC-Organization-1
                        identifier:
                        - system: https://fhir.nhs.uk/Id/ods-organization-code
                          value: A00001
                        name: The Trevelyan Practice
                        address:
                          line:
                          - Trevelyan Square
                          - Boar Ln
                          city: Leeds
                          district: West Yorkshire
                          postalCode: LS1 6AE
                        telecom:
                          system: phone
                          value: 03003035678
                          use: work
        4XX:
          description: "An error occurred as follows:\n\n| HTTP status | Error code                | Description                                                       |\n| ----------- | ----------                | -----------                                                       |\n| 400         | INVALID_IDENTIFIER_VALUE  | Invalid identifier value                                          |\n| 400         | BAD_REQUEST\t              | Submitted request is malformed/invalid                            |\n| 400         | VALIDATION_ERROR          | This is the \"default\" error thrown when no others are applicable  |\n| 400         | UNSUPPORTED_VALUE         | There was an unsupported value in the request                     |\n| 400         | NO_ORGANISATION_CONSENT   | Organisation has not provided consent to share data               |\n| 400         | BAD_REQUEST               | Submitted request is malformed/invalid                            |\n| 403         | ACCESS_DENIED\t            | Access denied                                                     |\n| 404         | NO_RECORD_FOUND           | No record found                                                   |\n| 422         | INVALID RESOURCE          | Submitted resource is invalid                                     |\n| 422         | INVALID PARAMETER         | Submitted parameter is invalid                                    |\n"
          content:
            application/fhir+json:
              schema:
                type: object
                description: Link to GPConnect-OperationOutcome-1 resource population guidance [here](https://simplifier.net/guide/gpconnect-data-model/Home/FHIR-Assets/All-assets/Profiles/Profile--GPConnect-OperationOutcome-1?version=current).
              examples:
                example:
                  value:
                    resourceType: OperationOutcome
                    meta:
                      profile:
                      - https://fhir.nhs.uk/STU3/StructureDefinition/GPConnect-OperationOutcome-1
                    issue:
                    - severity: error
                      code: forbidden
                      details:
                        coding:
                        - system: https://fhir.nhs.uk/STU3/ValueSet/Spine-ErrorOrWarningCode-1
                          code: ACCESS_DENIED
                          display: Access Denied
      tags:
      - Slot
components:
  parameters:
    BearerAuthorization:
      in: header
      name: Authorization
      description: 'An [OAuth 2.0 bearer token](https://digital.nhs.uk/developer/guides-and-documentation/security-and-authorisation#user-restricted-apis).

        Required in all environments except sandbox.

        '
      required: true
      schema:
        type: string
        format: ^Bearer\ [[:ascii:]]+$
        example: Bearer g1112R_ccQ1Ebbb4gtHBP1aaaNM
    RequestID:
      in: header
      name: X-Request-ID
      required: true
      description: 'A globally unique identifier (GUID) for the request, which we use to de-duplicate repeated requests and to trace the request if you contact our helpdesk.

        Must be a universally unique identifier (UUID) (ideally version 4).

        Mirrored back in a response header.

        If you re-send a failed request, use the same value in this header.

        Required in all environments except sandbox.

        '
      schema:
        type: string
        pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$
        example: 60E0B220-8136-4CA5-AE46-1D97EF59D068
    CorrelationID:
      in: header
      name: X-Correlation-ID
      required: false
      description: 'An optional ID which you can use to track transactions across multiple systems. It can have any value, but we recommend avoiding `.` characters.

        Mirrored back in a response header.

        '
      schema:
        type: string
        example: 11C46F5F-CDEF-4865-94B2-0EE0EDCC26DA
x-spec-publication:
  operation-order:
  - operations:
    - method: GET
      path: /FHIR/STU3/Slot
    - method: POST
      path: /FHIR/STU3/Appointment
    - method: GET
      path: /FHIR/STU3/Patient/{id}/Appointment
    - method: GET
      path: /FHIR/STU3/Appointment/{id}
    - method: PUT
      path: /FHIR/STU3/Appointment/{id}