Retrieve a patient's appointment schedule

Last updated: May 22, 2024
IMPLEMENTATION
HEALTH TECH VENDOR
PRODUCT OWNER

You can use this API action to look up a specific patient’s scheduled appointments.

Use cases

This API action may be a good fit for your organization if you perform any of these use cases:

  • Send reminders to patients for scheduled appointments.
  • Prompt patients to schedule routine appointments (e.g., annual physicals).
  • Schedule follow-up appointments for a patient.
  • Review historical appointments for a patient.

So, you can think about using this for chronic management of a patient, not for urgent or dynamic scheduling. 

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 schema for more details.

Query parameter
Required for this step
Notes
patient.identifier
Y
You must include at least one identifier that the EHR system uses.

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

Appointment/_search
Query
bash
1
curl 'https://api.redoxengine.com/fhir/R4/redox-fhir-sandbox/Development/Appointment/_search' \
2
--request POST \
3
--header 'Authorization: Bearer ${API_TOKEN}' \
4
--header 'Content-Type: application/x-www-form-urlencoded' \
5
--data-urlencode 'patient=Patient/81c2f5eb-f99f-40c4-b504-59483e6148d7'
Response
json
1
{
2
"id": "22cd2bca-8cf7-4b74-a26b-0e8941c37d84",
3
"type": "searchset",
4
"entry": [
5
{
6
"search": {
7
"mode": "match",
8
"score": 1
9
},
10
"resource": {
11
"id": "194414ff-46bf-4fd2-aa37-c58f3884f0de",
12
"end": "2022-10-15T10:15:00.000Z",
13
"meta": {
14
"lastUpdated": "2022-10-19T20:28:45.479Z"
15
},
16
"start": "2022-10-15T10:00:00.000Z",
17
"appointmentType": {
18
"text": "Check-up",
19
"coding": [
20
{
21
"code": "CHECKUP",
22
"system": "http://terminology.hl7.org/CodeSystem/v2-0276",
23
"display": "A routine check-up, such as an annual physical"
24
}
25
]
26
},
27
"status": "booked",
28
"identifier": [
29
{
30
"value": "991100112233",
31
"system": "urn:redox:redox-fhir-sandbox:VIS",
32
"extension": [
33
{
34
"url": "https://fhir.redoxengine.com/StructureDefinition/identifier-origin",
35
"valueString": "RedoxAPI"
36
}
37
]
38
}
39
],
40
"participant": [
41
{
42
"actor": {
43
"reference": "Patient/81c2f5eb-f99f-40c4-b504-59483e6148d7"
44
},
45
"status": "accepted"
46
},
47
{
48
"type": [
49
{
50
"text": "ATND",
51
"coding": [
52
{
53
"code": "ATND",
54
"system": "http://terminology.hl7.org/CodeSystem/v3-ParticipationType",
55
"display": "attender"
56
}
57
]
58
}
59
],
60
"actor": {
61
"reference": "Practitioner/dbed0f85-e3cd-47ac-9305-3f629e138832"
62
},
63
"status": "accepted"
64
},
65
{
66
"actor": {
67
"reference": "Location/ed4afd58-9796-4cc5-aed7-5c47345acec9"
68
},
69
"status": "accepted"
70
},
71
{
72
"actor": {
73
"reference": "Location/7fc98699-9108-46c1-958e-ec5419f6ebfd"
74
},
75
"status": "accepted"
76
}
77
],
78
"resourceType": "Appointment",
79
"minutesDuration": 15
80
}
81
}
82
],
83
"total": 1,
84
"resourceType": "Bundle"
85
}

Retrieve appointments by location

