# This is an OpenAPI Specification (https://swagger.io/specification/) # for gp-connect/patient-facing/appointments-management-fhir/FHIR/STU3 owned by NHS Digital (https://digital.nhs.uk/) openapi: '3.0.0' info: title: 'gp-connect/patient-facing/appointments-management-fhir/FHIR/STU3' version: 'Computed and injected at build time by `scripts/set_version.py`' description: | ## Overview ![Appointments Overview](https://raw.githubusercontent.com/NHSDigital/gp-connect-appointments-management-fhir/master/specification/diagrams/GP-Connect-PFS-Appointment-Management.svg) Use this API to book and manage patient appointments at their GP practice. You can: - search for free slots - book an appointment - retrieve a patient’s appointments - get details of a single appointment - cancel an appointment You cannot: - amend a patient's appointments beyond cancelling - re-schedule a patient's appointments (this must be done by cancelling and re-booking) To use this API, the end user must be a patient who is: - registered with the GP practice - registered with NHS login to P9 identity verification level ## Who can use this API This API can be used by developers of clinical systems. It is a patient-facing API. This API: - is only intended for use by patient-facing applications - can only be used where there is a legal basis to do so Make sure you have a valid use case before you go too far with your development. To do this, contact us. You must do this before you can go live (see 'Onboarding' below). ### Prerequisites #### Information governance (IG) You must: - be compliant with the GP Connect Direct Care API Information Governance Model. - be using the GP Connect APIs for direct care purposes for NHS patients in England #### Clinical safety You must: - have a clinical safety officer (CSO) who is responsible for DCB0129 and, if necessary, DCB0160. For more on clinical risk management, visit Clinical risk management standards. If you are confident that you can meet the prerequisites, contact us to express your interest. See 'Onboarding' below. ## Related APIs The following APIs are related to this API: - [GP Connect Access 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. - [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. - [GP Connect Access Record: Structured - FHIR API](https://digital.nhs.uk/developer/api-catalogue/gp-connect-access-record-structured-fhir) - retrieve structured information from a patient's GP practice record. - [GP Connect Appointment Management - FHIR API](https://digital.nhs.uk/developer/api-catalogue/gp-connect-appointment-management-fhir) - manage GP practice appointments between different systems. - [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. - [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. - [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. - [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. ## API status and roadmap This API is in [development](https://digital.nhs.uk/developer/guides-and-documentation/reference-guide#statuses). ## Service level This API is a silver service, meaning it is operational 24 hours a day, 365 days a year but only supported during business hours (8am to 6pm), Monday to Friday excluding bank holidays. For more details, see [service levels](https://digital.nhs.uk/developer/guides-and-documentation/reference-guide#service-levels). ## Technology This API is a FHIR API. It sends a FHIR STU3 payload. For more details, see [FHIR](https://digital.nhs.uk/developer/guides-and-documentation/our-api-technologies#fhir). ## Network access This API is available on the internet and indirectly over HSCN. For more details, see [Network access for APIs](https://digital.nhs.uk/developer/guides-and-documentation/network-access-for-apis). ## Security and authorisation This 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. The end user must be: - a patient - authenticated with NHS login to P9 identity verification level The 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: - [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) You 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. ## Environments and testing | Purpose | URL | | ------- | --- | | Sandbox | `https://sandbox.api.service.nhs.uk/gp-connect/patient-facing/appointments-management-fhir/FHIR/STU3` | Integration test | Not yet available | | Production | Not yet available | ### Sandbox testing (not yet available) Our [sandbox environment](https://digital.nhs.uk/developer/guides-and-documentation/testing#sandbox-testing): - is for early developer testing - only covers a limited set of scenarios - is stateless, so it does not store data - is open access, so does not allow you to test authorisation For more details on sandbox testing, or to try out the sandbox using our "Try this API" feature, see the documentation for each endpoint. Alternatively, you can try out the sandbox using our Postman collection: [![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) ### Integration testing (not yet available) Our [integration test environment](https://digital.nhs.uk/developer/guides-and-documentation/testing#integration-testing): - is for formal integration testing - is stateful, so it does persist data - includes authorisation For more details see [integration testing with our RESTful APIs](https://digital.nhs.uk/developer/guides-and-documentation/testing#integration-testing-with-our-restful-apis). ## Errors We use standard HTTP status codes to show whether an API request succeeded or not. They are usually in the range: - 200 to 299 if it succeeded, including code 202 if it was accepted by an API that needs to wait for further action - 400 to 499 if it failed because of a client error by your application - 500 to 599 if it failed because of an error on our server Errors 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. API Specific errors can be found [here.](https://simplifier.net/guide/pfs-appointments/guides-pfs-appointments-home-build-error-handling?version=current) ## Onboarding This API is not yet available for onboarding. ### Expressing an interest If you meet the prerequisites and have a product that can integrate with GP Connect, you should express an interest with us by submitting a use case. The main purpose of the use case is to help us understand how you plan to use GP Connect APIs and the business issue you are looking to address. You should email your use case to us at gpconnect@nhs.net. Your use case should include the following information as a minimum: - the business problem you are intending to solve using GP wConnect - how GP Connect will be used in practice to benefit patients and staff - which of the GP Connect products you will use to benefit patients and staff - any end user organisations you are currently working with - who your clinical safety officer is and, where available, your clinical risk management process documentation Once we receive your use case, we'll respond within 14 days. ### Consumer assurance process Once we approve your use case, we support you through the assurance process to go live. We will discuss the assurance process and artefacts with you to help you understand our requirements. Start your development work within 6 months of use case approval. If you miss this date, a review or new submission of the use case will be required. Changes or additional development will also require a review or new use case submission. 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 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} 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/ 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: | HTTP status | Error code | Description | | ----------- | ---------- | ----------- | | 400 | INVALID_IDENTIFIER_VALUE | 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 | | 403 | ACCESS_DENIED | Access denied | | 404 | NO_RECORD_FOUND | No record found | | 422 | INVALID RESOURCE | Submitted resource is invalid | | 422 | INVALID PARAMETER | Submitted parameter is invalid | 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 /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: - 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 /Patient/{id}/Appointment: get: summary: Read a patient's appointments description: Retrieve all appointments for the patient within a defined time-frame. parameters: - $ref: "#/components/parameters/BearerAuthorization" - $ref: "#/components/parameters/CorrelationID" - $ref: "#/components/parameters/RequestID" - name: id in: path description: The patient's NHS number. The primary identifier of a patient, unique within NHS England and Wales. Always 10 digits and must be a [valid NHS number](https://www.datadictionary.nhs.uk/attributes/nhs_number.html). required: true schema: type: string example: '9000000009' - name: start in: query description: Appointment start/end dates. Default values show a query for appointments on or after 2020-05-09 and on or before 2020-05-19. required: true style: form explode: true schema: type: array items: type: string default: ["ge2020-05-09","le2020-05-19"] - 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 - name: past-appt-limit in: query description: Number of past appointments to return in query, starting at the date given in the "le" portion of the start parameter and working backwards. Parameter is optional, if no value supplied then no limits are applied. required: false schema: type: string example: '5' - name: status in: query description: > The type of status to search: you can find valid values [here](https://simplifier.net/packages/hl7.fhir.r4.core/4.0.1/files/83480) required: false schema: type: string example: 'proposed' 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: $ref: "components/examples/PatientAppointment.yaml" 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 | | 403 | ACCESS_DENIED | Access denied | | 404 | NO_RECORD_FOUND | No record found | 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 /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: | 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 | | 403 | ACCESS_DENIED | Access denied | | 404 | NO_RECORD_FOUND | No record found | 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 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: | 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 | | 403 | ACCESS_DENIED | Access denied | | 403 | ACCESS_DENIED | Practice has disabled cancellation | | 404 | NO_RECORD_FOUND | No record found | | 409 | ACCESS_DENIED | Cannot cancel appointment | | 461 | ACCESS_DENIED | Too late to cancel appointment | 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 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' RoleId: in: header name: NHSD-Session-URID description: | The user role ID (URID) for the current session. Also known as a user role profile ID (URPID). If you are using User-restricted RESTful APIs - NHS login separate authentication and authorisation, see [determine the user's role](https://digital.nhs.uk/developer/guides-and-documentation/security-and-authorisation/user-restricted-restful-apis-nhs-cis2-separate-authentication-and-authorisation#step-9-determine-the-user-s-role) for guidance. This field is optional. required: false schema: type: string pattern: '^[0-9]+$' example: '555254240100' 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