GP Connect Appointment 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: Appointment
paths:
  /Appointment:
    post:
      summary: Book an appointment
      description: Book an appointment using the patient details and a retreived slot details.
      parameters:
      - $ref: '#/components/parameters/BearerAuthorization'
      - $ref: '#/components/parameters/CorrelationID'
      - $ref: '#/components/parameters/RequestID'
      requestBody:
        description: Appointment
        content:
          application/fhir+json:
            schema:
              type: object
              description: Link to Profile--GPConnect-Appointment-1 resource population guidance [here](https://simplifier.net/guide/gpconnect-data-model/Home/FHIR-Assets/All-assets/Profiles/Profile--GPConnect-Appointment-1?version=current).
            example:
              resourceType: Appointment
              meta:
                profile:
                - https://fhir.nhs.uk/STU3/StructureDefinition/GPConnect-Appointment-1
              contained:
              - resourceType: Organization
                id: '1'
                meta:
                  profile:
                  - https://fhir.nhs.uk/STU3/StructureDefinition/CareConnect-GPC-Organization-1
                identifier:
                - system: https://fhir.nhs.uk/Id/ods-organization-code
                  value: Z100
                type:
                - coding:
                  - system: https://fhir.nhs.uk/STU3/CodeSystem/GPConnect-OrganisationType-1
                    code: GP Practice
                name: Dr P. Stamp
                telecom:
                - system: phone
                  value: '01111222333'
                  extension:
                  - url: https://fhir.nhs.uk/STU3/StructureDefinition/Extension-GPConnect-BookingOrganisation-1
                valueReference:
                  reference: '#1'
                  status: proposed
                  description: Free text description.
                  start: '2017-05-30T10:00:00+01:00'
                  end: '2017-05-30T10:25:00+01:00'
                  slot:
                  - reference: Slot/1
                  created: '2017-05-25T13:48:41+01:00'
                  comment: Free text comment.
                  participant: null
              - actor:
                  reference: Patient/9000000009
                status: accepted
              - actor:
                  reference: Location/32
                status: accepted
                required: true
      responses:
        201:
          description: Created
          content:
            application/fhir+json:
              schema:
                type: object
                description: Link to Profile--GPConnect-Appointment-1 resource population guidance [here](https://simplifier.net/guide/gpconnect-data-model/Home/FHIR-Assets/All-assets/Profiles/Profile--GPConnect-Appointment-1?version=current).
              example:
                resourceType: Appointment
                id: '9'
                meta:
                  versionId: '636068818095315079'
                  profile:
                  - https://fhir.nhs.uk/STU3/StructureDefinition/GPConnect-Appointment-1
                contained:
                - resourceType: Organization
                  id: '1'
                  meta:
                    profile:
                    - https://fhir.nhs.uk/STU3/StructureDefinition/CareConnect-GPC-Organization-1
                  identifier:
                  - system: https://fhir.nhs.uk/Id/ods-organization-code
                    value: Z100
                  type:
                  - coding:
                    - system: https://fhir.nhs.uk/STU3/CodeSystem/GPConnect-OrganisationType-1
                      code: GP Practice
                  name: Dr P.Stamp
                  telecom:
                  - system: phone
                    value: '01111222333'
                extension:
                - url: https://fhir.nhs.uk/STU3/StructureDefinition/Extension-GPConnect-BookingOrganisation-1
                  valueReference:
                    reference: '#1'
                - 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
                - url: https://fhir.nhs.uk/STU3/StructureDefinition/Extension-GPConnect-DeliveryChannel-2
                  valueCode: In-person
                status: booked
                serviceCategory:
                  text: General GP Appointments
                serviceType:
                - text: General GP Appointment
                description: Free text description.
                start: '2017-05-30T10:00:00+01:00'
                end: '2017-05-30T10:25:00+01:00'
                minutesDuration: 25
                slot:
                - reference: Slot/1
                created: '2017-05-25T13:48:41+01:00'
                comment: Free text comment.
                participant:
                - actor:
                    reference: Patient/9000000009
                  status: accepted
                - actor:
                    reference: Location/32
                  status: accepted
        4XX:
          description: 'An error occurred as follows:



            | HTTP status | Error code              | Description                                                       |

            | ----------- | ----------              | -----------                                                       |

            | 400         | INVALID_IDENTIFIER_VA   | Invalid identifier value                                          |

            | 400         | BAD_REQUEST             | Submitted request is malformed/invalid                            |

            | 400         | VALIDATION_ERROR        | This is the "default" error thrown when no others are applicable  |

            | 400         | UNSUPPORTED_VALUE       | There was an unsupported value in the request                     |

            | 400         | NO_ORGANISATION_CONSENT | Organisation has not provided consent to share data               |

            | 400         | BAD_REQUEST             | Submitted request is malformed/invalid                            |

            | 400         | INVALID_NHS_NUMBER      | Nhs Number Invalid                                                |

            | 403         | ACCESS_DENIED           | Access denied                                                     |

            | 404         | ORGANISATION_NOT_FOUND  | Organisation record not found                                     |

            | 404         | PRACTITIONER_NOT_FOUND  | Practitioner record not found                                     |

            | 404         | PATIENT_NOT_FOUND       | Patient record not found                                          |

            | 404         | NO_RECORD_FOUND         | No record found                                                   |

            | 409         | DUPLICATE_REJECTED      | Create would lead to creation of a duplicate resource             |

            '
          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: not-found
                      details:
                        coding:
                        - system: https://fhir.nhs.uk/STU3/ValueSet/Spine-ErrorOrWarningCode-1
                          code: NO_RECORD_FOUND
                          display: No record found
      x-codegen-request-body-name: body
      tags:
      - Appointment
      operationId: postAppointment
      x-operation-id-source: derived
  /Appointment/{id}:
    get:
      summary: Get details of a single appointment
      description: Get a detailed view of a single patient appointment using the appointment id.
      parameters:
      - $ref: '#/components/parameters/BearerAuthorization'
      - $ref: '#/components/parameters/CorrelationID'
      - $ref: '#/components/parameters/RequestID'
      - name: id
        in: path
        description: Appointment logical identifier
        required: true
        schema:
          type: string
        example: '1'
      - in: query
        name: _include:recurse
        description: 'Appointment:actor:Practitioner Include Practitioner resources referenced in Appointment:actor

          Appointment:actor:Location Include Location resources referenced in Appointment:actor

          '
        schema:
          type: array
          items:
            type: string
            enum:
            - Appointment:actor:Practitioner
            - Appointment:actor:Location
      responses:
        200:
          description: OK
          content:
            application/fhir+json:
              schema:
                type: object
                description: Link to Profile--GPConnect-Appointment-1 resource population guidance [here](https://simplifier.net/guide/gpconnect-data-model/Home/FHIR-Assets/All-assets/Profiles/Profile--GPConnect-Appointment-1?version=current).
              examples:
                example:
                  value:
                    resourceType: Appointment
                    id: '150'
                    meta:
                      versionId: '1503440820000'
                      profile:
                      - https://fhir.nhs.uk/STU3/StructureDefinition/GPConnect-Appointment-1
                    contained:
                    - resourceType: Organization
                      id: '1'
                      meta:
                        profile:
                        - https://fhir.nhs.uk/STU3/StructureDefinition/CareConnect-GPC-Organization-1
                      identifier:
                      - system: https://fhir.nhs.uk/Id/ods-organization-code
                        value: Z100
                      type:
                      - coding:
                        - system: https://fhir.nhs.uk/STU3/CodeSystem/GPConnect-OrganisationType-1
                          code: GP Practice
                      name: Dr P. Stamp
                      telecom:
                      - system: phone
                        value: '01111222333'
                    extension:
                    - url: https://fhir.nhs.uk/STU3/StructureDefinition/Extension-GPConnect-BookingOrganisation-1
                      valueReference:
                        reference: '#1'
                    - 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
                    - url: https://fhir.nhs.uk/STU3/StructureDefinition/Extension-GPConnect-DeliveryChannel-2
                      valueCode: In-person
                    status: booked
                    serviceCategory:
                      text: General GP Appointments
                    serviceType:
                    - text: General GP Appointment
                    description: GP Connect Appointment description 148
                    start: '2017-08-17T11:20:00+01:00'
                    end: '2017-08-17T11:30:00+01:00'
                    minutesDuration: 10
                    slot:
                    - reference: Slot/303
                    created: '2017-08-14T13:48:41+01:00'
                    participant:
                    - actor:
                        reference: Patient/9000000009
                      status: accepted
                    - actor:
                        reference: Location/1
                      status: accepted
                    - 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
        4XX:
          description: "An error occurred as follows:\n\n\n| HTTP status | Error code               | Description                                                        |\n| ----------- | ----------               | -----------                                                        |\n| 400         | INVALID_IDENTIFIER_VA    | Invalid identifier value                                           |\n| 400         | BAD_REQUEST              | 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            | Access denied                                                      |\n| 404\t        | NO_RECORD_FOUND          | No record found                                                    |\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: not-found
                      details:
                        coding:
                        - system: https://fhir.nhs.uk/STU3/ValueSet/Spine-ErrorOrWarningCode-1
                          code: NO_RECORD_FOUND
                          display: No record found
      tags:
      - Appointment
      operationId: getAppointmentById
      x-operation-id-source: derived
    put:
      summary: Cancel an appointment
      description: Cancel a specific appointment using the appointment id.
      parameters:
      - $ref: '#/components/parameters/BearerAuthorization'
      - $ref: '#/components/parameters/CorrelationID'
      - $ref: '#/components/parameters/RequestID'
      - name: id
        in: path
        description: Appointment logical identifier
        required: true
        schema:
          type: string
        example: '1'
      requestBody:
        description: Appointment
        content:
          application/fhir+json:
            schema:
              type: object
              description: Link to Profile--GPConnect-Appointment-1 resource population guidance [here](https://simplifier.net/guide/gpconnect-data-model/Home/FHIR-Assets/All-assets/Profiles/Profile--GPConnect-Appointment-1?version=current).
            example:
              resourceType: Appointment
              id: '9'
              meta:
                versionId: '636068818095315079'
                profile:
                - https://fhir.nhs.uk/STU3/StructureDefinition/GPConnect-Appointment-1
              extension:
              - url: https://fhir.nhs.uk/STU3/StructureDefinition/Extension-GPConnect-AppointmentCancellationReason-1
                valueString: Free text cancellation reason.
              status: cancelled
              description: Free text description updated.
              start: '2017-05-30T10:00:00+01:00'
              end: '2017-05-30T10:25:00+01:00'
              slot:
              - reference: Slot/1
              created: '2017-05-25T13:48:41+01:00'
              participant:
              - actor:
                  reference: Patient/9000000009
                status: accepted
              - actor:
                  reference: Location/32
                status: accepted
      responses:
        200:
          description: OK
          content:
            application/fhir+json:
              schema:
                type: object
                description: Link to Profile--GPConnect-Appointment-1 resource population guidance [here](https://simplifier.net/guide/gpconnect-data-model/Home/FHIR-Assets/All-assets/Profiles/Profile--GPConnect-Appointment-1?version=current).
              examples:
                example:
                  value:
                    resourceType: Appointment
                    id: '9'
                    meta:
                      versionId: '636068818095315079'
                      profile:
                      - https://fhir.nhs.uk/STU3/StructureDefinition/GPConnect-Appointment-1
                    contained:
                    - resourceType: Organization
                      id: '1'
                      meta:
                        profile:
                        - https://fhir.nhs.uk/STU3/StructureDefinition/CareConnect-GPC-Organization-1
                      identifier:
                      - system: https://fhir.nhs.uk/Id/ods-organization-code
                        value: A00001
                      type:
                      - coding:
                        - system: https://fhir.nhs.uk/STU3/CodeSystem/GPConnect-OrganisationType-1
                          code: gp-practice
                      name: West Road GP Practice
                      telecom:
                      - system: phone
                        value: 0300 303 5678
                    extension:
                    - url: https://fhir.nhs.uk/STU3/StructureDefinition/Extension-GPConnect-BookingOrganisation-1
                      valueReference:
                        reference: '#1'
                    - url: https://fhir.nhs.uk/STU3/StructureDefinition/Extension-GPConnect-AppointmentCancellationReason-1
                      valueString: Free text cancellation reason.
                    - 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
                    - url: https://fhir.nhs.uk/STU3/StructureDefinition/Extension-GPConnect-DeliveryChannel-2
                      valueCode: In-person
                    status: cancelled
                    serviceCategory:
                      text: General GP Appointments
                    serviceType:
                    - text: General GP Appointment
                    description: Free text description updated.
                    start: '2017-05-30T10:00:00+01:00'
                    end: '2017-05-30T10:25:00+01:00'
                    minutesDuration: 10
                    slot:
                    - reference: Slot/1
                    created: '2017-05-25T13:48:41+01:00'
                    comment: Free text comment.
                    participant:
                    - actor:
                        reference: Patient/9000000009
                      status: accepted
                    - actor:
                        reference: Location/32
                      status: accepted
        4XX:
          description: "An error occurred as follows:\n\n| HTTP status | Error code              | Description                                                      |\n| ----------- | ----------              | -----------                                                      |\n| 400         | INVALID_IDENTIFIER_VA   | Invalid identifier value                                         |\n| 400         | BAD_REQUEST             | 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| 403         | ACCESS_DENIED\t          | Practice has disabled cancellation                               |\n| 404         | NO_RECORD_FOUND         | No record found                                                  |\n| 409         | ACCESS_DENIED\t          | Cannot cancel appointment                                        |\n| 461         | ACCESS_DENIED\t          | Too late to cancel appointment                                   |\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: not-found
                      details:
                        coding:
                        - system: https://fhir.nhs.uk/STU3/ValueSet/Spine-ErrorOrWarningCode-1
                          code: NO_RECORD_FOUND
                          display: No record found
      x-codegen-request-body-name: body
      tags:
      - Appointment
      operationId: putAppointmentById
      x-operation-id-source: derived
components:
  parameters:
    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
    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}