Creating Appointment
How
Assign the Appointment resource a logical id.
If the Appointment requires a Privacy label other then General Health, provide the relevant code in the security field.
An additional tracking identifier must be provided for every appointment.
Note: system + value are mandatory
Encounter class of the appointment can be provided via an extension, using standard codes and an appropriate display label.
Note: this is a requirement if you are using PKB for the NHS Wayfinder programme.
Booking Team contact details can be provided using the PKB “spoc” extension http://fhir.patientsknowbest.com/structuredefinition/spoc
Supports sending of an email address, phone number, phone extension, notes.
Date the Appointment was recorded can be supplied, extension http://fhir.patientsknowbest.com/structuredefinition/recorded-date
Status of the appointment must be included. See the FHIR R4 spec for the status value set.
Subject (as mapped in PKB) in the appointment
appointmentTypefield should aways be supplied.It displays prominently as the appointment “title” in the PKB interface and should therefore be meaningful to users.
The subject should clearly identify the reason for and nature of the appointment. This includes specifying if it is a virtual (online) or telephone appointment
If not supplied, PKB will default to displaying “Appointment”
Start and end time are both required. They must always be provided with the correct UTC offset.
In exceptional circumstances a data absent reason extension can be sent if there is no known end timestamp.
If providing the Specialty and Service Type. For UK-based integrations:
The
specialtyfield identifies the clinical specialty of the practitioner or the clinic.Primary Coding System: Use SNOMED CT (
http://snomed.info/sct) for maximum interoperability.NHS Mapping: If your internal system uses 3-digit NHS Specialty Codes (e.g.,
100for General Medicine), these should be mapped to their corresponding SNOMED concept IDs.Requirement: Provide at least one
codingwith asystem,code, and a human-readabledisplay.
Service Type (
serviceType)The
serviceTypefield identifies the specific type of service being performed (e.g., "Physiotherapy" or "Cardiology").Primary Coding System: Use the HL7 ServiceType CodeSystem (
http://terminology.hl7.org/CodeSystem/service-type).Granularity: While
specialtyis broad (e.g., Cardiology),serviceTypecan be more specific (e.g., "Echocardiography service").Requirement: Provide at least one
codingwith asystem,code, and a human-readabledisplay.
Comment field is used for detailed patient instructions. To ensure professional rendering, follow these formatting guidelines:
HTML Support: Use
<b>for bolding,<p>for paragraphs, and<a>for clickable links.Control Characters: Unicode characters below 32 are prohibited, with three specific exceptions: Horizontal Tab (U+0009), Line Feed (U+0010), and Carriage Return (U+0013).
Fallback Layout: Include
\nor\r\nalongside HTML tags. This ensures that even if a UI strips the HTML, the text remains readable and correctly spaced.
Participants
Patient Reference : You must reference the logical id of a previously created Patient resource in the participant field.
Practitioner: reference the logical id of a previously created Practitioner (the doctor / nurse / consultant) resource in the participant field.
Include the role in brackets within the
displayfield
Location: must be supplied in the
displayfieldLocation information should make it clear to the patient exactly where they need to attend.
Appointment Creation Example
{
"resourceType": "Appointment",
"id": "apt98765432",
"meta": {
"security": [
{
"system": "http://fhir.patientsknowbest.com/codesystem/privacy-label",
"code": "MENTAL_HEALTH"
}
]
},
"identifier": [
{
"use": "official",
"system": "http://hospital-abc.nhs.uk/ids/appointment",
"value": "EXT-98765432"
}
],
"extension": [
{
"url": "http://hl7.org/fhir/StructureDefinition/encounter-class",
"valueCoding": {
"system": "http://terminology.hl7.org/CodeSystem/v3-ActCode",
"code": "AMB",
"display": "outpatient"
}
},
{
"url": "http://fhir.patientsknowbest.com/structuredefinition/spoc",
"extension": [
{
"url": "http://fhir.patientsknowbest.com/structuredefinition/spoc-email",
"valueString": "contactus@help.com"
},
{
"url": "http://fhir.patientsknowbest.com/structuredefinition/spoc-phone",
"valueString": "123 456 789"
},
{
"url": "http://fhir.patientsknowbest.com/structuredefinition/spoc-phone-extension",
"valueString": "11"
},
{
"url": "http://fhir.patientsknowbest.com/structuredefinition/spoc-note",
"valueString": "Open only on Mondays"
}
]
},
{
"url": "http://fhir.patientsknowbest.com/structuredefinition/recorded-date",
"valueDateTime": "2026-04-30T12:00:00+01:00"
}
],
"status": "booked",
"description": "Initial Cardiology Consultation",
"start": "2026-05-25T14:30:00+01:00",
"end": "2026-05-25T15:30:00+01:00",
"appointmentType": {
"coding": [
{
"display": "Cardiology Appointment"
}
]
},
"specialty": [
{
"coding": [
{
"system": "http://snomed.info/sct",
"code": "394579002",
"display": "Cardiology"
}
]
}
],
"serviceType": [
{
"coding": [
{
"system": "http://terminology.hl7.org/CodeSystem/service-type",
"code": "124",
"display": "Cardiology"
}
]
}
],
"comment": "<b>APPOINTMENT SUMMARY</b>\r\n<p>Please note the following requirements:</p>\r\n\t• Bring your ID\r\n\t• Arrive early\r\n\t• Wear a mask\r\n\r\n<p>Contact us if you have any questions.</p>",
"participant": [
{
"actor": {
"reference": "Patient/AECP12345"
},
"status": "accepted"
},
{
"actor": {
"reference": "Practitioner/staff-id-9988",
"display": "Dr Jones (Doctor)"
},
"status": "accepted"
},
{
"actor": {
"display": "Room 10, The Cardiology Centre, Hospital ABC, SW1",
"type": "Location"
},
"status": "accepted"
}
]
}