Skip to main content

GET MedicationRequest

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 MedicationRequest records is performed using a HTTP GET described below.

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 must always be present. The MedicationRequest can only be targeted against a single patient at any one time.

Subject​

GET /MedicationRequest?patient=Patient/{id}&intent=[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&intent=[value]

All the search examples shown below will accept the patient parameter in either form.

Intent​

To search MedicationRequests based on intent, the following can be used.

GET /MedicationRequest?patient={id}&intent=[value]

Permitted Values

CodeDefinition
proposalThe request is a suggestion made by someone/something that doesn't have an intention to ensure it occurs and without providing an authorization to act
planThe request represents an intension to ensure something occurs without providing an authorization for others to act
orderThe request represents a request/demand and authorization for action
instance-orderThe request represents an instance for the particular order, for example a medication administration record.

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]&intent=[value]&code=[code]
GET /MedicationRequest?patient=[value]&intent=[value]&code=[system]|[code]
GET /MedicationRequest?patient=[value]&intent=[value]&code=|[code]
GET /MedicationRequest?patient=[value]&intent=[value]&code=[system]|

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]&intent=[value]&code=http://snomed.info/sct|39732411000001100
tip

For further information consult the FHIR specification at http://hl7.org/fhir/STU3/search.html#token

Authored On Date​

To search on the date a MedicationRequest was authored on the following search constructs can be used.

GET /MedicationRequest?patient=[value]&intent=order&authoredon=[value]

To improve searching the API supports the use of search modifiers. The modifiers supported for date are as below:

ModifierDescription
ltReturns dates less than the search term
leReturns dates less than or equal to the search term
gtReturns dates greater than the search term
geReturns dates greater than or equal to the search term
eqReturns 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]&intent=[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]&intent=[value]&authoredon=lt2020-12-23

Identifiers​

To search for MedicationRequests using identifiers present on the MedicationRequest record, the following can be used

GET /MedicationRequest?patient=[value]&intent=[value]&identifier=[code]
GET /MedicationRequest?patient=[value]&intent=[value]&identifier=[system]|[code]
GET /MedicationRequest?patient=[value]&intent=[value]&identifier=|[code]
GET /MedicationRequest?patient=[value]&intent=[value]&identifier=[system]|

For example

GET /MedicationRequest?patient=[value]&intent=[value]&identifier=http://acme.org/medreqdata|98765-1365428
tip

For further information consult the FHIR specification at http://hl7.org/fhir/STU3/search.html#token

Status​

To search MedicationRequests based on status, the following can be used.

GET /MedicationRequest?patient={id}&intent=[value]&status=active

Permitted Values

CodeDefinition
activeThe prescription is 'actionable', but not all actions that are implied by it have occurred yet.
on-holdActions implied by the prescription are to be temporarily halted, but are expected to continue later. May also be called "suspended".
cancelledThe prescription has been withdrawn.
completedThe medication is no longer being taken.
entered-in-errorAll actions that are implied by the prescription have occurred.
stoppedActions implied by the prescription are to be permanently halted, before all of them occurred.
draftThe prescription is not yet 'actionable', i.e. it is a work in progress, requires sign-off or verification, and needs to be run through decision support process.
unknownThe authoring system does not know which of the status values currently applies for this request

_lastUpdated​

To retrieve MedicationRequests based on the updated date of the record

GET /MedicationRequest?patient={id}&_lastUpdated={value}

To improve searching the API supports the use of search modifiers. The modifiers supported for _lastUpdated are as below:

ModifierDescription
ltReturns dates less than the search term
leReturns dates less than or equal to the search term
gtReturns dates greater than the search term
geReturns dates greater than or equal to the search term
eqReturns 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={id}&intent=[value]&_summary=count

will return a response along the lines of

{
"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 ValueAPI Response Format
xmlXML
text/xmlXML
application/xmlXML
application/fhir+xmlXML
jsonJSON
text/jsonJSON
application/jsonJSON
application/fhir+jsonJSON
GET /MedicationRequest?patient={id}&intent=[value]&_format=[format value]

For example the query below would return a response in XML format.

GET /MedicationRequest?patient={id}&intent=[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​

GET /MedicationRequest?patient={id}&intent=[value]&status={code}

Examples​

Examples of payloads in both XML and JSON formats are available from the examples section of this site.