Skip to main content

Appointment

Overview​

The Appointment resource represents a booking of a healthcare event among patient(s), practitioner(s), related person(s), and/or device(s) for a specific date/time. This may result in one or more Encounter(s).

Purpose:

  • Schedule healthcare appointments
  • Coordinate patient and provider availability
  • Track appointment status and participation
  • Support appointment workflows (booking, confirmation, cancellation)

Use Cases:

  • Scheduling patient visits (office visits, telehealth, procedures)
  • Managing appointment requests and confirmations
  • Tracking appointment status changes (booked, arrived, fulfilled, cancelled)
  • Coordinating multiple participants for appointments

Relationships:

  • References Patient resources for appointment subjects
  • References Practitioner/PractitionerRole for healthcare providers
  • References Location for appointment venues
  • May reference Slot resources for scheduling
  • Can create Encounter resources when appointments are fulfilled

Resource Schema​

Key Fields​

FieldTypeDescription
resourceTypestringAlways "Appointment"
idstringUnique identifier for the appointment
statuscodeproposed | pending | booked | arrived | fulfilled | cancelled | noshow | entered-in-error | checked-in | waitlist
appointmentTypeCodeableConceptThe style of appointment or patient that has been booked
serviceTypeCodeableReference[]The specific service to be performed
specialtyCodeableConcept[]The specialty of a practitioner required
descriptionstringShown on a subject line in a meeting request
startinstantWhen appointment is to take place
endinstantWhen appointment is to conclude
minutesDurationpositiveIntDuration in minutes
participantBackboneElement[]Participants involved in appointment
participant.actorReferenceIndividual, device, location, or service participating
participant.requiredbooleanWhether participant is required to attend
participant.statuscodeaccepted | declined | tentative | needs-action

JSON Example​

{
  "resourceType": "Appointment",
  "id": "appointment-123",
  "meta": {
    "profile": [
      "http://hl7.org/fhir/us/core/StructureDefinition/us-core-appointment"
    ]
  },
  "status": "booked",
  "appointmentType": {
    "coding": [
      {
        "system": "http://terminology.hl7.org/CodeSystem/v2-0276",
        "code": "ROUTINE",
        "display": "Routine appointment"
      }
    ]
  },
  "serviceType": [
    {
      "concept": {
        "coding": [
          {
            "system": "http://snomed.info/sct",
            "code": "11429006",
            "display": "Consultation"
          }
        ]
      }
    }
  ],
  "description": "Follow-up appointment",
  "start": "2024-03-15T10:00:00Z",
  "end": "2024-03-15T10:30:00Z",
  "minutesDuration": 30,
  "participant": [
    {
      "actor": {
        "reference": "Patient/patient-123",
        "display": "John Smith"
      },
      "required": true,
      "status": "accepted"
    },
    {
      "actor": {
        "reference": "Practitioner/practitioner-456",
        "display": "Dr. Jane Doe"
      },
      "required": true,
      "status": "accepted"
    },
    {
      "actor": {
        "reference": "Location/location-789",
        "display": "Clinic Room 101"
      },
      "required": true,
      "status": "accepted"
    }
  ]
}

Operations​

The Appointment resource supports Read, Search, Create, and Update operations. Note: No CareRecord solutions currently support this resource.

CareRecord / SolutionCreateReadUpdateSearch
GEHRIMEDYesYesYesYes
myAvatarYesYesYesYes
myEvolvYesYesYesYes
myUnityYesYesYesYes
TheraOfficeYesYesYesYes

Read​

Retrieve a specific Appointment resource by its ID.

GET /Appointment/{id}

The Appointment resource supports searching by patient, date, status, and other parameters.

Patient-based Search:

ParameterTypeRequiredDescriptionExample
patientreferenceYesThe patient for whom the appointment is scheduledpatient=Patient/patient-123
datedateNoAppointment date/timedate=ge2024-01-01
statustokenNoThe overall status of the appointmentstatus=booked
_lastUpdateddateNoOnly return resources which were last updated as specified by the given range_lastUpdated=ge2024-01-01
_revincludespecialNoInclude Provenance resource(s) that reference the matched search results. Allowed: "Provenance:target"_revinclude=Provenance:target

ID-based Search:

ParameterTypeRequiredDescriptionExample
_idtokenYesThe ID of the resource_id=appointment-123
_lastUpdateddateNoOnly return resources which were last updated as specified by the given range_lastUpdated=ge2024-01-01
_revincludespecialNoInclude Provenance resource(s) that reference the matched search results. Allowed: "Provenance:target"_revinclude=Provenance:target

Create​

Create a new Appointment resource.

POST /Appointment

Update​

Update an existing Appointment resource by its ID.

PUT /Appointment/{id}

Examples​

Read​

Retrieve a specific Appointment resource by its ID.

GET /Appointment/{id}

Search​

Via POST (Recommended)​

Search by Patient
curl -X POST https://fhir.netsmartcloud.com/provider/patient-access/v2/{tenant-id}/Appointment/_search \
    -H "Accept: application/fhir+json" \
    -H "Content-Type: application/x-www-form-urlencoded" \
    -d "patient=Patient/patient-123"
Search by Patient and Status
curl -X POST https://fhir.netsmartcloud.com/provider/patient-access/v2/{tenant-id}/Appointment/_search \
    -H "Accept: application/fhir+json" \
    -H "Content-Type: application/x-www-form-urlencoded" \
    -d "patient=Patient/patient-123&status=booked"

Via GET​

Search by Patient
curl https://fhir.netsmartcloud.com/provider/patient-access/v2/{tenant-id}/Appointment?patient=Patient/patient-123 \
    -H "Accept: application/fhir+json"
Search by Patient and Date
curl https://fhir.netsmartcloud.com/provider/patient-access/v2/{tenant-id}/Appointment?patient=Patient/patient-123&date=ge2024-01-01 \
    -H "Accept: application/fhir+json"

Create​

Create Appointment
curl -X POST https://fhir.netsmartcloud.com/provider/patient-access/v2/{tenant-id}/Appointment \
    -H "Accept: application/fhir+json" \
    -H "Content-Type: application/fhir+json" \
    -d '{
  "resourceType": "Appointment",
  "status": "booked",
  "start": "2024-03-15T10:00:00Z",
  "end": "2024-03-15T10:30:00Z",
  "participant": [
    {
      "actor": { "reference": "Patient/patient-123" },
      "status": "accepted"
    }
  ]
}'

Update​

Update Appointment
curl -X PUT https://fhir.netsmartcloud.com/provider/patient-access/v2/{tenant-id}/Appointment/{id} \
    -H "Accept: application/fhir+json" \
    -H "Content-Type: application/fhir+json" \
    -d '{
  "resourceType": "Appointment",
  "id": "{id}",
  "status": "booked",
  "start": "2024-03-15T10:00:00Z",
  "end": "2024-03-15T10:30:00Z",
  "participant": [
    {
      "actor": { "reference": "Patient/patient-123" },
      "status": "accepted"
    }
  ]
}'

Integration Patterns​

Common Workflows​

  1. Appointment Scheduling

    • Search for available slots
    • Create appointment with proposed status
    • Update to booked when confirmed

  2. Appointment Check-in

    • Update status to arrived when patient checks in
    • Update status to fulfilled when appointment is completed

  3. Appointment Cancellation

    • Update status to cancelled
    • Include cancellation reason if applicable

Error Handling​

For common error scenarios and troubleshooting guidance, see Common Errors.

Supported Profiles​