Retrieve a patient's appointment schedule

You can use this API action to look up a specific patient’s scheduled appointments. Typically, you can use this for: 

  • sending reminders to patients for scheduled appointments;
  • prompting patients to schedule appointments routine appointments (e.g., annual physicals); 
  • scheduling follow-up appointments for a patient; or
  • reviewing historical appointments for a patient.

Essentially, this API action is for chronic management of a patient, not for urgent or dynamic scheduling. 

Also, keep in mind that this API action is different than looking up a provider's schedule to make patient appointments.

Supported systems

You can use this API action with the Redox FHIR® API.

Your connection's system can return results with their own FHIR® or query-based API. 

Things you need to know

Action steps

Retrieve appointments by patient identifier

You can search for appointments for a specific patient if you already have the patient identifier. This is one possible search method, but you could combine the query parameters from this step with those in other steps to refine your search even more.

This table has notes about how to use parameters for this action step specifically, but it's not exhaustive. Refer to the Appointment resource schema for more details.

Query parameter
Required for this step
Notes
patient.identifier
Y
You must include at least one identifier for the patient that's used by the EHR system you're querying.

Your search returns a list of scheduled appointments for one patient at one organization.

Appointment/_search
curl 'https://api.redoxengine.com/fhir/R4/redox-fhir-sandbox/Development/Appointment/_search' \
--request POST \
--header 'Authorization: Bearer ${API_TOKEN}' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'patient=Patient/81c2f5eb-f99f-40c4-b504-59483e6148d7'
{
"id": "22cd2bca-8cf7-4b74-a26b-0e8941c37d84",
"type": "searchset",
"entry": [
{
"search": {
"mode": "match",
"score": 1
},
"resource": {
"id": "194414ff-46bf-4fd2-aa37-c58f3884f0de",
"end": "2022-10-15T10:15:00.000Z",
"meta": {
"lastUpdated": "2022-10-19T20:28:45.479Z"
},
"start": "2022-10-15T10:00:00.000Z",
"reason": [
{
"text": "Check up"
}
],
"status": "booked",
"identifier": [
{
"value": "991100112233",
"system": "urn:redox:redox-fhir-sandbox:VIS",
"extension": [
{
"url": "https://fhir.redoxengine.com/StructureDefinition/identifier-origin",
"valueString": "RedoxAPI"
}
]
}
],
"participant": [
{
"actor": {
"reference": "Patient/81c2f5eb-f99f-40c4-b504-59483e6148d7"
},
"status": "accepted"
},
{
"type": [
{
"text": "ATND",
"coding": [
{
"code": "ATND",
"system": "http://terminology.hl7.org/CodeSystem/v3-ParticipationType",
"display": "attender"
}
]
}
],
"actor": {
"reference": "Practitioner/dbed0f85-e3cd-47ac-9305-3f629e138832"
},
"status": "accepted"
},
{
"actor": {
"reference": "Location/ed4afd58-9796-4cc5-aed7-5c47345acec9"
},
"status": "accepted"
},
{
"actor": {
"reference": "Location/7fc98699-9108-46c1-958e-ec5419f6ebfd"
},
"status": "accepted"
}
],
"resourceType": "Appointment",
"minutesDuration": 15
}
}
],
"total": 1,
"resourceType": "Bundle"
}

Retrieve appointments by location

You can also search for appointments by location if you want to search a specific facility. This is one possible search method, but you could combine the query parameters from this step with those in other steps to refine your search even more.

This table has notes about how to use parameters for this action step specifically, but it's not exhaustive. Refer to the Appointment resource schema for more details.

Query parameter
Required for this step
Notes
location
Y
You must include the facility code of the location you want to search.

Your search returns a list of scheduled appointments for the specified location of one organization.

