Medication History for Population Response FHIR Resource Details

18 min

The response is a normal search set response bundle. The _lastUpdated parameter should be used to create the window for which to return the notifications.

The focus of the response will be Communication resources. Adhering to FHIR best practices, the minimum necessary information will be returned in each response. Additional referenced resources can be requested using the _include or _include:iterate parameters.

Panel – Each Communication resource contains MedicationDispense references based on each medication returned from PBM/payers and pharmacies connected to Surescripts. Up to 600 medications may be returned within the lookback requested dates from the last 12 months.

Prescription Notifications – Each Communication resource contains one or more notification type extension elements, which will show the reason for the notification (a single medication can have more than one).

Note: This section is organized by the available FHIR Resources as shown on the right-hand navigation pane.

Patient

This FHIR resource provides demographics and other administrative information about an individual receiving care or other health-related services.

Note: The patient extension defines a complex extension or compound extension.

"resourceType": "Patient",
"id": "fec334f9-50ea-4643-a137-1ed4557ae805"

Name	Requirement	Comments	Example
identifier	mandatory	The Patient Resource identifier contains the following values: Data coming from Patient File Load (refer to the associated implementation guide) System = Assigning Authority (detail record field 2) Value = Patient ID (detail record field 3) Note: Best practice is to leverage the Medical Record Number when available.	"identifier": [ { "system": "2.16.840.1.113883.3.2054.2.3.1", "value": "1111990" }, { "system": "http://fhirdocs.surescripts.net/identifiers/participantid", "value": "T00000000111321" } ]
active	mandatory	Identifies whether resource is currently in use.	"active": true,
meta	mandatory	Provides metadata about the resource.	"meta": { "lastUpdated": "2025-02-16T17:23:48.432697+00:00", "profile": [ "http://hl7.org/fhir/us/core/StructureDefinition/us-core-patient\|4.1.0" ], "versionId": "MTczOTcyNjYyODQzMjY5NzAwMA" },
name	mandatory	FHIR® Human Name: Use = Official Family = family name, often called surname Given = given name, first and middle name Prefix = Parts that come before the name Suffix = Parts that come after the name	"name": [ { "family": "ROBINSON", "given": [ "COZMO" ] } ]
phone	optional	The patient’s phone number gathered from Pharmacy Fill data.	"telecom": [ { "system": "phone", "value": "7185987658" } ],
gender	mandatory	Patient gender value coded to match the Administrative Gender Codes.	"gender": "female"
birthDate	mandatory	Patient Date of Birth. Conforms to the FHIR® date/time standards.	"birthDate": "1931-07-06"
address	mandatory	Patient Address including line, city, state, and postal code.	"address": [ { "line": [ "2377 66th AVENUE" ], "city": "MANHATTAN", "state": "NY", "postalCode": "10000" } ]

Organization

This FHIR resource provides information about the pharmacy.

"resourceType": "Organization"
"id": "09207555-197c-49q9-9525-726cb5aa111a"

