Skip to main content
The Appointment resource represents a scheduled healthcare event between patient(s) and practitioner(s). OmniEHR implements a 15-minute slot-based booking system with conflict detection.

​
Endpoints

​
Create Appointment

Admin can book for any practitioner. Practitioners can only book their own appointments.
POST /api/fhir/Appointment
Authorization: Bearer {token}
Content-Type: application/json
​
resourceType
string
required
Must be "Appointment"
​
status
string
required
proposed, pending, booked, arrived, fulfilled, cancelled, noshow, entered-in-error, checked-in, waitlist
​
serviceCategory
array
Category of appointment (Outpatient, Follow-up, etc.)
​
appointmentType
object
Type of appointment
​
reasonCode
array
Reason for appointment
​
description
string
Brief description of the appointment
​
start
string
required
Start time (must be on 15-minute boundary, 09:00-12:00, Mon-Sat)
​
end
string
required
End time (must be 15 minutes after start)
​
minutesDuration
number
Must be 15
​
participant
array
required
Patient and practitioner references
​
comment
string
Additional comments

​
Example Request

cURL
curl -X POST https://api.example.com/api/fhir/Appointment \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "resourceType": "Appointment",
    "status": "booked",
    "serviceCategory": [{
      "coding": [{
        "system": "http://terminology.hl7.org/CodeSystem/service-category",
        "code": "1",
        "display": "Outpatient"
      }]
    }],
    "appointmentType": {
      "coding": [{
        "system": "http://terminology.hl7.org/CodeSystem/v2-0276",
        "code": "ROUTINE",
        "display": "Routine appointment"
      }]
    },
    "description": "Annual physical examination",
    "start": "2024-03-20T10:00:00Z",
    "end": "2024-03-20T10:15:00Z",
    "minutesDuration": 15,
    "participant": [
      {
        "actor": {
          "reference": "Patient/65f1234567890abcdef12345"
        },
        "status": "accepted"
      },
      {
        "actor": {
          "reference": "Practitioner/65f9876543210abcdef98765"
        },
        "status": "accepted"
      }
    ],
    "comment": "Patient requests Dr. Smith"
  }'

​
Response

{
  "resourceType": "Appointment",
  "id": "65f7890123456abcdef78901",
  "status": "booked",
  "start": "2024-03-20T10:00:00Z",
  "end": "2024-03-20T10:15:00Z",
  "minutesDuration": 15,
  "participant": [
    {
      "actor": {
        "reference": "Patient/65f1234567890abcdef12345"
      },
      "status": "accepted"
    },
    {
      "actor": {
        "reference": "Practitioner/65f9876543210abcdef98765"
      },
      "status": "accepted"
    }
  ]
}

​
List Appointments

GET /api/fhir/Appointment
Authorization: Bearer {token}
​
date
string
Filter by appointment date (YYYY-MM-DD format)
​
practitioner
string
Filter by practitioner: Practitioner/{id}
​
patient
string
Filter by patient: Patient/{id}
​
status
string
Filter by status

​
Example Request

curl -X GET "https://api.example.com/api/fhir/Appointment?date=2024-03-20&practitioner=Practitioner/65f9876543210abcdef98765" \
  -H "Authorization: Bearer YOUR_TOKEN"

​
Get Appointment by ID

GET /api/fhir/Appointment/:id
Authorization: Bearer {token}

​
Update Appointment

Updates are subject to the same scheduling rules: 15-minute slots, 09:00-12:00, Mon-Sat, no conflicts.
PUT /api/fhir/Appointment/:id
Authorization: Bearer {token}
Content-Type: application/json

​
Scheduling Rules

All appointments must follow these rules:
  • Duration: Exactly 15 minutes
  • Time slots: Must start on 15-minute boundaries (09:00, 09:15, 09:30, etc.)
  • Hours: 09:00 AM - 12:00 PM only
  • Days: Monday through Saturday
  • Conflicts: Practitioner must be available (no overlapping bookings)

​
Appointment Statuses

StatusDescriptionBlocks Slot?
proposedAppointment is proposed❌
pendingWaiting for confirmation❌
bookedConfirmed appointment✅
arrivedPatient has arrived✅
fulfilledAppointment completed✅
cancelledAppointment cancelled❌
noshowPatient didn’t show❌
entered-in-errorCreated by mistake❌

​
Service Categories

Outpatient

Regular outpatient visits

Follow-up

Follow-up appointments

Preventive Care

Wellness and screening

Acute Care

Urgent care visits

Chronic Management

Ongoing condition management

Specialist Referral

Specialist consultations

​
Role Permissions

RoleCreateReadUpdateScope
Admin✅✅✅All practitioners
Practitioner✅✅✅Own schedule only
Auditor❌✅❌All appointments

​
Error Responses

StatusErrorDescription
400Invalid slotTime not on 15-min boundary or outside 09:00-12:00
409Practitioner unavailableOverlapping appointment exists
403Permission deniedPractitioner trying to book for another practitioner

Build docs developers (and LLMs) love

Get started for freeTalk to us