Appointment/_search
curl 'https://api.redoxengine.com/fhir/R4/redox-fhir-sandbox/Development/Appointment/_search' \
--request POST \
--header 'Authorization: Bearer ${API_TOKEN}' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'location=Location/ed4afd58-9796-4cc5-aed7-5c47345acec9'
{
"id": "2bdd0020-f553-45cc-bedc-6061b36abb80",
"resourceType": "Bundle",
"type": "searchset",
"entry": [
{
"resource": {
"resourceType": "Appointment",
"id": "194414ff-46bf-4fd2-aa37-c58f3884f0de",
"status": "booked",
"participant": [
{
"actor": {
"reference": "Patient/81c2f5eb-f99f-40c4-b504-59483e6148d7"
},
"status": "accepted"
},
{
"type": [
{
"text": "ATND",
"coding": [
{
"code": "ATND",
"system": "http://terminology.hl7.org/CodeSystem/v3-ParticipationType",
"display": "attender"
}
]
}
],
"actor": {
"reference": "Practitioner/dbed0f85-e3cd-47ac-9305-3f629e138832"
},
"status": "accepted"
},
{
"actor": {
"reference": "Location/ed4afd58-9796-4cc5-aed7-5c47345acec9"
},
"status": "accepted"
},
{
"actor": {
"reference": "Location/7fc98699-9108-46c1-958e-ec5419f6ebfd"
},
"status": "accepted"
}
],
"identifier": [
{
"value": "991100112233",
"system": "urn:redox:redox-fhir-sandbox:VIS",
"extension": [
{
"url": "https://fhir.redoxengine.com/StructureDefinition/identifier-origin",
"valueString": "RedoxAPI"
}
]
}
],
"reason": [
{
"text": "Check up"
}
],
"start": "2022-10-15T10:00:00.000Z",
"end": "2022-10-15T10:15:00.000Z",
"minutesDuration": 15,
"meta": {
"lastUpdated": "2022-10-19T20:28:45.479Z"
}
},
"search": {
"mode": "match",
"score": 1
}
}
],
"total": 1
}

Retrieve appointments by provider

You can search for appointments by provider if you want to search a specific provider's appointments. This is one possible search method, but you could combine the query parameters from this step with those in other steps to refine your search even more.

This table has notes about how to use parameters for this action step specifically, but it's not exhaustive. Refer to the Appointment resource schema for more details.

Query parameter
Required for this step
Notes
practitioner
Y
You must include the practitioner ID of the provider you want to retrieve appointments for.

Your search returns a list of scheduled appointments for the specified provider.

Appointment/_search
curl 'https://api.redoxengine.com/fhir/R4/redox-fhir-sandbox/Development/Appointment/_search' \
--request POST \
--header 'Authorization: Bearer ${API_TOKEN}' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'practitioner=Practitioner/dbed0f85-e3cd-47ac-9305-3f629e138832'
{
"id": "b76797f1-cf3d-4584-a6d3-69d14373a375",
"resourceType": "Bundle",
"type": "searchset",
"entry": [
{
"resource": {
"resourceType": "Appointment",
"id": "194414ff-46bf-4fd2-aa37-c58f3884f0de",
"status": "booked",
"participant": [
{
"actor": {
"reference": "Patient/81c2f5eb-f99f-40c4-b504-59483e6148d7"
},
"status": "accepted"
},
{
"type": [
{
"text": "ATND",
"coding": [
{
"code": "ATND",
"system": "http://terminology.hl7.org/CodeSystem/v3-ParticipationType",
"display": "attender"
}
]
}
],
"actor": {
"reference": "Practitioner/dbed0f85-e3cd-47ac-9305-3f629e138832"
},
"status": "accepted"
},
{
"actor": {
"reference": "Location/ed4afd58-9796-4cc5-aed7-5c47345acec9"
},
"status": "accepted"
},
{
"actor": {
"reference": "Location/7fc98699-9108-46c1-958e-ec5419f6ebfd"
},
"status": "accepted"
}
],
"identifier": [
{
"value": "991100112233",
"system": "urn:redox:redox-fhir-sandbox:VIS",
"extension": [
{
"url": "https://fhir.redoxengine.com/StructureDefinition/identifier-origin",
"valueString": "RedoxAPI"
}
]
}
],
"reason": [
{
"text": "Check up"
}
],
"start": "2022-10-15T10:00:00.000Z",
"end": "2022-10-15T10:15:00.000Z",
"minutesDuration": 15,
"meta": {
"lastUpdated": "2022-10-19T20:28:45.479Z"
}
},
"search": {
"mode": "match",
"score": 1
}
}
],
"total": 1
}