Medication History for Population Response FHIR Resource Details

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 example "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 example "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 example "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 example "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 example "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 o f 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 example "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 example "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 example "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 example "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 example "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