Medication Request
Overview
The MedicationRequest API can be used to interact with data relating to the authorisation and issue(s) of medications for a patient. When querying for data it must always be in the context of a single patient and must state the intent of the Medication Request.
- Retrieving or searching for
MedicationRequestrecords is performed using a HTTP GET described below.
GET API - MedicationRequest Retrieval
id and _id
The MedicationRequest resource can be retrieved directly if the id of the resource is known. By appending the id to the url will cause the MedicationRequest resource to be retrieved. Unlike all other retrieval queries, the response will be a single resource as opposed to a Bundle.
GET /MedicationRequest/[id]
An alternative method for retrieval is to make use of the _id search parameter. In this case, the result will be a Bundle. If the id is present the Bundle will contain a single MedicationRequest resource, otherwise, the Bundle will be empty.
GET /MedicationRequest?_id=[id]
Query Parameters
Unless retrieving a MedicationRequest resource by the use of id then the subject and intent must always be present.
The MedicationRequest can only be targeted against a single patient at any one time.
When retrieving Medication Requests for a patient, the intent must always be supplied in the request.
- For prescriptions, intent = “plan”
- For issued medications, intent = “order”
Subject
GET /MedicationRequest?patient=[value]
GET /MedicationStatement?patient.identifer=[system]|[value]
When searching for NHS Numbers then use the system https://fhir.nhs.uk/Id/nhs-number
For example
GET /MedicationRequest?patient.identifier=https://fhir.nhs.uk/Id/nhs-number|1234567890
All the search examples shown below will accept the patient parameter in either form.
Code
When searching for MedicationRequests with a specific medication code then the query can be constructed using different combinations of the code system and the code value.
GET /MedicationRequest?patient=[value]&code=[code]
GET /MedicationRequest?patient=[value]&code=[system]|[code]
For example to search for a MedicationRequest for 'Amoxicillin 500mg capsules' using SNOMED then a query would look like the following.
GET /MedicationRequest?patient=[value]&code=http://snomed.info/sct|39732411000001100
It is possible to construct a search using text.
GET /MedicationRequest?patient=[value]&code:text=[value]
It is possible to construct a search using a predefined ValueSet that defines a collection of codes.
GET /MedicationRequest?patient=[value]&code:in=[ValueSet url]
The ValueSets that are available for this function will evolve over time. Speak to Graphnet if you intend to use this capability.
Prescription Type
To search for MedicationStatements based on the prescription type of the record, the following can be used
GET /MedicationStatement?patient=[value]&prescription-type=[code]
GET /MedicationStatement?patient=[value]&prescription-type=[system]|[code]
Permitted values:
System = https://fhir.graphnethealth.com/CodeSystem-PrescriptionType
| Code | Display |
|---|---|
| R | Repeat |
| A | Acute |
| D | Repeat Dispensed |
For example, to query for repeat prescriptions, the following can be used
GET /MedicationStatement?patient=[value]&prescription-type=R
Intent
To search MedicationRequests based on intent, the following can be used.
GET /MedicationRequest?patient=[value]&intent=[value]
Permitted values are codes defined in http://hl7.org/fhir/CodeSystem/medicationrequest-intent.
For example:
GET /MedicationRequest?patient=[value]&intent=plan
Authored On Date
To search on the date a MedicationRequest was authored on the following search constructs can be used.
GET /MedicationRequest?patient=[value]&authoredon=[value]
To improve searching the API supports the use of search modifiers. The modifiers supported for date are as below:
| Modifier | Description |
|---|---|
| lt | Returns dates less than the search term |
| le | Returns dates less than or equal to the search term |
| gt | Returns dates greater than the search term |
| ge | Returns dates greater than or equal to the search term |
| eq | Returns dates equal to the search term |
GET /MedicationRequest?patient=[value]&intent=[value]&authoredon=lt[value]
GET /MedicationRequest?patient=[value]&intent=[value]&authoredon=le[value]
GET /MedicationRequest?patient=[value]&intent=[value]&authoredon=gt[value]
GET /MedicationRequest?patient=[value]&intent=[value]&authoredon=ge[value]
GET /MedicationRequest?patient=[value]&intent=[value]&authoredon=eq[value]
So to search for an MedicationRequest authored on 23rd January 2021 the query would be
GET /MedicationRequest?patient=[value]&authoredon=2021-01-23
To search for all MedicationRequests authored before the 23rd December 2020, the following could be used
GET /MedicationRequest?patient=[value]&authoredon=lt2020-12-23
Identifier
To search for MedicationRequests using an identifier on the MedicationRequest record, the following can be used
GET /MedicationRequest?patient=[value]&identifier=[system]|[value]
For example
GET /MedicationRequest?patient=[value]&identifier=http://acme.org/medreqdata|98765-1365428
Status
To search MedicationRequests based on status, the following can be used.
GET /MedicationRequest?patient=[value]&status=[value]
Permitted values are codes defined in http://hl7.org/fhir/CodeSystem/medicationrequest-status.
For example:
GET /MedicationRequest?patient=[value]&status=active
_lastUpdated
To retrieve MedicationRequests based on the updated date of the record
GET /MedicationRequest?patient=[value]&_lastUpdated=[value]
To improve searching the API supports the use of search modifiers. The modifiers supported for _lastUpdated are as below:
| Modifier | Description |
|---|---|
| lt | Returns dates less than the search term |
| le | Returns dates less than or equal to the search term |
| gt | Returns dates greater than the search term |
| ge | Returns dates greater than or equal to the search term |
| eq | Returns dates equal to the search term |
GET /MedicationRequest?patient=[value]&_lastUpdated=lt[value]
GET /MedicationRequest?patient=[value]&_lastUpdated=le[value]
GET /MedicationRequest?patient=[value]&_lastUpdated=gt[value]
GET /MedicationRequest?patient=[value]&_lastUpdated=ge[value]
GET /MedicationRequest?patient=[value]&_lastUpdated=eq[value]
_summary
Adding the _summary=count query parameter will change the behaviour of the query to return just the count of records, rather than the records themselves.
GET /MedicationRequest?patient=[value]&_summary=count
This will return a response like:
{
"resourceType": "Bundle",
"type": "searchset",
"total": 15,
"id": "df23fd8b-d30c-47c6-a2bd-64c8a24b1166"
}
This can be added to any query construct.
_format
The API supports both XML and JSON formats. The default format is JSON. The format can be requested either using HTTP headers or via the use of the _format query parameter as per the following table.
| Format Value | API Response Format |
|---|---|
| xml | XML |
| text/xml | XML |
| application/xml | XML |
| application/fhir+xml | XML |
| json | JSON |
| application/json | JSON |
| application/fhir+json | JSON |
GET /MedicationRequest?patient=[value]&_format=[format value]
For example the query below would return a response in XML format.
GET /MedicationRequest?patient=[value]&_format=xml
This can be added to any query construct.
Sort Parameters
The default sort order for MedicationRequest records is in descending date order (i.e. most current first).
Paging
_count
The parameter _count is defined as a hint to the server regarding how many resources should be returned in a single page.
GET /MedicationRequest?patient=[value]&_count=[n]
For example the query below would return a Bundle with 5 records per page.
GET /MedicationRequest?patient=[value]&_count=5