Name	Requirement	Comments	Example
identifier	mandatory	The Organization resource identifiers include: Pharmacy NCPDPID Data coming from Patient File Load (refer to the associated implementation guide) The pharmacy’s 10-digit National Provider Identifier number Data Source Reference ID Value: Pharmacy dispensed fill record = P2 (Prescription Notification) Pharmacy (Panel) Claim Record = Payer NewRx Record = Prescriber	"identifier": [ { "system": "http://fhirdocs.surescripts.net/identifiers/participantid", "value": "T00000000111321" }, { "system": "http://fhirdocs.surescripts.net/identifiers/organization-type", "value": "P2" }, { "system": "http://hl7.org/fhir/sid/us-npi", "value": "1144235417" }, { "system": "https://terminology.hl7.org/6.0.2/CodeSystem-NCPDPProviderIdentificationNumber.html", "value": "0501468" } ],"identifier": [ { "system": "http://surescripts.net/fhir/identifiers/ncpdpid", "value": "3390705"
active	mandatory	Identifies whether resource is currently in use.	"active": true,
meta	mandatory	Provides metadata about the resource.	"meta": { "lastUpdated": "2025-02-16T17:23:48.432697+00:00", "profile": [ "http://hl7.org/fhir/us/core/StructureDefinition/us-core-patient\|4.1.0" ], "versionId": "MTczOTcyNjYyODQzMjY5NzAwMA" },
name	optional	Name of pharmacy	"name": " Walgreens"
telecom	optional	Pharmacy phone number System = phone or fax	"telecom": [ { "system": "phone", "value": "5035558839" } ]
address	optional	Pharmacy address	"address": [ { "line": [ "555 AVENUE X" ], "city": "BUFFALO", "state": "NY", "postalCode": "666665117" } ] }

Practitioner

This FHIR resource provides information about the individual directly or indirectly involved in healthcare provisioning.

"resourceType": "Practitioner"
"id": "8111cd95-1c5a-4a8f-be37-71c4178888f6"

Name	Requirement	Comments	Example
identifier	optional	The Practitioner resource identifiers include: Data coming from Patient File Load (refer to the associated implementation guide) 10-digit valid NPI DEA Number State License number	"identifier": [ { "system": "http://hl7.org/fhir/sid/us-npi", "value": "1831620525" } { "system": "http://hl7.org/fhir/sid/us-dea", "value": "BP6645216" } { "system": "http://fhirdocs.surescripts.net/identifiers/participantid", "value": "T00000000111321" } ]
meta	mandatory	Provides metadata about the resource.	"meta": { "lastUpdated": "2025-02-16T17:23:48.432697+00:00", "profile": [ "http://hl7.org/fhir/us/core/StructureDefinition/us-core-patient\|4.1.0" ], "versionId": "MTczOTcyNjYyODQzMjY5NzAwMA" },
name	mandatory	FHIR® Human Name: Use = Official Family = family name, often called surname Given = given name, first and middle name Prefix = Parts that come before the name Suffix = Parts that come after the name	"name": [ { "family": "HASHEMI", "given": [ "ALEX" ] } ]
telecom	optional	A contact detail for the practitioner, for example, a telephone number or an email address.	"telecom": [ { "system": "phone", "value": "2122416639" } ]
address	optional	Prescriber office address.	"address": [ { "line": [ "95 10TH AVE" ], "city": "BROOKLYN", "state": "NY", "postalCode": "11215" } ] }

MedicationRequest

This FHIR resource provides an order for both supply of the medication and the instructions for administration for the patient.

"resourceType": "MedicationRequest"
"id": "e6aa023c-419a-4174-9caa-9ad5e4c0a111"