You can search by location to search for appointments at one 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 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
Query
bash
1
curl 'https://api.redoxengine.com/fhir/R4/redox-fhir-sandbox/Development/Appointment/_search' \
2
--request POST \
3
--header 'Authorization: Bearer ${API_TOKEN}' \
4
--header 'Content-Type: application/x-www-form-urlencoded' \
5
--data-urlencode 'location=Location/ed4afd58-9796-4cc5-aed7-5c47345acec9'
Response
json
1
{
2
"id": "2bdd0020-f553-45cc-bedc-6061b36abb80",
3
"resourceType": "Bundle",
4
"type": "searchset",
5
"entry": [
6
{
7
"resource": {
8
"resourceType": "Appointment",
9
"id": "194414ff-46bf-4fd2-aa37-c58f3884f0de",
10
"status": "booked",
11
"participant": [
12
{
13
"actor": {
14
"reference": "Patient/81c2f5eb-f99f-40c4-b504-59483e6148d7"
15
},
16
"status": "accepted"
17
},
18
{
19
"type": [
20
{
21
"text": "ATND",
22
"coding": [
23
{
24
"code": "ATND",
25
"system": "http://terminology.hl7.org/CodeSystem/v3-ParticipationType",
26
"display": "attender"
27
}
28
]
29
}
30
],
31
"actor": {
32
"reference": "Practitioner/dbed0f85-e3cd-47ac-9305-3f629e138832"
33
},
34
"status": "accepted"
35
},
36
{
37
"actor": {
38
"reference": "Location/ed4afd58-9796-4cc5-aed7-5c47345acec9"
39
},
40
"status": "accepted"
41
},
42
{
43
"actor": {
44
"reference": "Location/7fc98699-9108-46c1-958e-ec5419f6ebfd"
45
},
46
"status": "accepted"
47
}
48
],
49
"identifier": [
50
{
51
"value": "991100112233",
52
"system": "urn:redox:redox-fhir-sandbox:VIS",
53
"extension": [
54
{
55
"url": "https://fhir.redoxengine.com/StructureDefinition/identifier-origin",
56
"valueString": "RedoxAPI"
57
}
58
]
59
}
60
],
61
"appointmentType": {
62
"text": "Check-up",
63
"coding": [
64
{
65
"code": "CHECKUP",
66
"system": "http://terminology.hl7.org/CodeSystem/v2-0276",
67
"display": "A routine check-up, such as an annual physical"
68
}
69
]
70
},
71
"start": "2022-10-15T10:00:00.000Z",
72
"end": "2022-10-15T10:15:00.000Z",
73
"minutesDuration": 15,
74
"meta": {
75
"lastUpdated": "2022-10-19T20:28:45.479Z"
76
}
77
},
78
"search": {
79
"mode": "match",
80
"score": 1
81
}
82
}
83
],
84
"total": 1
85
}

Retrieve appointments by provider

You can search by provider to search for 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 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
Query
bash
1
curl 'https://api.redoxengine.com/fhir/R4/redox-fhir-sandbox/Development/Appointment/_search' \
2
--request POST \
3
--header 'Authorization: Bearer ${API_TOKEN}' \
4
--header 'Content-Type: application/x-www-form-urlencoded' \
5
--data-urlencode 'practitioner=Practitioner/dbed0f85-e3cd-47ac-9305-3f629e138832'
Response
json
1
{
2
"id": "b76797f1-cf3d-4584-a6d3-69d14373a375",
3
"resourceType": "Bundle",
4
"type": "searchset",
5
"entry": [
6
{
7
"resource": {
8
"resourceType": "Appointment",
9
"id": "194414ff-46bf-4fd2-aa37-c58f3884f0de",
10
"status": "booked",
11
"participant": [
12
{
13
"actor": {
14
"reference": "Patient/81c2f5eb-f99f-40c4-b504-59483e6148d7"
15
},
16
"status": "accepted"
17
},
18
{
19
"type": [
20
{
21
"text": "ATND",
22
"coding": [
23
{
24
"code": "ATND",
25
"system": "http://terminology.hl7.org/CodeSystem/v3-ParticipationType",
26
"display": "attender"
27
}
28
]
29
}
30
],
31
"actor": {
32
"reference": "Practitioner/dbed0f85-e3cd-47ac-9305-3f629e138832"
33
},
34
"status": "accepted"
35
},
36
{
37
"actor": {
38
"reference": "Location/ed4afd58-9796-4cc5-aed7-5c47345acec9"
39
},
40
"status": "accepted"
41
},
42
{
43
"actor": {
44
"reference": "Location/7fc98699-9108-46c1-958e-ec5419f6ebfd"
45
},
46
"status": "accepted"
47
}
48
],
49
"identifier": [
50
{
51
"value": "991100112233",
52
"system": "urn:redox:redox-fhir-sandbox:VIS",
53
"extension": [
54
{
55
"url": "https://fhir.redoxengine.com/StructureDefinition/identifier-origin",
56
"valueString": "RedoxAPI"
57
}
58
]
59
}
60
],
61
"appointmentType": {
62
"text": "Check-up",
63
"coding": [
64
{
65
"code": "CHECKUP",
66
"system": "http://terminology.hl7.org/CodeSystem/v2-0276",
67
"display": "A routine check-up, such as an annual physical"
68
}
69
]
70
},
71
"start": "2022-10-15T10:00:00.000Z",
72
"end": "2022-10-15T10:15:00.000Z",
73
"minutesDuration": 15,
74
"meta": {
75
"lastUpdated": "2022-10-19T20:28:45.479Z"
76
}
77
},
78
"search": {
79
"mode": "match",
80
"score": 1
81
}
82
}
83
],
84
"total": 1
85
}