Scheduling
Overview
This resource manages appointment scheduling and availability for healthcare organizations. The scheduling system supports booking, updating, rescheduling appointments, and finding available slots across multiple EHR systems.
You can book, reschedule, update appointments, and search for available slots through our platform API, which integrates with Epic and eCW EHR systems.
Supported Integration Options
FHIR R4 integration
HL7 v2.4 integration
API Endpoints
1. Book Appointment (Consumer)
Endpoint: POST /api/patients/:patientId/appointments
Description: Books a new appointment for an authenticated patient.
Authentication: Required (UserAuthMiddleware)
Request Headers:
Authorization: Bearer <token>
organization_code: <org_code>
organizationid: <org_id>Path Parameters:
patientId(string, required): The unique identifier of the patient
Request Body:
Response:
2. Book Appointment (Service Provider)
Endpoint: POST /api/service-provider-scheduling/appointments
Description: Books a new appointment by service providers.
Authentication: Required (ProviderAuthMiddleware)
Request Headers:
Request Body: Same as Consumer endpoint
Response: Same as Consumer endpoint
3. Update Appointment
Endpoint: PUT /api/service-provider-scheduling/appointments/:token
Description: Updates an existing appointment.
Authentication: Required (ProviderAuthMiddleware)
Path Parameters:
token(string, required): The unique token of the appointment
Request Body:
Response:
4. Reschedule Appointment
Endpoint: PUT /api/patients/:patientId/appointments/reschedule
Description: Reschedules an existing appointment.
Authentication: Required (UserAuthMiddleware)
Request Body:
Response:
5. Get Available Slots (Consumer)
Endpoint: GET /api/patients/:patientId/appointments/available-slots
Description: Retrieves available appointment slots.
Authentication: Required (UserAuthMiddleware)
Query Parameters:
appointmentTypeId(string, optional): Filter by appointment typeappointmentTypeTemplateId(string, optional): Filter by appointment type templateserviceProviderId(string, optional): Filter by service providerstartDate(string, required): Start date for availability searchendDate(string, required): End date for availability searchlocationType(string, optional): Filter by location type (VIRTUAL, IN_PERSON, HYBRID)
Response:
6. Get Available Slots with Service Provider Info
Endpoint: GET /api/service-provider-scheduling/available-slots-service-provider-info
Description: Retrieves available appointment slots with detailed service provider information.
Authentication: Required (ProviderAuthMiddleware)
Query Parameters: Same as Get Available Slots
Response:
7. Search Available Slots
Endpoint: POST /api/service-provider-scheduling/available-slots/search
Description: Searches for available appointment slots with advanced filtering.
Authentication: Required (ProviderAuthMiddleware)
Request Body:
Response:
Field Mappings to EHR Systems
Epic FHIR Integration Mapping
id
id
Appointment.id
Unique appointment identifier
appointmentTypeId
appointmentType.coding[0].code
Appointment.appointmentType.coding[0].code
Appointment type code
patientId
participant[0].actor.reference
Appointment.participant[0].actor.reference
Patient reference
startDateTime
start
Appointment.start
Appointment start time
endDateTime
end
Appointment.end
Appointment end time
durationInMinutes
minutesDuration
Appointment.minutesDuration
Duration in minutes
status
status
Appointment.status
Appointment status
priority
priority.coding[0].code
Appointment.priority.coding[0].code
Priority level
note
comment
Appointment.comment
Appointment notes
serviceProviderId
participant[1].actor.reference
Appointment.participant[1].actor.reference
Provider reference
token
identifier[0].value
Appointment.identifier[0].value
External identifier
timeZone
extension[0].valueString
Appointment.extension[0].valueString
Time zone extension
attributes.chiefComplaint
reasonCode[0].text
Appointment.reasonCode[0].text
Chief complaint
attributes.billingNotes
extension[1].valueString
Appointment.extension[1].valueString
Billing notes extension
Epic FHIR Integration Notes:
Uses FHIR R4 Appointment resource
Patient and provider references use format "Patient/{id}" and "Practitioner/{id}"
Status values mapped: BOOKED→confirmed, CANCELLED→cancelled, COMPLETED→fulfilled
Priority values mapped: HIGH→urgent, MEDIUM→routine, LOW→asap
Custom extensions used for platform-specific fields
eCW HL7 Integration Mapping
id
SCH.1
SCH
Appointment ID
externalId
SCH.2
SCH
External appointment ID
attributes.chiefComplaint
SCH.7
SCH
Chief complaint
appointmentTypeId
SCH.8
SCH
Appointment type external ID
durationInMinutes
SCH.9
SCH
Duration in minutes
startDateTime
SCH.11.1
SCH
Start date/time (YYYYMMDDHHMMSS)
endDateTime
SCH.11.2
SCH
End date/time (YYYYMMDDHHMMSS)
attributes.billingNotes
SCH.24
SCH
Billing notes
status
SCH.25
SCH
Appointment status
patientId
PID.3
PID
Patient ID
patientExternalId
PID.2
PID
Patient external ID
firstName
PID.5.2
PID
Patient first name
lastName
PID.5.1
PID
Patient last name
birthDate
PID.7
PID
Patient birth date
gender
PID.8
PID
Patient gender (M/F/O/U)
serviceProviderId
PV1.7.1
PV1
Provider ID
serviceProviderLastName
PV1.7.2
PV1
Provider last name
serviceProviderFirstName
PV1.7.3
PV1
Provider first name
facilityId
PV1.3.1
PV1
Facility ID
facilityName
PV1.3.2
PV1
Facility name
token
PV1.19
PV1
Appointment token
startDateTime
PV1.43
PV1
Start date/time
externalId
PV1.50
PV1
External appointment ID
eCW HL7 Integration Notes:
Uses SIU^S12 message type for appointment creation
Uses SIU^S13 message type for appointment updates
Uses SIU^S14 message type for appointment cancellation
Date/time format: YYYYMMDDHHMMSS (e.g., 20230715050000)
Gender mapping: MALE→M, FEMALE→F, OTHERS→O, default→U
Status mapping: CANCELLED→CANC, default→PEN
Facility mapping based on organization configuration
Group appointments use default provider (ID: 13155)
Examples
Book Appointment
Update Appointment
Reschedule Appointment
Get Available Slots
Search Available Slots
Last updated