Name	Requirement	Comments	Example
identifier	mandatory	The Medication Request identifier values included are: pharmacy-prescription-number – Prescription number assigned by the pharmacy. electronic-rx-order-number – Order Number on the NewRx. Present for eRx. electronic-rx-ref-number – Prescription Reference Number. Present for eRx. Panel only identifiers include: BIN number of the insurance used Card holder number Plan code Payment code PCN for the insurance used	"identifier": [ { "system": { http://fhirdocs.surescripts.net/identifiers/prescription-number, "value": "222243636" }, { "system": {http://fhirdocs.surescripts.net/identifiers/electronic_order_number, "value": "R1C113elec_pres_order_no" }, { "system": {http://fhirdocs.surescripts.net/identifiers/electronic_rx_ref_number, "value": "00000000000000000000005871842664474" } { "system": { http://hl7.org/fhir/us/core/StructureDefinition/us-core-prescription-bin-number, "value": " 020107_BIN" }, { "system": { http://hl7.org/fhir/us/core/StructureDefinition/us-core-prescription-cardholder-number, "value": "R1C113elec_pres_order_no" }, { "system": { http://hl7.org/fhir/us/core/StructureDefinition/us-core-prescription-plan-code, "value": "02_Medicaid" }, { "system": { http://hl7.org/fhir/us/core/StructureDefinition/us-core-prescription-payment-code, "value": "01_PrivatePay" }, { "system": { http://hl7.org/fhir/us/core/StructureDefinition/us-core-prescription-pcn, "value": " 01410000_PCN" } { "system": "http://fhirdocs.surescripts.net/identifiers/participantid", "value": "T00000000111321" } ],
meta	mandatory	Provides metadata about the resource.	"meta": { "lastUpdated": "2025-02-17T19🕚41.453737+00:00", "profile": [ "http://hl7.org/fhir/us/core/StructureDefinition/us-core-medicationrequest\|4.1.0" ], "versionId": "MTczOTgxOTUwMTQ1MzczNzAwMA" },
status	mandatory	A code specifying current state of the order. Generally, this is an active or completed state.	"status": "completed",
intent	mandatory	Whether the request is a proposal, plan, or an original order.	"intent": "order"
medicationReference	mandatory	Link to a resource representing the medication ordered.	"medicationReference": { "reference": "Medication/1e9de5e5-a7a4-4a09-a87d-77b181c00e25" },
reasonReference	optional	Link to a resource representing the diagnosis why the medication was ordered.	"reasonReference": { "reference": "Condition/46f92300-00b4-43ab-974b-62f28de92736" },
subject	mandatory	Link to a resource representing the person to whom the medication will be given.	"subject": { "reference": "Patient/4d8fd28e-5c99-436c-9d82-6aaad8d8842a" }
authoredOn	mandatory	Also known as date written, which is the date when the prescription was initially written or authored on.	"authoredOn": "2025-02-14T23:00:00+00:00"
requester	mandatory	The individual that initiated the request and has responsibility for its activation.	"requester": { "reference": "Practitioner/47ca5584-2259-4a5a-bb81-69f30c45cd0a" } }
performer	conditional	The actor is the intended dispenser of the medication, the pharmacy details. Note: Only populated for FirstFillNotPickedUp notifications	"performer": [ { "actor": { "reference": "Organization/701c9e15-14df-4fd0-a791-ebbfa7b39de4" } } ]
dispenseRequest	optional	Number of repeats allowed represents the number of refills originally authorized when available. Value represents the quantity amount of medication to supply per dispense.	"dispenseRequest": { "numberOfRepeatsAllowed": 3, "quantity": { "value": 90.0 } }

MedicationDispense

This FHIR resource indicates that a medication product is to be or has been dispensed for a named person/patient. This includes a description of the medication product (supply) provided and the instructions for administering the medication. The medication dispense is the result of a pharmacy system responding to a medication order.

"resourceType": "MedicationDispense",
"id": "90428847-c5ca-4182-b868-74e1ca99c04c"

Name	Requirement	Comments	Example
meta	mandatory	Provides metadata about the resource.	"meta": { "lastUpdated": "2025-02-16T19🕛38.790907+00:00", "versionId": "MTczOTczMzE1ODc5MDkwNzAwMA" },
extension	optional	Represents the number of refills remaining after this dispense of the medication when available.	"extension": [ { "url": "http://fhirdocs.surescripts.net/extension/refills-remaining", "valueString": "2" } ],
identifier	mandatory	The MedicationDispense Resource identifier values include the Sender ID data coming from the Patient File Load. Panel only identifiers include: Pharmacy Source NCPDP ID Group ID of the insurance used.	"identifier": [ { "system": "http://fhirdocs.surescripts.net/identifiers/participantid", "value": "T00000000111321" } ], { "system": "https://terminology.hl7.org/6.0.2/CodeSystem-NCPDPProviderIdentificationNumber.html", "value": "RX8446" }, { "system": "http://terminology.hl7.org/CodeSystem/coverage-class", "value": "COS" } ],
status	mandatory	A code specifying the state of the set of dispense events.	"status": "completed"
medicationReference	mandatory	Link to a resource representing the medication ordered.	"medicationReference": { "reference": "Medication/1e9de5e5-a7a4-4a09-a87d-77b181c00e25" },
subject	mandatory	Link to a resource representing the person or the group to whom the medication will be given.	"subject": { "reference": "Patient/4d8fd28e-5c99-436c-9d82-6aaad8d8842a" }
performer	conditional	The actor is the dispenser of the medication, the pharmacy details. Note: Not populated for FirstFillNotPickedUp notifications	"performer": [ { "actor": { "reference": "Organization/701c9e15-14df-4fd0-a791-ebbfa7b39de4" } } ]
authorizingPrescription	mandatory	Indicates the medication order that is being dispensed against. Note: When used in FHIR parameters authorizingPrescription must be included as MedicationDispense.prescription.	"authorizingPrescription": [ { "reference": "MedicationRequest/35983470-963e-42a5-a9ce-a5d0216890f1" } ]
type	mandatory	Indicates the type of dispensing event that is performed: FF First Fill FFP = First – Part Fill RF Refill RFP = Refill – Part Fill For example, display Refill 04 indicates this dispense event is the 4th refill.	"type": { "coding": [ { "system": "http://hl7.org/fhir/ValueSet/v3-ActPharmacySupplyType", "code": "FF", “display: “First Fill” } ], E.g. of Refill display Refill 04 indicating Refills Originally Authorized is 04 "type": { "coding": [ { "system": "http://hl7.org/fhir/ValueSet/v3-ActPharmacySupplyType", "code": "RF", “display”: “Refill 04” } ],
quantity	mandatory	The amount of medication that has been dispensed. Value = Represents number dispensed to the patient Unit = Represents the Quantity Unit of Measure Note: See Codified Field Usage for Federal Medication Terminologies (FMT) Codes for details.	"quantity": { "value": 90.0 "unit": "C48155" }
daysSupply	mandatory	The amount of medication expressed as a timing amount.	"daysSupply": { "value": 30.0 }
whenPrepared	mandatory	Also known as DateFilled, which is the date when the dispensed product was packaged and reviewed.	"whenPrepared": "2020-04-18"
whenHandedOver	optional	Also known as DatePickedUp, which is the date the dispensed product was provided to the patient or their representative.	"whenHandedOver": "2020-04-18"
dosageInstruction	optional	Also known as SigText, which indicates how the medication is to be used by the patient.	"dosageInstruction": [ { "text": "TAKE ONE TABLET BY MOUTH THREE TIMES A DAY" } ]

Medication

This FHIR resource provides the medication label, NDC and DEA schedule details.

"resourceType": "Medication",
"id": "b9969cb8-8740-4657-85d1-afb41e7f7509"

Name	Requirement	Comments	Example
identifier	mandatory	The Medication Resource identifier contains data coming from Patient File Load.	"identifier": [ { "system": "http://fhirdocs.surescripts.net/identifiers/participantid", "value": "T00000000111321" } ],
meta	mandatory	Provides metadata about the resource	"meta": { "lastUpdated": "2025-02-16T19🕛38.790907+00:00", "versionId": "MTczOTczMzE1ODc5MDkwNzAwMA" },
code	mandatory	Code is the 11-digit NDC or DEA Drug coding for schedules 1-5. Display is the drug description field, and should include the standardized drug name including strength and form. Note: When all 9s are displayed for the NDC, and it is for fill data, this indicates that the prescription is a compound.	"medicationCodeableConcept": { "coding": [ { "system": " http://hl7.org/fhir/sid/ndc ", "code": "23155010210", "display": "METFORMIN 500MG TAB" }, { "code": "C38046", "display": "Unspecified", "system": "http://www.dea.gov/drug-scheduling" } ] }

Condition

This FHIR resource captures the diagnosis code as to why the medication was ordered for the patient

"resourceType": "Condition",
"id": "46f92300-00b4-43ab-974b-62f28de92736"

Name	Requirement	Comments	Example
identifier	mandatory	The Condition Resource identifier contains data coming from Patient File Load.	"identifier": [ { "system": "http://fhirdocs.surescripts.net/identifiers/participantid", "value": "T00000000111321" } ],
meta	mandatory	Provides metadata about the resource	"meta": { "lastUpdated": "2025-02-16T19🕛38.790907+00:00", "versionId": "MTczOTczMzE1ODc5MDkwNzAwMA" },
code	optional	Code iis CodeableConcept that contains diagnosis information. It can include ICD-9, ICD-10 or CDT codes. Display is the diagnosis description field, and should include the standardized diagnosis name for describing the code.	"code": { "coding": [ { "system": " http://hl7.org/fhir/+sid/icd-10", "code": "E10.1:", "display": "Diabetes mellitus without complications" },
subject	mandatory	Link to a resource representing the person or the group to whom the medication will be given.	"subject": { "reference": "Patient/4d8fd28e-5c99-436c-9d82-6aaad8d8842a" }
category	optional	CodeableConcept that indicates if the diagnosis code represents the primary or secondary.	“category”: { “system”: ”http://fhirdocs.surescripts.net/coding/diagnosis-category”, “code”: “Primary” }

Communication

This resource provides focus for Medication History for Populations FHIR responses. It identifies the response for Panel and Prescription Notifications.

The Communication resources for Panel are based-on and include references to all MedicationDispensed for a specific patient. If there were no medications for a patient during the timeframe of the requested panel, you can get a communication with 0 MedicationDispensed resources.

The Communication resource for Prescription Notifications identifies which notifications are applicable and has a one-to-one relationship with a single MedicationDispensed or MedicationRequest (FirstFillNotPickedUp notifications only) reference.

"resourceType": "Communication",
"id": "ec29328d-67fc-43f0-8a79-75849e94d76b"

Name	Requirement	Comments	Example
extension	conditional	Prescription Notifications: The notification-generated-time uses a Date element for the medication dispense. The patient-notification-types valueString is the notification that was alerted on for this medication dispense Alert types values: NewRx Refill NewPrescriber ControlledSubstance NoRefillsRemaining RefillNotPickedUp CashPayRx MonitoredMedRx FirstFillNotPickedUp The valueCoding alert id will identify that specific Prescription Notification alert for support purposes. Panel: start-date valueString identifies the Request Start Date or start of the lookback period used for the RxHistoryRequest from the Patient File Load data. end-date valueString identifies the Request End Date or end of the lookback period used for the RxHistoryRequest from the Patient File Load data. primary-sender-message-id identifies the Sender Message ID for the RxHistoryRequest.	Prescription Notification "extension": [ { "url": "http://fhirdocs.surescripts.net/coding/patient-notification-types", "valueCoding": { "id": "1b1d5843-0cdc-4788-b309-9822c7da665a", "code": "RefillNotPickedUp" } }, { "url": "http://fhirdocs.surescripts.net/coding/sender-id", "valueCode": " T00000000111321" }, { "url": "http://fhirdocs.surescripts.net/coding/notification-generated-time", "valueDateTime": "2025-12-18T05:58:18+00:00" } ], Panel: "extension": [ { "url": "http://fhirdocs.surescripts.net/extension/start-date", "valueString": "2024-02-17" }, { "system": "http://fhirdocs.surescripts.net/identifiers/primary-sender-message-id", "value": "48320906:13759282:1774967833762" } ],
identifier	mandatory	The Communication resource identifiers include: Data coming from Patient File Load Sender’s Participant ID Patient Population ID Panel Only identifers Primary Sender Message ID (RxHistoryRequest)	"identifier": [ { "system": "http://fhirdocs.surescripts.net/identifiers/participantid", "value": "T00000000111321" }, { "system": "http://fhirdocs.surescripts.net/identifiers/alert-population-id", "value": "PATIENTPOPID~" } ], { "system": "http://fhirdocs.surescripts.net/identifiers/primary-sender-message-id", "value": "45206310:10634006:1763586868423" },
status	mandatory	A code specifying current state of the order. This will always be a completed state.	"status": "completed",
meta	mandatory	Provides metadata about the resource.	"meta": { "lastUpdated": "2025-02-18T15:39:45.079419+00:00", "profile": [ "http://hl7.org/fhir/R4/communication" ], "versionId": "MTczOTg5MzE4NTA3OTQxOTAwMA" },
received	mandatory	Populates date/time the FHIR response was retieved by the customer system.	"received": "2025-02-18T15:39:44+00:00",
category	mandatory	The type of message conveyed. Values: Notification = Prescription Notifications Panel = Panel	Notification: "category": [ { "coding": [ { "system": "http://hl7.org/fhir/communication-category", "code": "notification", "display": "Notification" } ] } ], Panel: "category": [ { "coding": [ { "code": "panel", "display": "Panel", "system": "http://hl7.org/fhir/communication-category" } ] } ],
subject	mandatory	The patient that was the focus of this communication.	"subject": { "reference": "Patient/4a1ff77b-f500-4b6c-9613-6de9118dd689" }
based on	conditional	Identifies the MedicationDispense or MedicationRequest references that was the focus of this communication. Panel will include a reference for each MedicationDispense returned from the RxHistoryRequest lookback period. Prescription Notification will include a single reference to MedicationDispensed that triggered the notification. Prescription Notification FirstFillNotPickedUp will include a single reference to the MedicationRequest that trigered the notification Note: If the patient is found but no medication is identified during the look back period, based-on will be omitted.	"basedOn": [ { "reference": "MedicationDispense/e9afab37-7a65-4a3b-883f-679eb2df2fa7" } ],
reason code	conditional	Captures the reason for the current state of the communication. Value: Patient Not Found Note: Use of this element and its associated reason code is restricted to Medication History Panel workflows.	"reasonCode": [ { "coding": [ { "code": "DJ", "display": "Patient Not Found." } ] } ],
search	mandatory	Search returns a response that is an exact match for what was specified in the query (using the communication or medication dispensed resource for the notification). Value: Match	"search": { "mode": "match" }

CapabilityStatement

This FHIR resource provides the capabilities supported by the FHIR server.

Note: The Capability Statement resource is retrieved from a separate endpoint and is not included as part of any panels or prescription notification FHIR responses.

"resourceType": "CapabilityStatement",
"id": "ec29328d-67fc-43f0-8a79-75849e94d76b"

Name	Requirement	Comments	Example
version	optional	Business version of the capability statement	"version": "20250220",
status	mandatory	The status of this capability statement. Enables tracking the life-cycle of the content. Values: • active • draft	"status": "draft",
date	mandatory	Identifies the date the CapabilityStatement was published	"date": "2025-02-20",
publisher	optional	Name of the organization who published the CapabilityStatement. Value: Surescripts	"publisher": "Surescripts",
description	optional	Provides human readable description of the capability statement	"description": "FHIR capability statement",
kind	mandatory	Identifies the intended use of the CapabilityStatement. Value: instance = The CapabilityStatement instance represents the present capabilities of a specific system instance. This is the kind returned by /metadata for a FHIR server end-point.	"kind": "instance",
fhirVersion	mandatory	The version of the FHIR specification that this CapabilityStatement describes	"fhirVersion": "4.0.1",
format	mandatory	Identifies the supported formats supported Value: json	"format": [ "json" ],
patchFormat	optional	Identifies supported patch formats supported Value: application/json-patch+json	"patchFormat": [ "application/json-patch+json" ],
rest	optional	Defines the restful capabilites of the FHIR endpoint.
security	mandatory	Identifies the connectivity security supported Value: mTLS
resource	optional	Resources are available on the REST interface and describes what capabilities are support for each FHIR resource: type: Resource type that is supported. interaction: What operations are supported by the resource. Values: read search-type searchInclude: _include values supported by the server. searchRevInclude: _revinclude values supported by the server. searchParam: Search parameters supported by implementation.	"resource": [ "type": "MedicationDispense", "interaction": [ { "code": "read" }, { "code": "search-type" } ], "readHistory": false, "updateCreate": false, "conditionalCreate": false, "conditionalUpdate": false, "searchInclude": [ "MedicationDispense.medication", "MedicationDispense.performer", "MedicationDispense.subject" ], "searchRevInclude": [ "Communication.based-on" ], "searchParam": [ { "extension": [ { "url": "https://g.co/fhir/StructureDefinition/CapabilityStatementSearchParameterModifiers", "valueCoding": { "system": "http://hl7.org/fhir/ValueSet/search-modifier-code", "code": "missing" } }, { "url": "https://g.co/fhir/StructureDefinition/CapabilityStatementSearchParameterModifiers", "valueCoding": { "system": "http://hl7.org/fhir/ValueSet/search-modifier-code", "code": "type" } } ], "name": "medication", "definition": "http://hl7.org/fhir/SearchParameter/medications-medication", "type": "reference" },
interactions	optional	Operations supported by the system. Value: search-system	"interaction": [ { "code": "search-system" }

OperationOutcome

This FHIR resource provides a collection of error, warning, or information messages that result from a system action.

"resourceType": "OperationOutcome",
"id": "fg29328d-67fc-22f0-8a79-58412e94d778"

Name	Requirement	Comments	Example
issue	mandatory	Defines a single issue associated with the action performed.	"issue": [ { "severity": "error", "code": "exception", "diagnostics": "_lastUpdated date of 2020-16-19T23:59:59Z is formatted incorrectly." } ]
severity	mandatory	Indicates whether the issue impacts the overall success of the operations. Fixed: Error = Operation was unsuccessful
code	mandatory	Describes the type of issue in a human and computer-friendly way to allow. Fixed: Exception = An unexpected internal error has occurred
diagnostics	optional	Details about which query parameter was missing or badly formatted.