HL7 FHIR® US Core Implementation Guide STU3 Release 3.1.1

This page is part of the US Core (v3.1.1: STU3) based on FHIR R4. The current version which supercedes this version is 5.0.1. For a full list of available versions, see the Directory of published versions

Medication List Guidance

The guidance below addresses how a patient or a provider can access a patients’ active, historical and future (planned) medications list. This use case adopts the use cases defined as part of the Argonaut Project and US Core, specifically within the scope of accessing medication information as prescribed in the ONC U.S. Core Data for Interoperability (USCDI) v1. This section provide specific guidance on how to to access “all medications” and “all active medications” for a patient using a query on MedicationRequest. Note that in prior versions of this guide, a query on MedicationStatement was required. Because of underlying changes in the FHIR Release 4 pharmacy resources, this guide doesn’t require use of MedicationStatement since an “active” medication list can be obtained using only MedicationRequest.1

Background on the FHIR Medications resources

Pharmacy FHIR Resources

The FHIR specification defines 5 FHIR pharmacy resources concerned with the ordering, dispensing, administration and recording of medications. This guide provides guidance for accessing a patient’s medications using the following 2 resources:

  • Medication: Represents the medication itself
  • MedicationRequest: An order or request for both supply of the medication and the instructions for administration of the medication to a patient, and patient reported medications.

The following 3 resources are introduced here to provide background and define the relationships between the pharmacy resources. This guide does not use them for accessing a patient’s medications:

Details about each resource can be found in the FHIR specification. A general discussion regarding the interaction between these resources is described in the FHIR Medications Module and the Guide to Resources Sections.

Relationships Between the Pharmacy FHIR Resources

This IG focuses on access to a patient’s medications. It is therefore important to understand the relationships between these resources. Figure 1 illustrates the workflow relationship between the medication order and the fulfillment as represented by the FHIR medication resources. Note that in the outpatient setting the patient does the administration.

Figure 1: FHIR Medication Order and Fulfillment
ArgoR4Meds_1.svg

Sources of a MedicationRequest

Several sources may be used to create a MedicationRequest as is shown in Figure 2 below. The information may captured directly a system’s medication orders or reported by a provider. A patient or related person may also report the information (or provide some type of record) including “self-prescribed” orders. For example, oftentimes the patient is the only source of information when the patient reports Cannabis or OTC medication use.

Figure 2: MedicationRequest Information Sources
ArgoR4Meds_3.svg

Options for Representing Medication

This guide supports representing a medication using either a code or a reference to a Medication resource. Typically, a code will be used to represent either a branded (for example, Crestor 10mg tablet) or a generic (for example, Rosuvastatin 10mg tablet) medication. When using a code, the code SHALL follow the extensible binding rules to Medication Clinical Drug (RxNorm) - i.e. unless the concept is not covered by RxNorm, the RxNorm code SHALL be used. More information about using codes can be found in the General Guidance Section and the FHIR Terminology section. A medication resource is typically used when information that is not included as part of the RxNorm code is required. For example, the Medication resource is the only way to correctly represent compounded or extemporaneously prepared medication. When referencing the Medication resource, the resource may be included in the bundle returned, an external resource, or a contained if the resource can’t stand alone. These options are shown in figure 3 below. The server application MAY choose any combination of these methods, but if an external reference to Medication is used, the server SHALL support the include parameter for searching this element. The client application MUST support all methods. The MedicationRequest examples show these different methods. Additional guidance is provided below and in the US Core Server Capability Statement section.

Figure 3: Ways to Represent the Medication
ArgoR4Meds_4.svg

Fetching All Medications, Active Medications, and All Medications for an Encounter

Definitions

  • “medication” is defined in this IG to include all prescribed and “self-prescribed” medications directly ordered by a provider or reported by the provider, patient or related person including ethical drugs, over the counter (OTC) medication, and other substances taken for medical and/or recreational use.
  • “All medications” is defined in this IG to include all historical, active, future prescribed medications and medications that are entered in error and whose status is unknown.
  • “Active medications” is defined in this IG to include all medications with an active status. Active medications do not include past, future, unknown status, and entered in error medications.

Note that these definition do not convey compliance - i.e. the list is a statement of what is prescribed (or self-prescribed) and not what is consumed by patient.

