Care Centric FHIR API R4

Medication Statement

Overview

The MedicationStatement API can be used to interact with data relating to the authorisation of medications, including repeat medications for a patient. When querying for data it must always be in the context of a single patient.

Retrieving or searching for MedicationStatement records is performed using a HTTP GET described below.

GET API - MedicationStatement Retrieval

id and _id

The MedicationStatement resource can be retrieved directly if the id of the resource is known. By appending the id to the url will cause the MedicationStatement resource to be retrieved. Unlike all other retrieval queries, the response will be a single resource as opposed to a Bundle.

GET /MedicationStatement/[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 MedicationStatement resource, otherwise, the Bundle will be empty.

GET /MedicationStatement?_id=[id]

Query Parameters

Unless retrieving a MedicationStatement resource by the use of id then the subject must always be present. The MedicationStatement can only be targeted against a single patient at any one time.

Patient

GET /MedicationStatement?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 /MedicationStatement?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 MedicationStatements with a specific medication code then the query can be constructed using different combinations of the code system and the code value.

GET /MedicationStatement?patient=[value]&code=[code]
GET /MedicationStatement?patient=[value]&code=[system]|[code]

For example to search for a MedicationStatement for 'Amoxicillin 500mg capsules' using SNOMED then a query would look like the following.

GET /MedicationStatement?patient=[value]&code=http://snomed.info/sct|39732411000001100

It is possible to construct a search using text.

GET /MedicationStatement?patient=[value]&code:text=[value]

It is possible to construct a search using a predefined ValueSet that defines a collection of codes.

GET /MedicationStatement?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.

Effective Date

To search on the date a MedicationStatement was effective the following search constructs can be used.

GET /MedicationStatement?patient=[value]&effective=[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 /MedicationStatement?patient=[value]&effective=lt[value]
GET /MedicationStatement?patient=[value]&effective=le[value]
GET /MedicationStatement?patient=[value]&effective=gt[value]
GET /MedicationStatement?patient=[value]&effective=ge[value]
GET /MedicationStatement?patient=[value]&effective=eq[value]

So to search for an MedicationStatement effective on 23rd January 2021 the query would be

GET /MedicationStatement?patient=[value]&effective=2021-01-23

To search for all MedicationStatements effective before the 23rd December 2020, the following could be used:

GET /MedicationStatement?patient=[value]&effective=lt2020-12-23

Identifier

To search for MedicationStatement using an identifier on the MedicationStatement record, the following can be used

GET /MedicationStatement?patient=[value]&identifier=[system]|[value]

For example:

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

Status

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

GET /MedicationStatement?patient=[value]&status=[code]

Permitted values are codes defined in http://hl7.org/fhir/CodeSystem/medication-statement-status.

For example:

GET /MedicationStatement?patient=[value]&status=active

Last Issued Date

To search on the date a MedicationStatement was last issued the following search constructs can be used.

GET /MedicationStatement?patient=[value]&last-issued=[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 /MedicationStatement?patient=[value]&last-issued=lt[value]
GET /MedicationStatement?patient=[value]&last-issued=le[value]
GET /MedicationStatement?patient=[value]&last-issued=gt[value]
GET /MedicationStatement?patient=[value]&last-issued=ge[value]
GET /MedicationStatement?patient=[value]&last-issued=eq[value]

So to search for an MedicationStatement last issued on 23rd January 2021 the query would be:

GET /MedicationStatement?patient=[value]&last-issued=2021-01-23

To search for all MedicationStatements issued before the 23rd December 2020, the following could be used:

GET /MedicationStatement?patient=[value]&last-issued=lt2020-12-23

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

_lastUpdated

To retrieve MedicationStatements based on the updated date of the record

GET /MedicationStatement?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 /MedicationStatement?patient=[value]&_lastUpdated=lt[value]
GET /MedicationStatement?patient=[value]&_lastUpdated=le[value]
GET /MedicationStatement?patient=[value]&_lastUpdated=gt[value]
GET /MedicationStatement?patient=[value]&_lastUpdated=ge[value]
GET /MedicationStatement?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 /MedicationStatement?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 /MedicationStatement?patient=[value]&_format=[format value]

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

GET /MedicationStatement?patient=[value]&_format=xml

This can be added to any query construct.

Sort Parameters

The default sort order for MedicationStatement records is in descending date order (i.e. most current first). The following sort parameters are also available.

Date

The MedicationStatement resource can be sorted by effective date or last issued date.

GET /MedicationStatement?_sort=effective
GET /MedicationStatement?_sort=-effective
GET /MedicationStatement?_sort=last-issued
GET /MedicationStatement?_sort=-last-issued

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 /MedicationStatement?patient=[value]&_count=[n]

For example the query below would return a Bundle with 5 records per page.

GET /MedicationStatement?patient=[value]&_count=5