Overview
The Medication History API provides a FHIR compliant layer on top of the Surescripts MedHx API. Due to the way Surescripts MedHx protocol works, the interface is asynchronous.
Workflow
In order to retrieve the Medication Hostory results for a given patient follow these steps:
-
Client initiates a MedHx request for a certain patient:
POST /TaskHeaders
The
Content-Typeheader is required and should be valued toapplication/jsonBody
{ "resourceType": "Task", "code": { "coding": [ { "system": "http://infoworld.ro/nxt/sid/task-code", "code": "medicationHistory", "display": "Medication History Task" } ], "text": "Medication History Task" }, "requester": { "agent": { "reference": "Practitioner/fbde83bf-d592-48dd-a647-fc103699af6d", "display": "ANJALI MODAK" } }, "for": { "reference": "Patient/1170976", "display": "BERT SCHNUR" }, "input": [ { "type": { "coding": [ { "system": "http://infoworld.ro/nxt/sid/task-input", "code": "consent", "display": "Medication History Request Input" } ], "text": "Medication History Request Input" }, "valueString": "Y" }, { "valueString": "HOUSTON GENERAL HOSPITAL", "type": { "coding": [ { "system": "http://infoworld.ro/nxt/sid/task-input", "code": "organization-name", "display": "Organization name" } ], "text": "Organization name" } }, { "valueIdentifier": { "system": "http://us.gov/NPI", "value": "1760423263" }, "type": { "coding": [ { "system": "http://infoworld.ro/nxt/sid/task-input", "code": "organization-identifier", "display": "Organization Identifier" } ], "text": "Organization Identifier" } } ] }Notes
- you should always include a requester in order to identify the practitioner who performed the query
- the user interface should confirm that the patient gave consent to request the medication history data. The consent encoded as seen in the first
inputentry should be valued asY - please provide the organization name and NPI as input parameters as well
Response
If the operation is successful the server responds with the following headers set:
- HTTP status code =
200 OK Locationset to the absolute URL of the newly createdTaskresource
-
Client polls the Task resource endpoint
The client application should check the status by polling the URL previously returned in the
Locationheader and check thestatusproperty.GET /Task/<id>Response
- If the MedHx request was successful, the Task status will be
completedand theoutputproperty will contain two entries: a count of Medication Hostory entries and a link to a FHIRListresource. - If the request failed the status will be set to
entered-in-errorand theoutputproperty will contain a description of the error. - If the request partially succeeded, the Task status will be
completedand theoutputproperty will contain: a count of Medication Hostory entries, a link to aListresource and a description of the encountered error
Example
{ "resourceType": "Task", "identifier": [ { "system": "http://infoworld.ro/nxt/identifier/Task/requestMessageId", "value": "da61a986-c12d-430e-bd79-7981cf7a037" }, { "system": "http://infoworld.ro/nxt/identifier/Task/responseMessageId", "value": "541092961" }, { "system": "http://infoworld.ro/nxt/identifier/Task/asyncResponseMessageId", "value": "541092317" } ], "status": "completed", "intent": "order", "code": { "coding": [ { "system": "http://infoworld.ro/nxt/sid/task-code", "code": "medicationHistory", "display": "Medication History Task" } ], "text": "Medication History Task" }, "for": { "reference": "Patient/1170976", "display": "Bert SCHNUR" }, "lastModified": "2019-04-01T16:10:04-04:00", "requester": { "agent": { "reference": "Practitioner/fbde83bf-d592-48dd-a647-fc103699af6d", "display": "ANJALI MODAK" } }, "input": [ { "valueString": "Y", "type": { "coding": [ { "system": "http://infoworld.ro/nxt/sid/task-input", "code": "consent", "display": "Medication History Request Input" } ], "text": "Medication History Request Input" } }, { "valueString": "HOUSTON GENERAL HOSPITAL", "type": { "coding": [ { "system": "http://infoworld.ro/nxt/sid/task-input", "code": "organization-name", "display": "Organization name" } ], "text": "Organization name" } }, { "valueIdentifier": { "system": "http://us.gov/NPI", "value": "1760423263" }, "type": { "coding": [ { "system": "http://infoworld.ro/nxt/sid/task-input", "code": "organization-identifier", "display": "Organization Identifier" } ], "text": "Organization Identifier" } } ], "output": [ { "type": { "coding": [ { "system": "http://infoworld.ro/nxt/sid/task-result", "code": "count", "display": "Medication History Result Count" } ], "text": "Medication History Result Count" }, "valueInteger": 6 }, { "type": { "coding": [ { "system": "http://infoworld.ro/nxt/sid/task-result", "code": "list", "display": "Medication History Result List" } ], "text": "Medication History Result List" }, "valueReference": { "display": "Result list", "reference": "List/e976bc25-b992-4452-afe7-8060594823d9" } } ], "id": "dd6bcfdd-3c8a-47ac-a97c-3c0b24a4e1dd" } - If the MedHx request was successful, the Task status will be
-
Client retrieves the medication history entries
The client application should retrieve the list of medication history entries data by querying the FHIR API for the
Listresource returned in the previous step along with theMedicetionDispenseresources referenced in theListExample
GET /List?_id=e976bc25-b992-4452-afe7-8060594823d9&_include=List.entryResponse
{ "resourceType": "Bundle", "id": "urn:uuid:d36f2d89-c822-4678-8ab1-4cd133d6865e", "type": "searchset", "updated": "2023-07-04T11:37:33.037Z", "total": 1, "link": [ { "relation": "self", "url": "https://apidhinai.medicasoft.us:8443/api/fhir/List?_id=69991d74-c15e-49ed-af75-5af41477c5c9&_include=List.entry" }, { "relation": "first", "url": "https://apidhinai.medicasoft.us:8443/api/fhir/List?_id=69991d74-c15e-49ed-af75-5af41477c5c9&_include=List.entry&page=1" }, { "relation": "last", "url": "https://apidhinai.medicasoft.us:8443/api/fhir/List?_id=69991d74-c15e-49ed-af75-5af41477c5c9&_include=List.entry&page=1" } ], "entry": [ { "resource": { "resourceType": "List", "identifier": [ { "system": "http://infoworld.ro/nxt/List/messageHistoryRequestId", "value": "8b9f799a-12a1-4f10-b693-44f1efb76a2" }, { "system": "http://infoworld.ro/nxt/List/messageHistoryResponseId", "value": "648312232" } ], "status": "current", "mode": "snapshot", "subject": { "reference": "Patient/1170976", "display": "Bert Schnur" }, "date": "2019-10-10T15:38:54.079Z", "entry": [ { "item": { "reference": "MedicationDispense/0dc397d1-3418-47a7-a36b-874c2746e57f" } }, { "item": { "reference": "MedicationDispense/8a8ef14e-066f-4151-8e3a-995230d8cbe0" } }, { "item": { "reference": "MedicationDispense/5bc5281d-dcec-4bb6-9dd9-600dcc1daab2" } }, { "item": { "reference": "MedicationDispense/37f6a431-26b3-438e-8a12-69bce0c159d9" } }, { "item": { "reference": "MedicationDispense/988e00cc-8232-4349-8935-363def4ed15e" } }, { "item": { "reference": "MedicationDispense/875c8027-c80f-4d18-be02-84967ba5ec6a" } } ], "id": "69991d74-c15e-49ed-af75-5af41477c5c9" }, "fullUrl": "https://apidhinai.medicasoft.us:8443/api/fhir/List/69991d74-c15e-49ed-af75-5af41477c5c9" }, { "search": { "mode": "include" }, "resource": { "contained": [ { "resourceType": "Practitioner", "identifier": [ { "system": "http://us.gov/DEA", "value": "LM7493353" } ], "name": [ [ { "given": [ "RHONDA" ], "family": "JEFFRIES" } ] ], "address": [ { "use": "work", "country": "United States", "line": [ "2155 POST OAK TRITT RD" ], "city": "MARIETTA", "state": "GA", "postalCode": "30062" } ], "id": "refPrescriber" }, { "resourceType": "Organization", "identifier": [ { "system": "http://infoworld.ro/nxt/identifier/NCPDPID", "value": "2121767" } ], "name": "WAL-MART #2514", "telecom": [ { "use": "work", "system": "phone", "value": "6518456325" } ], "id": "refPharmacy" }, { "id": "938574b3-4b54-4c8a-90f7-53989b364c4f", "resourceType": "MedicationRequest", "status": "completed", "intent": "order", "subject": { "reference": "Patient/1170976", "display": "Bert Schnur" }, "medicationReference": { "reference": "Medication/197606", "display": "DIGITEK 250MCG TABLET" }, "requester": { "agent": { "reference": "#refPrescriber", "display": "RHONDA JEFFRIES" } } } ], "resourceType": "MedicationDispense", "meta": { "lastUpdated": "2019-03-28T13:44:13.230Z" }, "extension": [ { "url": "http://infoworld.ro/nxt/Profile/extensions#medicationDispense-medicationNDC", "valueString": "62794014601" }, { "url": "http://infoworld.ro/nxt/Profile/extensions#medicationDispense-type", "valueString": "claim" }, { "url": "http://infoworld.ro/nxt/Profile/extensions#medicationDispense-sourceName", "valueString": "RXHUBPBM" } ], "status": "completed", "medicationReference": { "reference": "Medication/197606", "display": "DIGITEK 250MCG TABLET" }, "subject": { "reference": "Patient/1170976", "display": "Bert Schnur" }, "performer": [ { "actor": { "reference": "#refPharmacy", "display": "WAL-MART #2514" } } ], "authorizingPrescription": [ { "reference": "#938574b3-4b54-4c8a-90f7-53989b364c4f", "display": "RHONDA JEFFRIES" } ], "quantity": { "value": "30", "system": "urn:oid:2.16.840.1.113883.3.26.1.1", "code": "C38046", "unit": "Unspecified" }, "daysSupply": { "value": "30", "code": "d", "system": "http://unitsofmeasure.org", "unit": "days" }, "whenHandedOver": "2015-06-11T00:00:00.0Z", "id": "0dc397d1-3418-47a7-a36b-874c2746e57f" }, "fullUrl": "https://apidhinai.medicasoft.us:8443/api/fhir/MedicationDispense/0dc397d1-3418-47a7-a36b-874c2746e57f" }, { "search": { "mode": "include" }, "resource": { "contained": [ { "resourceType": "Practitioner", "identifier": [ { "system": "http://us.gov/DEA", "value": "SO0088817" } ], "id": "refPrescriber" }, { "resourceType": "Organization", "identifier": [ { "system": "http://infoworld.ro/nxt/identifier/NCPDPID", "value": "0322038" } ], "name": "AdvanceRx.com", "telecom": [ { "use": "work", "system": "phone", "value": "8774831324" } ], "id": "refPharmacy" }, { "id": "e21bbffd-1208-4f00-9497-d7ad998ce182", "resourceType": "MedicationRequest", "status": "completed", "intent": "order", "subject": { "reference": "Patient/1170976", "display": "Bert Schnur" }, "medicationReference": { "reference": "Medication/393245", "display": "LANOXIN 50MCG/ML ELIXIR" }, "requester": { "agent": { "reference": "#refPrescriber" } } } ], "resourceType": "MedicationDispense", "meta": { "lastUpdated": "2019-02-22T17:36:07.304Z" }, "extension": [ { "url": "http://infoworld.ro/nxt/Profile/extensions#medicationDispense-medicationNDC", "valueString": "00173026427" }, { "url": "http://infoworld.ro/nxt/Profile/extensions#medicationDispense-medicationStrength", "valueString": "50MCG/ML" }, { "url": "http://infoworld.ro/nxt/Profile/extensions#medicationDispense-type", "valueString": "claim" }, { "url": "http://infoworld.ro/nxt/Profile/extensions#medicationDispense-sourceName", "valueString": "RXHUBPBM" } ], "status": "completed", "medicationReference": { "reference": "Medication/393245", "display": "LANOXIN 50MCG/ML ELIXIR" }, "subject": { "reference": "Patient/1170976", "display": "Bert Schnur" }, "performer": [ { "actor": { "reference": "#refPharmacy", "display": "AdvanceRx.com" } } ], "authorizingPrescription": [ { "reference": "#e21bbffd-1208-4f00-9497-d7ad998ce182" } ], "quantity": { "value": "1", "system": "urn:oid:2.16.840.1.113883.3.26.1.1", "code": "C38046", "unit": "Unspecified" }, "daysSupply": { "value": "30", "code": "d", "system": "http://unitsofmeasure.org", "unit": "days" }, "whenHandedOver": "2019-01-01T00:00:00.0Z", "id": "8a8ef14e-066f-4151-8e3a-995230d8cbe0" }, "fullUrl": "https://apidhinai.medicasoft.us:8443/api/fhir/MedicationDispense/8a8ef14e-066f-4151-8e3a-995230d8cbe0" }, { "search": { "mode": "include" }, "resource": { "contained": [ { "resourceType": "Practitioner", "identifier": [ { "system": "http://us.gov/DEA", "value": "LM7493353" } ], "name": [ [ { "given": [ "RHONDA" ], "family": "JEFFRIES" } ] ], "address": [ { "use": "work", "country": "United States", "line": [ "2155 POST OAK TRITT RD" ], "city": "MARIETTA", "state": "GA", "postalCode": "30062" } ], "id": "refPrescriber" }, { "resourceType": "Organization", "identifier": [ { "system": "http://infoworld.ro/nxt/identifier/NCPDPID", "value": "2121767" } ], "name": "WAL-MART #2514", "telecom": [ { "use": "work", "system": "phone", "value": "6518456325" } ], "id": "refPharmacy" }, { "id": "39a7024b-e21c-4a68-94e0-534602d26a09", "resourceType": "MedicationRequest", "status": "completed", "intent": "order", "subject": { "reference": "Patient/1170976", "display": "Bert Schnur" }, "medicationReference": { "reference": "Medication/197604", "display": "DIGITEK 125MCG TABLET" }, "requester": { "agent": { "reference": "#refPrescriber", "display": "RHONDA JEFFRIES" } } } ], "resourceType": "MedicationDispense", "meta": { "lastUpdated": "2019-03-28T13:44:13.233Z" }, "extension": [ { "url": "http://infoworld.ro/nxt/Profile/extensions#medicationDispense-medicationNDC", "valueString": "62794014510" }, { "url": "http://infoworld.ro/nxt/Profile/extensions#medicationDispense-type", "valueString": "claim" }, { "url": "http://infoworld.ro/nxt/Profile/extensions#medicationDispense-sourceName", "valueString": "RXHUBPBM" } ], "status": "completed", "medicationReference": { "reference": "Medication/197604", "display": "DIGITEK 125MCG TABLET" }, "subject": { "reference": "Patient/1170976", "display": "Bert Schnur" }, "performer": [ { "actor": { "reference": "#refPharmacy", "display": "WAL-MART #2514" } } ], "authorizingPrescription": [ { "reference": "#39a7024b-e21c-4a68-94e0-534602d26a09", "display": "RHONDA JEFFRIES" } ], "quantity": { "value": "30", "system": "urn:oid:2.16.840.1.113883.3.26.1.1", "code": "C38046", "unit": "Unspecified" }, "daysSupply": { "value": "30", "code": "d", "system": "http://unitsofmeasure.org", "unit": "days" }, "whenHandedOver": "2015-05-07T00:00:00.0Z", "id": "5bc5281d-dcec-4bb6-9dd9-600dcc1daab2" }, "fullUrl": "https://apidhinai.medicasoft.us:8443/api/fhir/MedicationDispense/5bc5281d-dcec-4bb6-9dd9-600dcc1daab2" }, { "search": { "mode": "include" }, "resource": { "contained": [ { "id": "a73a5a87-b5a6-44a4-95a8-f90a8dc21bca", "resourceType": "MedicationRequest", "status": "completed", "intent": "order", "subject": { "reference": "Patient/1170976", "display": "Bert Schnur" }, "medicationReference": { "reference": "Medication/197604", "display": "DIGITEK" }, "authoredOn": "2018-03-31T00:00:00.0Z" } ], "resourceType": "MedicationDispense", "meta": { "lastUpdated": "2019-02-22T17:36:07.308Z" }, "extension": [ { "url": "http://infoworld.ro/nxt/Profile/extensions#medicationDispense-priorAuthorization", "valueString": "9383729" }, { "url": "http://infoworld.ro/nxt/Profile/extensions#medicationDispense-medicationNDC", "valueString": "62794014510" }, { "url": "http://infoworld.ro/nxt/Profile/extensions#medicationDispense-medicationStrength", "valueString": "125MCG" }, { "url": "http://infoworld.ro/nxt/Profile/extensions#medicationDispense-type", "valueString": "claim" }, { "url": "http://infoworld.ro/nxt/Profile/extensions#medicationDispense-sourceName", "valueString": "RXHUBPBM" } ], "status": "completed", "medicationReference": { "reference": "Medication/197604", "display": "DIGITEK" }, "subject": { "reference": "Patient/1170976", "display": "Bert Schnur" }, "authorizingPrescription": [ { "reference": "#a73a5a87-b5a6-44a4-95a8-f90a8dc21bca" } ], "quantity": { "value": "30", "system": "urn:oid:2.16.840.1.113883.3.26.1.1", "code": "C38046", "unit": "Unspecified" }, "daysSupply": { "value": "30", "code": "d", "system": "http://unitsofmeasure.org", "unit": "days" }, "whenHandedOver": "2019-02-02T00:00:00.0Z", "id": "37f6a431-26b3-438e-8a12-69bce0c159d9" }, "fullUrl": "https://apidhinai.medicasoft.us:8443/api/fhir/MedicationDispense/37f6a431-26b3-438e-8a12-69bce0c159d9" }, { "search": { "mode": "include" }, "resource": { "contained": [ { "resourceType": "Practitioner", "identifier": [ { "system": "http://us.gov/DEA", "value": "LM7493353" } ], "name": [ [ { "given": [ "RHONDA" ], "family": "JEFFRIES" } ] ], "address": [ { "use": "work", "country": "United States", "line": [ "2155 POST OAK TRITT RD" ], "city": "MARIETTA", "state": "GA", "postalCode": "30062" } ], "id": "refPrescriber" }, { "resourceType": "Organization", "identifier": [ { "system": "http://infoworld.ro/nxt/identifier/NCPDPID", "value": "2121767" } ], "name": "WAL-MART #2514", "telecom": [ { "use": "work", "system": "phone", "value": "6518456325" } ], "id": "refPharmacy" }, { "id": "e3148794-757c-4d89-a486-a7deb9633458", "resourceType": "MedicationRequest", "status": "completed", "intent": "order", "subject": { "reference": "Patient/1170976", "display": "Bert Schnur" }, "medicationReference": { "reference": "Medication/197604", "display": "LANOXIN 125MCG TABLET" }, "requester": { "agent": { "reference": "#refPrescriber", "display": "RHONDA JEFFRIES" } } } ], "resourceType": "MedicationDispense", "meta": { "lastUpdated": "2019-03-28T13:44:13.232Z" }, "extension": [ { "url": "http://infoworld.ro/nxt/Profile/extensions#medicationDispense-medicationNDC", "valueString": "00173024275" }, { "url": "http://infoworld.ro/nxt/Profile/extensions#medicationDispense-type", "valueString": "claim" }, { "url": "http://infoworld.ro/nxt/Profile/extensions#medicationDispense-sourceName", "valueString": "RXHUBPBM" } ], "status": "completed", "medicationReference": { "reference": "Medication/197604", "display": "LANOXIN 125MCG TABLET" }, "subject": { "reference": "Patient/1170976", "display": "Bert Schnur" }, "performer": [ { "actor": { "reference": "#refPharmacy", "display": "WAL-MART #2514" } } ], "authorizingPrescription": [ { "reference": "#e3148794-757c-4d89-a486-a7deb9633458", "display": "RHONDA JEFFRIES" } ], "quantity": { "value": "30", "system": "urn:oid:2.16.840.1.113883.3.26.1.1", "code": "C38046", "unit": "Unspecified" }, "daysSupply": { "value": "30", "code": "d", "system": "http://unitsofmeasure.org", "unit": "days" }, "whenHandedOver": "2015-04-05T00:00:00.0Z", "id": "988e00cc-8232-4349-8935-363def4ed15e" }, "fullUrl": "https://apidhinai.medicasoft.us:8443/api/fhir/MedicationDispense/988e00cc-8232-4349-8935-363def4ed15e" }, { "search": { "mode": "include" }, "resource": { "contained": [ { "resourceType": "Practitioner", "identifier": [ { "system": "http://us.gov/DEA", "value": "LM7493353" } ], "name": [ [ { "given": [ "RHONDA" ], "family": "JEFFRIES" } ] ], "address": [ { "use": "work", "country": "United States", "line": [ "2155 POST OAK TRITT RD" ], "city": "MARIETTA", "state": "GA", "postalCode": "30062" } ], "id": "refPrescriber" }, { "resourceType": "Organization", "identifier": [ { "system": "http://infoworld.ro/nxt/identifier/NCPDPID", "value": "2121767" } ], "name": "WAL-MART #2514", "telecom": [ { "use": "work", "system": "phone", "value": "6518456325" } ], "id": "refPharmacy" }, { "id": "442a7064-61b9-4c4f-94d5-38c3b4341b02", "resourceType": "MedicationRequest", "status": "completed", "intent": "order", "subject": { "reference": "Patient/1170976", "display": "Bert Schnur" }, "medicationReference": { "reference": "Medication/393245", "display": "LANOXIN 50MCG/ML ELIXIR" }, "requester": { "agent": { "reference": "#refPrescriber", "display": "RHONDA JEFFRIES" } } } ], "resourceType": "MedicationDispense", "meta": { "lastUpdated": "2019-03-28T13:44:13.234Z" }, "extension": [ { "url": "http://infoworld.ro/nxt/Profile/extensions#medicationDispense-medicationNDC", "valueString": "00173026427" }, { "url": "http://infoworld.ro/nxt/Profile/extensions#medicationDispense-type", "valueString": "claim" }, { "url": "http://infoworld.ro/nxt/Profile/extensions#medicationDispense-sourceName", "valueString": "RXHUBPBM" } ], "status": "completed", "medicationReference": { "reference": "Medication/393245", "display": "LANOXIN 50MCG/ML ELIXIR" }, "subject": { "reference": "Patient/1170976", "display": "Bert Schnur" }, "performer": [ { "actor": { "reference": "#refPharmacy", "display": "WAL-MART #2514" } } ], "authorizingPrescription": [ { "reference": "#442a7064-61b9-4c4f-94d5-38c3b4341b02", "display": "RHONDA JEFFRIES" } ], "quantity": { "value": "1", "system": "urn:oid:2.16.840.1.113883.3.26.1.1", "code": "C38046", "unit": "Unspecified" }, "daysSupply": { "value": "30", "code": "d", "system": "http://unitsofmeasure.org", "unit": "days" }, "whenHandedOver": "2015-03-05T00:00:00.0Z", "id": "875c8027-c80f-4d18-be02-84967ba5ec6a" }, "fullUrl": "https://apidhinai.medicasoft.us:8443/api/fhir/MedicationDispense/875c8027-c80f-4d18-be02-84967ba5ec6a" } ] }