Retrieve a patient's appointment schedule

Last updated: Feb 18, 2025

IMPLEMENTATION

HEALTH TECH VENDOR

PRODUCT OWNER

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

Prerequisite: Having a patient identifier

To use this API action, you must know the patient identifier. If you don’t have one, search for a patient with demographics to locate an appropriate identifier first.

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.

Not for scheduling appointments

This isn't what you'd use for scheduling a patient appointment. In that case, you'd want to look up a provider's schedule first, not retrieve a patient's appointments.

Supported systems

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

Talk to a Redoxer

It’s also possible to use the Redox Data Model API for this API action. Talk to a Redoxer to learn about your options.

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

Using data on demand

Your connection's system may not support a query-based data exchange, but they may still be willing to provide results with a push-based method.

However, we understand that you may not want to store all that data. Maybe you don't need all the possible results and just want to query for what you want when you need it. If so, you can use this API action via our data on demand service, which stores the connection's data so that you can query from Redox "on demand." Learn about data on demand.

Things you need to know

Refining your search

Variation in scheduling practices

Sensible queries

What's next?

Does this API action seem like a good fit for your unique workflow? Let your Technical Account Manager know! To start development, download the resource schema noted in the related action step. Then decide which data elements you need.

If you’re new to Redox, use the Quickstart guide to dive in. If you’re not engaged with our sales team yet, talk to a Redoxer to get started.

Action steps

1
Retrieve appointments by patient identifier
optional
2
Retrieve appointments by location
optional
3
Retrieve appointments by provider
optional

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

Select sandbox

Select format

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

Select sandbox

Select format

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

Select sandbox

Select format

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
}

FHIR® is a registered trademark of Health Level Seven International (HL7) and is used with the permission of HL7. Use of this trademark does not constitute an endorsement of products/services by HL7®.