GP Connect Slot API

openapi: 3.2.0
info:
  title: gp-connect/patient-facing/appointments-management-fhir/FHIR/…
  version: Computed and injected at build time by `scripts/set_version.py`
  description: '## Overview


    !Appointments Overview

    Use this API to book and manage patient appointments at their GP practice.'
  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
      operationId: getSlot
      x-operation-id-source: derived
components:
  parameters:
    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
    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
    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
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}