Requirements to access “all medications” and “all active medications” for a patient:

  1. A MedicationRequest resource query:

  2. SHALL be all that is required.
    1. See the General Guidance section for additional rules and expectations for Servers Requiring Status.
  3. SHALL include all MedicationRequest resources with an intent = “order” representing authorized medication orders directly derived from the system’s orders.
  4. SHALL include all prescribed and “self-prescribed” MedicationRequest resources with an intent = “plan” representing reported medications
    1. SHALL use the reported[x] element to indicate the MedicationRequest record was captured as a secondary “reported” record rather than an original primary source-of-truth record. It may also indicate the source of the report.
    2. When recording “self-prescribed” medication, SHOULD use the requester element to indicate the Patient or RelatedPerson as the prescriber.
  5. The encounter element SHOULD be supported. Searching by context (i.e., for a given inpatient encounter) will return all medications ordered during that encounter, which can include both medications administered in hospital as well as prescribed or discharge medications, which are intended to be taken at home.
  6. The category and encounter elements MAY be used together to get the intersection of medications for a given encounter (i.e., the context) that were administered during as an inpatient (i.e., the category).

Get All Medications

  1. Get all medications for a patient by querying MedicationRequest using the patient search parameter and intent search parameter = “order,plan”. See MedicationRequest Quick Start for further details.

    GET /MedicationRequest?patient=[id]&intent=order,plan{&_include=MedicationRequest:medication}

Storyboard for this example

This example is based upon the following scenario:

Patient Brian Z uses an App to request all his medications from a single provider, Dr Cayr. This test scenario exercises a mix of routine meds, unusual schedule meds and as-needed meds. All meds are in the outpatient setting only.

Provider A’s (Dr Cayr) medication records for Patient Brian Z

Item Date Script Source Notes
1 9/12/2016 testosterone cypionate 100mg/ml inj 1ml intramuscularly every 3 weeks Reported by Patient Get at doctor’s office every third Friday. Taking for energy level and drive.
2 9/1/2016 testosterone cypionate 100mg/ml inj 1ml intramuscularly Reported by Dr Cryn completed
3 1/15/2016 Zocor (simvastatin) 40mg by mouth once daily Dr. Cayr Order: BMC patient med status: taking
4 7/1/2015 Humulin R (insulin regular, human) U100 10U every AM, 5U every PM, 5U at bedtime. Dr.Cayr Order:BMC patient med status: taking
5 6/12/2015 simvastatin 30mg by mouth once daily Dr. Cayr Order: BMC patient med status: completed

Request:

Get “all medications” for a patient by querying MedicationRequest using the patient search parameter.

GET [base]/MedicationRequest?patient=test2&intent=order,plan

Response:

A Server returns a search Bundle resource containing all the MedicationRequests for the patient Brian Z

HTTP/1.1 200 OK
[other headers]
{
"resourceType" : "Bundle",
"id" : "get-all-meds",
"meta" : {
  "lastUpdated" : "2017-03-28T14:29:23Z"
},
"type" : "searchset",
"total" : 5,
"entry" : [
  {
    "fullUrl" : "http://test.fhir.org/r4/MedicationRequest/derivedfrom-mr-test2-1",
    "resource" : {
      "resourceType" : "MedicationRequest",
      "id" : "mr-example-1",
 ...snip...
      "status" : "active",
      "intent" : "order",
      "medicationCodeableConcept" : {
        "coding" : [
          {
            "system" : "http://www.nlm.nih.gov/research/umls/rxnorm",
            "code" : "104491",
            "display" : "Simvastatin 20 MG Oral Tablet [Zocor]",
            "userSelected" : false
          }
        ],
        "text" : "Zocor (simvastatin) 20mg Tablet"
      },
...snip...
  },
  {
    "fullUrl" : "http://test.fhir.org/r4/MedicationRequest/derivedfrom-mr-test2-2",
    "resource" : {
      "resourceType" : "MedicationRequest",
      "id" : "mr-example-2",
      ...snip...
      "status" : "active",
      "intent" : "order",
      "medicationCodeableConcept" : {
        "coding" : [
          {
            "system" : "http://www.nlm.nih.gov/research/umls/rxnorm",
            "code" : "311036",
            "display" : "Humulin R (insulin regular, human) U100  100units/ml inj solution",
            "userSelected" : false
          }
        ],
        "text" : "Humulin R (insulin regular, human) U100  100units/ml inj solution"
      },
...snip...
  },
  {
    "fullUrl" : "http://test.fhir.org/r4/MedicationRequest/derivedfrom-mr-test2-3",
    "resource" : {
      "resourceType" : "MedicationRequest",
      "id" : "mr-example-3",
...snip...
    "status" : "completed",
    "intent" : "order",
      "medicationCodeableConcept" : {
        "coding" : [
          {
            "system" : "http://www.nlm.nih.gov/research/umls/rxnorm",
            "code" : "314231",
            "display" : "Simvastatin 10 MG Oral Tablet",
            "userSelected" : false
          }
        ],
        "text" : "simvastatin 10mg Tablet"
      },
...snip...
  },
  {
    "fullUrl" : "http://test.fhir.org/r4/MedicationRequest/test2-1",
    "resource" : {
      "resourceType" : "MedicationRequest",
      "id" : "mr-example-4",
...snip...
      "status" : "completed",
      "intent" : "plan",
      "medicationCodeableConcept" : {
        "coding" : [
          {
            "system" : "http://www.nlm.nih.gov/research/umls/rxnorm",
            "code" : "835829",
            "display" : "testosterone cypionate 100 MG/ML Injectable Solution",
            "userSelected" : false
          }
        ],
        "text" : "testosterone cypionate 100mg/ml inj"
      },
...snip...
  },
  {
    "fullUrl" : "http://test.fhir.org/r4/MedicationRequest/test2-2",
    "resource" : {
      "resourceType" : "MedicationRequest",
      "id" : "mr-example-5",
...snip...
      "status" : "active",
      "intent" : "plan",
      "medicationCodeableConcept" : {
        "coding" : [
          {
            "system" : "http://www.nlm.nih.gov/research/umls/rxnorm",
            "code" : "835829",
            "display" : "testosterone cypionate 100 MG/ML Injectable Solution",
            "userSelected" : false
          }
        ],
        "text" : "testosterone cypionate 100mg/ml inj"
      },
...snip...
    }
  }
 ]
}


Get All Active Medications

  1. Get all active medications for a patient by querying MedicationRequest using the patient, and intent = “order,plan” status = “active” search parameters. See MedicationRequest Quick Start for further details. Note that the client should also consider MedicationRequests with a status of “unknown” and whether to query those as well.

    GET /MedicationRequest?patient=[id]&intent=order,plan&status=active{&_include=MedicationRequest:medication}

Storyboard for this example

This example is based upon the following scenario:

Patient Brian Z uses an App to request all his medications from a single provider, Dr Cayr. This test scenario exercises a mix of routine meds, unusual schedule meds and as-needed meds. All meds are in the outpatient setting only.

Provider A’s (Dr Cayr) medication records for Patient Brian Z

Item Date Script Source Notes
1 9/12/2016 testosterone cypionate 100mg/ml inj 1ml intramuscularly every 3 weeks Reported by Patient Get at doctor’s office every third Friday. Taking for energy level and drive.
2 9/1/2016 testosterone cypionate 100mg/ml inj 1ml intramuscularly Reported by Dr Cryn completed
3 1/15/2016 Zocor (simvastatin) 40mg by mouth once daily Dr. Cayr Order: BMC patient med status: taking
4 7/1/2015 Humulin R (insulin regular, human) U100 10U every AM, 5U every PM, 5U at bedtime. Dr.Cayr Order:BMC patient med status: taking
5 6/12/2015 simvastatin 30mg by mouth once daily Dr. Cayr Order: BMC patient med status: completed

Request:

Get “all active medications” for a patient by querying MedicationRequest using the patient and status= “active” search parameters.

GET [base]/MedicationRequest?patient=test2&intent=order,plan&status=active

Response:

A Server returns a search Bundle resource containing all the MedicationRequests with a status of “active” for the patient Brian Z

HTTP/1.1 200 OK
[other headers]
{
"resourceType" : "Bundle",
"id" : "get-all-meds",
"meta" : {
  "lastUpdated" : "2017-03-28T14:29:23Z"
},
"type" : "searchset",
"total" : 3,
"entry" : [
  {
    "fullUrl" : "http://test.fhir.org/r4/MedicationRequest/derivedfrom-mr-test2-1",
    "resource" : {
      "resourceType" : "MedicationRequest",
      "id" : "mr-example-1",
...snip...
      "status" : "active",
      "intent" : "order",
      "medicationCodeableConcept" : {
        "coding" : [
          {
            "system" : "http://www.nlm.nih.gov/research/umls/rxnorm",
            "code" : "104491",
            "display" : "Simvastatin 20 MG Oral Tablet [Zocor]",
            "userSelected" : false
          }
        ],
        "text" : "Zocor (simvastatin) 20mg Tablet"
      },
...snip...
  },
  {
    "fullUrl" : "http://test.fhir.org/r4/MedicationRequest/derivedfrom-mr-test2-2",
    "resource" : {
      "resourceType" : "MedicationRequest",
      "id" : "mr-example-2",
...snip...
      "status" : "active",
      "intent" : "order",
      "medicationCodeableConcept" : {
        "coding" : [
          {
            "system" : "http://www.nlm.nih.gov/research/umls/rxnorm",
            "code" : "311036",
            "display" : "Humulin R (insulin regular, human) U100  100units/ml inj solution",
            "userSelected" : false
          }
        ],
        "text" : "Humulin R (insulin regular, human) U100  100units/ml inj solution"
      },
...snip...
  },
  {
    "fullUrl" : "http://test.fhir.org/r4/MedicationRequest/test2-2",
    "resource" : {
      "resourceType" : "MedicationRequest",
      "id" : "mr-example-5",
...snip...
      "status" : "active",
      "intent" : "plan",
      "medicationCodeableConcept" : {
        "coding" : [
          {
            "system" : "http://www.nlm.nih.gov/research/umls/rxnorm",
            "code" : "835829",
            "display" : "testosterone cypionate 100 MG/ML Injectable Solution",
            "userSelected" : false
          }
        ],
        "text" : "testosterone cypionate 100mg/ml inj"
      },
...snip...
    }
  }
 ]
}


Get All Medications for an Encounter

  1. Get “all medications” for an encounter by querying MedicationRequest using the patient and encounter and intent =”order,plan” search parameters. See MedicationRequest Quick Start for further details.

    GET /MedicationRequest?patient=[id]&intent=order,plan&encounter=[id]{&_include=MedicationRequest:medication}

Storyboard for this example

This example is based upon the following scenario.

Patient Brain Z has presented with the same condition (pneumonia) as in a previous inpatient encounter. Provider A (Dr Cayr) uses a desktop or mobile application to request all the medications from this previous inpatient encounter (Encounter A).

Medication records for Patient Brian Z during Encounter A

Item Date Script Source Notes
1 9/10/2016 - 9/12-2016 Cefatoxime 1gm intravenously every 6 hours Provider B’s Order Administered in hospital
2 9/10/2016 - 9/12-2016 Zithromax (azithromycin) 500 MG in 250 ml Normal Saline intravenous infusion over 1hr daily Provider B’s Order Administered in hospital
3 9/10/2016 - 9/12-2016 Ketorolac 15 mg intravenously every 6 hours Provider B’s Order Administered in hospital
2 9/10/2016 - 9/12-2016 LRS Solution 200 ml/hr intravenously CRI Provider B’s Order Administered in hospital
5 9/12/2016 Amoxicillin 500mg by mouth every 6 hours for 10 days Provider B’s Order discharge prescription, patient reported did not comply (fill prescription)
6 9/12/2016 Zithromax (azithromycin) 250mg by mouth every 12 hours for 10 days Provider B’s Order discharge prescription, patient reported did not comply (fill prescription)

Request:

Get “all medications” for a patient inpatient encounter by querying MedicationRequest using the patient and encounter search parameters.

GET [base]/MedicationRequest?patient=test2&intent=order,plan&encounter=A

Response:

A Server returns a search Bundle resource containing all the MedicationRequests for the patient Brian Z during inpatient Encounter A:

HTTP/1.1 200 OK
[other headers]
"id": "get-encounter-meds",
"meta": {
  "versionId": "1",
  "lastUpdated": "2017-04-10T12:49:37.665-04:00"
},
"type": "searchset",
"total": 6,
 ...snip...
 "entry": [
   {
     "fullUrl": "http://test.fhir.org/r4/MedicationRequest/derivedfrom-mr-enca-1",
     "resource": {
       "resourceType": "MedicationRequest",
       "id": "mr-example-6",
  ...snip...
  },
  "encounter": {
    "reference": "Encounter/A",
    "display": "Inpatient Encounter A"
  },
  "status": "completed",
  "intent": "order",
  "medicationCodeableConcept": {
    "coding": [
      {
        "system": "http://www.nlm.nih.gov/research/umls/rxnorm",
        "code": "1656313",
        "display": "Cefotaxime 1000 MG Injection"
      }
    ],
    "text": "Cefotaxime 1000Mg Powder For Solution For Injection"
  },
  ...snip...
  "fullUrl": "http://test.fhir.org/r4/MedicationRequest/derivedfrom-mr-enca-2",
  "resource": {
    "resourceType": "MedicationRequest",
    "id": "mr-example-7",
    ...snip...
    },
    "encounter": {
      "reference": "Encounter/A",
      "display": "Inpatient Encounter A"
    },
    "status": "completed",
      "intent": "order",
    "medicationCodeableConcept": {
      "coding": [
        {
          "system": "http://www.nlm.nih.gov/research/umls/rxnorm",
          "code": "860092",
          "display": "1 ML Ketorolac Tromethamine 15 MG/ML Injection"
        }
      ],
      "text": "Ketorolac Tromethamine 15 MG/ML For Injection"
    },
    ...snip...
    "fullUrl": "http://test.fhir.org/r4/MedicationRequest/derivedfrom-mr-enca-3",
    "resource": {
      "resourceType": "MedicationRequest",
      "id": "mr-example-8",
      ...snip...
      "contained": [
        {
          "resourceType": "Medication",
          "id": "med-1",
          "meta": {
            "profile": [
              "http://hl7.org/fhir/us/core/StructureDefinition/us-core-medication"
            ]
          },
          "code": {
            "text": "Azithromycin 500mg in 250 ml Normal Saline"
          },
          ...snip...
          },
        "encounter": {
          "reference": "Encounter/A",
          "display": "Inpatient Encounter A"
        },
        "status": "completed",
        "intent": "order",
        "medicationReference": {
            "reference": "#med-1"
          },
          ...snip...
      "fullUrl": "http://test.fhir.org/r4/MedicationRequest/derivedfrom-mr-enca-4",
      "resource": {
        "resourceType": "MedicationRequest",
        "id": "mr-example-9",
      ...snip...
      "encounter": {
        "reference": "Encounter/A",
        "display": "Inpatient Encounter A"
      },
      "status": "completed",
      "intent": "order",
      "medicationCodeableConcept": {
        "coding": [
          {
            "system": "http://www.nlm.nih.gov/research/umls/rxnorm",
            "code": "847626",
            "display": "Calcium Chloride 0.0014 MEQ/ML / Potassium Chloride 0.024 MEQ/ML / Sodium Chloride 0.103 MEQ/ML / Sodium Lactate 0.028 MEQ/ML Injectable Solution"
          }
        ],
        "text": "LRS"
        ...snip...
      "fullUrl": "http://test.fhir.org/r4/MedicationRequest/derivedfrom-mr-enca-5",
      "resource": {
        "resourceType": "MedicationRequest",
        "id": "mr-example-10",
      ...snip...
      "encounter": {
        "reference": "Encounter/A",
        "display": "Inpatient Encounter A"
      },
      "status": "active",
      "intent": "order",
      "medicationCodeableConcept": {
        "coding": [
          {
            "system": "http://www.nlm.nih.gov/research/umls/rxnorm",
            "code": "212446",
            "display": "Zithromax 250 MG Oral Tablet"
          }
        ],
        "text": "Zithromax 500 MG Oral Tablet"
        ...snip...
      "fullUrl": "http://test.fhir.org/r4/MedicationRequest/derivedfrom-mr-enca-6",
      "resource": {
        "resourceType": "MedicationRequest",
        "id": "mr-example-11",
      ...snip...
      },
      "encounter": {
        "reference": "Encounter/A",
        "display": "Inpatient Encounter A"
      },
      "status": "active",
      "intent": "order",
      "medicationCodeableConcept": {
        "coding": [
          {
            "system": "http://www.nlm.nih.gov/research/umls/rxnorm",
            "code": "308191",
            "display": "Amoxicillin 500 MG Oral Capsule"
          }
        ],
        "text": "Amoxicillin 500 MG"

 ]
}


See the US Core Server Capability Statement for a complete list of supported RESTful operations and search parameters for this IG.

De-duplication of Data

Medications may be duplicated in a medication list when multiple sources of data are used to generate the list. To provide a list of a patients’ medications, it may be necessary to “de-duplicate” the medications on the list. The deduplication activity MAY be provided by the server but SHOULD be provided by the client.

This specification does not specify deduplication best practices, however systems can consider the following approaches:

  • Compare the MedicationRequest.identifier. The identifier element is an external business identifier systems include to help indicate that the resources are related.
  • Compare the generic, or brand name, included in the medication resource. The system will require access to terminology capabilities to identify equivalence.
  • Finally, in the deduplication process, systems must be cautious in only marking things as equivalent if they are certain.


  1. It is anticipated that there will be further changes to the medication resources in future versions of FHIR which may lead to changes in our guidance for fetching patient medications in future versions of this guide. ↩