HL7 FHIR Implementation Guide - New Zealand Formulary/NZULM IG
1.0.0 - ci-build
HL7 FHIR Implementation Guide - New Zealand Formulary/NZULM IG, published by New Zealand Medicines Formulary LP. This guide is not an authorized publication; it is the continuous build for version 1.0.0 built by the FHIR (HL7® FHIR® Standard) CI Build. This version is based on the current content of https://github.com/HL7NZ/nzf/ and changes regularly. See the Directory of published versions
The aim of this page is to detail all the data items available from this API. For each there should be a brief description of the data along with details on how it be retrieved and used. Most of these apply to medication resources but some also use other FHIR resource types (Substance, DocumentReference).
All medication resources have a unique NZMT ID (see NZMT Data model - ID details). This is used as the ID for a medication as well as being the first code listed in the medication.code
Example FHIR Data
"code": {
"coding": [
{
"system": "http://nzmt.org.nz",
"code": "10037191000116105",
"display": "paracetamol"
}
]
}
Example Queries
The simplest way to retrieve an individual medicine resource is via the id from any level of the NZMT hierarchy
[base]/Medication/44282231000116104
Medications are also available via the code field which returns a bundle
[base]/Medication?code=http://nzmt.org.nz|44282231000116104
Definition - Medication code definition
In order to identify what type of NZMT concept a particular medicine is there is an extension call nzf-nzmt-type. This not only allows for concept identification but there is also a custom search parameter which allows for retrieval based on a particular type.
The types allowed are - mp, mpp, mpuu, tp, tpp, tpuu, ctpp
Note - NZMT substances are also available but these use the Substance resource and not the medication resource.
Example FHIR Data
{
"url": "http://hl7.org.nz/fhir/StructureDefinition/nzf-nzmt-type",
"valueCodeableConcept": {
"coding": [
{
"system": "https://standards.digital.health.nz/ns/nzmt-type-code",
"code": "mp"
}
]
}
}
Example Queries
To retrieve all MPUUs using the custom search parameter (nzf-nzmt-type)
[base]/Medication?nzf-nzmt-type=https://standards.digital.health.nz/ns/nzmt-type-code|mpuu
Note - it is possible to query without the system but for performance reasons it is not recommended
[base]/Medication?nzf-nzmt-type=mpuu
Extension - nzf-nzmt-type extension
Valueset - https://nzhts.digital.health.nz/fhir/ValueSet/nzmt-type-code
Custom search parameter - see details
MP, TP, MPP, TPP, MPUU, TPUU and substances are deemed inactive if they are either duplicates, known to be obsolete, replaced by another entry (possibly due to error) or products that have been rebranded.
A CTPP medication is deemed active if it is not deemed obsolete (as above) and at least one of the following criteria is met:
Example FHIR Data
"status": "inactive",
Examples Queries
To get a list of all ‘active’ CTPPs
[base]/Medication?status=active&nzf-nzmt-type=ctpp
To get a list of all ‘active’ MPUUs
[base]/Medication?status=active&nzf-nzmt-type=mpuu
To get a list of all ‘active’ Substances
[base]/Substance?status=active
Definition - Medication status definition
As explained in the NZMT data model the various NZMT concepts have various relationships to each other. To model these relationships there is a extension called nzf-related-medication and a related custom search parameter. This models the direct relationships, as shown in the datamodel, and also has some convenience links as well.
All medications will have one or more nzf-related-medication links to its applicable MPs.
The following table shows the related medications for each concept
Concept | Related medications |
CTPP | MP TPP TPUU MPUU TP (via TPP) |
MPP | MP MPUU (1 or more) |
MPUU | MP MPP (1 or more) |
TPP | MP TP TPUU (1 or more) MPP |
TPUU | MP TP TPP (1 or more) MPUU |
These relationships can be used after retrieving individual medication resources or for queries via the custom search parameter
Example FHIR Data
{
"extension": [
{
"url": "code",
"valueCodeableConcept": {
"coding": [
{
"system": "http://nzmt.org.nz",
"code": "10037191000116105",
"display": "paracetamol"
}
],
"text": "paracetamol"
}
},
{
"url": "type",
"valueCodeableConcept": {
"coding": [
{
"system": "https://standards.digital.health.nz/ns/nzmt-type-code",
"code": "mp"
}
]
}
}
],
"url": "http://hl7.org.nz/fhir/StructureDefinition/nzf-related-medication"
},
{
"extension": [
{
"url": "code",
"valueCodeableConcept": {
"coding": [
{
"system": "http://nzmt.org.nz",
"code": "10527591000116101"
}
]
}
},
{
"url": "type",
"valueCodeableConcept": {
"coding": [
{
"system": "https://standards.digital.health.nz/ns/nzmt-type-code",
"code": "mpp"
}
]
}
}
],
"url": "http://hl7.org.nz/fhir/StructureDefinition/nzf-related-medication"
}
Examples Queries
To get a list of all medications that are related to a given MP
[base]/Medication?nzf-related-medication=10013251000116106
This can be limited further - for example the following query gives all the Ibuprofen mpuu’s.
[base]/Medication?nzf-related-medication=10013251000116106&nzf-nzmt-type=mpuu
Extension - nzf-related-medication extension Custom search parameter - see details
Each medication has a preferred term and a fully specified name description.
A description is a text expression related to a Concept ID. Each of these descriptions has a SNOMED CT description ID of its own, in addition to the SNOMED CT Concept ID to which it is related. The primary descriptions are the FullySpecifiedName and PreferredTerm but this table includes other variant Terms or names for a substance or product. There are number of types of descriptions including Label Names, Pharmac-specific names and Prescribing Terms (see 3.5.7 for more details).
These may exist for a number of reasons. For example, some substances have very long names (Preferred Terms) but a label on a bottle only has room for 40 characters, so an alternate name of type “label” may need to be created. This would be done by a pharmacist, and would involve sensibly condensing a long name down to something that it still precise and meaningful in 40 characters or less. This will usually involve the use of common abbreviations.
There are number of possible descriptions in addition to the FullySpecifiedName and PreferredTerm including:
The Prescribing Terms description now has entries at the MPUU, MPP, TPUU and TPP level. These entries are designed to provide a standard shorter abbreviation (200 characters instead of 1000 characters) for lengthy Preferred Terms. While the field is 200 characters in length, in practice we have reduced the length of Prescribing Terms to 120 characters. Where a Prescribing Term exists, we expect it to be used as a display term in preference to the Preferred Term in prescribing systems. In the absence of a generic Prescribing Term, where a shortened name is needed, the MPUU PT is to be used.
Note that an MPUU or MPP record that has the prescribe-by-brand flag set does not have a generic Prescribing Term and the MPUU or MPP PreferredTerm should not be used as a generic Prescribing Term. For these generics, the Trade Prescribing Term is the only Prescribing Term to be used.
The Sort Names description now has entries at the CTPP and MPUU level. These entries are designed to support sorting the text Preferred Terms into ascending order by strength and unit dose. They have only been added where required, and where they do not exist the Preferred Term is used to sort for text-based sorting of the records. Note that the sort we use includes the dose form as a separate element and so the Sort Name is intended only to provide the correct ascending sequence for a given dose form.
The Synonyms description now has entries at the MP and substance level. These entries are designed to support searching for alternate names for medicines and so are currently only found at MP and substance level.
The Dispensing Term descriptions come in two types: 80-character Label Names and 40-character Label Names. These two description types now have entries at the MPUU, MPP, TPUU, TPP and CTPP level (as of release 2.8.6.0). These entries are designed to provide a standard shorter abbreviation (80 and 40 characters instead of 1000 characters) for lengthy Preferred Terms. In practice we have limited the 80-character terms to 76 characters and the 40-character terms to 36 characters to enable vendors to prefix the label with the number of units of use and suffix the label with a plural if required. All Dispensing Terms are singular to allow for consistency in their application.
Unlike the Prescribing Terms, we have included Dispensing Terms for ‘virtual’ CTPP records. These are necessarily at CTPP level and are effectively trade dispensing terms.
Note that the ‘prescribe_by_brand’ flag at MPUU or MPP level does not affect Dispensing Terms. All products that are not virtual CTPPs should have generic Dispensing Terms.
The Charting Terms description now has entries at the MPUU, MPP, TPUU and TPP level. These entries are designed to provide a standard shorter abbreviation (160 characters instead of 1000 characters) for lengthy Preferred Terms. These terms were specifically intended for use in hospital electronic charting systems. Where a Charting Term exists, we expect it to be used as a display term in preference to the Preferred Term in such systems. In the absence of a generic Prescribing Term, where a shortened name is needed, the MPUU PT is to be used.
Note that unlike the Prescribing Term an MPUU or MPP record that has the prescribe-by-brand flag set does have a generic Charting Term and the MPUU or MPP PreferredTerm should be used as a generic Charting Term where required. Another variation from the Preferred Term and the Prescribing is that the trade Charting Terms do not include details of the generic ingredients of the product.
Hospital clinicians were concerned about the level of abbreviation in the LBL80 label terms where these were used for internal hospital labels. Accordingly, we now provide an LBL160 label which has dose forms (for example) no longer abbreviated as a matter of course. These label terms are designed to provide a standard shorter abbreviation (160 characters instead of 1000 characters) for lengthy Preferred Terms for use in hospital pharmacy systems. Note that an MPUU or MPP record that has the prescribe-by-brand flag set still has a generic LBL160 Term.
There are three terms intended to provide alternate descriptions using Tallman Lettering, as recommended by the Health Quality and Safety Commission. There are alternates to the Preferred Term, the Prescribing Term and the Charting Term, and are intended to allow for safer selection of medicine through the use of the Tallman Lettering convention. For substance, MP and TP the alternate TallMan terms are all alternates to the PreferredTerm. For MPUU, TPUU, MPP and TPP the alternate TallMan terms are alternates to the Charting Term and the Prescribing Term.
This term is the American CVX vaccine code. This alternate description exists to provide an additional method of searching for specific vaccines. More than one code may be present for a given NZMT record. These codes are linked to MP and TP records.
These descriptions are added to each medication resource via the nzf-description extension. This extension contains two fields, firstly the type of the description and secondly the description term.
There is also a custom search parameter on the preferred-term allowing for normal FHIR search based expressions - see FHIR search documentation
Example FHIR Data
{
"extension": [
{
"url": "type",
"valueCodeableConcept": {
"coding": [
{
"system": "http://nzmt.org.nz",
"code": "20069041000116103",
"display": "Label name (80)"
}
],
"text": "Label name (80)"
}
},
{
"url": "term",
"valueCodeableConcept": {
"coding": [
{
"system": "http://nzmt.org.nz",
"code": "44578011000116118",
"display": "paracetamol powder"
}
],
"text": "paracetamol powder"
}
}
],
"url": "http://hl7.org.nz/fhir/StructureDefinition/nzf-description"
}
Examples Queries
Search for a medication based on part of the preferred term
[base]/Medication?nzf-preferred-term:contains=purified
Search for a CTPP medication based on part of the preferred term
[base]/Medication?nzf-preferred-term:contains=purified&nzf-nzmt-type=ctpp
Extension - nzf-related-medication extension
Custom search parameter - see details
The manufactured dose form is added to MPUU and TPUUs.
Example FHIR Data
form": {
"coding": [
{
"system": "http://nzmt.org.nz",
"code": "147011000036100",
"display": "powder"
}
]
}
Examples Queries
Get medications that have a form of ‘powder’
[base]/Medication?form=147011000036100
Definition - Medication form
The majority of medications resources have their ingredients listed. The exceptions to this are those that do not have known active medicinal ingredients, typical examples being medicinal devices and special foods.
Each ingredient listed is a NZMT substance and where possible a strength is provided. The ingredients listed are derived from the list of substances assigned to a given MP. Therefore if a medication resource has multiple MPs, each of the substances for each of the MPs will be listed. This means that it is possible to have duplicated substances for certain concepts in the Medication hiearchy.
Strength information is determined at an MPUU level and assigned to the given ingredient substances (from the MP). Once again this means that some NZMT concepts that have multiple MPUUs will sometimes have repeated ingredients, at the same or varying strengths.
Both MP and TP concepts do not have strength information but will have ingredients listed where possible.
Medications regularly have ‘alternate strength representation’ which are a piece of text used where the ingredient strength is expressed in a form that does not fit into a numerator/denominator pattern or does not include any of the unit dose forms used in the NZMT e.g. 1 in 10,000, 10%. These are also added as an extension to the strength field where applicable.
Background: For those familar with the original NZMT dataset the strength information is derived from the NZMT MPUUSAI records (hence the MPUU level). The difference with these records is that these aren’t always assigned to a MPUU/MP Substance as they could be assigned at a salt level. Considerable work as been done to match these records to the associated MPUU/MP Substance however if the base/salt ingredient from the MPUUSAI record does differ from the MPUU/MP Substance record then an extension is added to the strength field, specifying this substance. See below for an example.
Example FHIR Data
cilazapril 1 mg tablet (mpuu) ingredient field
"ingredient": [
{
"itemCodeableConcept": {
"coding": [
{
"system": "http://nzmt.org.nz",
"code": "10000191000116103",
"display": "cilazapril"
}
]
},
"isActive": true,
"strength": {
"numerator": {
"value": 1,
"unit": "mg",
"system": "http://nzmt.org.nz",
"code": "99011000036109"
}
}
}
]
Nurofen Cold & Flu With Decongestant tablet: film-coated, 24 tablets, blister pack (ctpp) ingredients
"ingredient": [
{
"itemCodeableConcept": {
"coding": [
{
"system": "http://nzmt.org.nz",
"code": "2211011000036101",
"display": "ibuprofen"
}
]
},
"isActive": true,
"strength": {
"numerator": {
"value": 200,
"unit": "mg",
"system": "http://nzmt.org.nz",
"code": "99011000036109"
}
}
},
{
"extension": [
{
"url": "http://hl7.org.nz/fhir/StructureDefinition/nzf-specific-substance",
"valueCodeableConcept": {
"coding": [
{
"system": "http://nzmt.org.nz",
"code": "2526011000036108",
"display": "pseudoephedrine hydrochloride"
}
],
"text": "pseudoephedrine hydrochloride"
}
}
],
"itemCodeableConcept": {
"coding": [
{
"system": "http://nzmt.org.nz",
"code": "2525011000036101",
"display": "pseudoephedrine"
}
]
},
"isActive": true,
"strength": {
"numerator": {
"value": 30,
"unit": "mg",
"system": "http://nzmt.org.nz",
"code": "99011000036109"
}
}
}
]
Examples Queries
Get medications that have pseudoephredrine as an ingredient
[base]/Medication?ingredient-code=http://nzmt.org.nz|2525011000036101
Get MPUU medications that have pseudoephredrine as an ingredient
[base]/Medication?ingredient-code=http://nzmt.org.nz|2525011000036101&nzf-nzmt-type=mpuu
Definition - Medication ingredients
[TODO] Add nzf-specific-substance and alternate strength extension details
As mentioned above all ingredients are listed as NZMT substances. All NZMT substances are available via the Substance FHIR resource. These contain minimal data but do have their status flag set, active or inactive.
Example FHIR Data
{
"resourceType": "Substance",
"id": "47575401000116106",
"meta": {
"versionId": "1",
"lastUpdated": "2023-06-18T20:54:06.17+00:00"
},
"status": "active",
"code": {
"coding": [
{
"system": "http://nzmt.org.nz",
"code": "47575401000116106",
"display": "amivantamab"
}
]
}
}
Examples Queries
Get a list of all substances
[base]/Substance
Definition - FHIR Substance definition
Some generic medications should, for safety reasons, be prescribed by brand and have no generic prescribing term. Medicines appearing in this extension are defined by the application of the Health Quality and Safety Commission’s Specify Brand Advice Guidance rules.
These are indicated via the nzf-prescribe-by-brand extension and is set to true when this applies. There is also a custom search parameter available to allow for searching via this extension.
Example FHIR Data
{
"url": "http://hl7.org.nz/fhir/StructureDefinition/nzf-prescribe-by-brand",
"valueBoolean": true
}
Examples Queries
Get a list of all prescribe-by-brand medications
[base]/Medication?nzf-prescribe-by-brand=true
Extension - nzf-prescribe-by-brand extension
Custom search parameter - see details
NB: section 29 medicines are medicines covered by the Medicines Act that have not been granted formal consent to distribute by Medsafe. They are supplied under the compassionate use provisions of Section 29 of the Medicines Act
These are indicated via the nzf-unapproved extension and is set to true when this applies. This extension applies to Medications at the CTPP level. There is also a custom search parameter available to allow for searching via this extension.
Example FHIR Data
{
"url": "http://hl7.org.nz/fhir/StructureDefinition/nzf-unapproved",
"valueBoolean": true
}
Examples Queries
Get a list of all unapproved medications
[base]/Medication?nzf-unapproved=true
Extension - nzf-unapproved extension
Custom search parameter - see details
CTPP, TPP, TPUU, MPP, MPUU and MP medications can be linked to one or more ATC codes.
Note that not all medications are linked. There are, for example a number of items in the NZMT that simply don’t have an ATC code (particularly in the area of devices) because they do not fall within the coverage of the ATC system. In addition, we chose not to add an ATC link to the MPUU and TPUU records for inert substances (diluents and similar) to avoid the potential for user confusion.
This is modelled via the nzf-atc code extension.
Example FHIR Data
{
"url": "http://hl7.org.nz/fhir/StructureDefinition/nzf-atc",
"valueCodeableConcept": {
"coding": [
{
"system": "http://www.whocc.no/atc",
"code": "N02BE01",
"display": "Paracetamol"
}
],
"text": "Paracetamol"
}
}
Examples Queries
Get a list of medications with the paracetamol ATC code
[base]/Medication?nzf-atc=N02BE01
Extension - nzf-atc extension
Valueset - http://www.whocc.no/atc
Custom search parameter - see details
GTINs are GS1 Global Trade Identification Numbers. They are the most common type of barcode / number found on all kinds of products.
GS1 regulations require a new GTIN every time the product formulation or packaging changes, so there may be more than one GTIN for a given CTPP (physical product pack), in which case there will be a code for each GTIN.
These code(s) are added as codes in the medication code field
Example FHIR Data
"code": {
"coding": [
{
"system": "http://nzmt.org.nz",
"code": "50066481000117107",
"display": "Paracetamol (Amcal) orange 250 mg/5 mL oral liquid: suspension, 200 mL, bottle"
},
{
"system": "https://www.gs1.org/gtin",
"code": "09403092340084"
}
]
}
Examples Queries
Get a medication based on its GTIN code
[base]/Medication?code=https://www.gs1.org/gtin|09403092340084
Valueset - https://www.gs1.org/gtin
Where applicable mappings and are available the NZMT MPs have been mapped to SNOMED CT MP Products.
These codes are added as a code in the medication code field alongside the NZMT code and any other applicable code.
Example FHIR Data
"code": {
"coding": [
{
"system": "http://nzmt.org.nz",
"code": "10037191000116105",
"display": "paracetamol"
},
{
"system": "http://snomed.info/sct",
"code": "90332006",
"display": "Product containing paracetamol (medicinal product)"
}
]
}
Examples Queries
Get a medication based on its SNOMED CT code
[base]/Medication?code=http://snomed.info/sct|90332006
Get all medications that have a SNOMED CT code assigned
[base]/Medication?code=http://snomed.info/sct|
Legal classifications, provided by Medsafe, are primarily added to CTPPs via the nzf-legalclass extension. However, for convenience, the legal classification extension is also added to TPUU and MPUU where all the related CTPPs have the same legal classification.
See here for a list of possible values
Note - Medsafe also provide classifications at the substance level. This has been added against MPs where applicable using the nzf-legalclass extension.
Note that products unmapped to Medsafe (and therefore not considered registered) should only use this MP/Substance classification data where the classification is as a ‘Controlled Drug’ - as the Misuse of Drugs Act is separate from the Medicines Act and applies regardless of whether the sponsor has registered the product or not. Any other classification (General Sale, Prescription etc) requires the product to be registered and so these classifications are not appropriate to be used for unregistered products.
Example FHIR Data
CTPP (MPUU/TPUU) level
{
"extension": [
{
"url": "code",
"valueCodeableConcept": {
"coding": [
{
"system": "https://standards.digital.health.nz/ns/medicine-classification-code",
"code": "PO"
}
],
"text": "Pharmacy only"
}
}
],
"url": "http://hl7.org.nz/fhir/StructureDefinition/nzf-legalclass"
}
MP level
{
"extension": [
{
"url": "substance",
"valueCodeableConcept": {
"coding": [
{
"system": "http://nzmt.org.nz",
"code": "2442011000036104"
}
],
"text": "paracetamol"
}
},
{
"url": "classification",
"valueCodeableConcept": {
"text": "Prescription"
}
},
{
"url": "conditions",
"valueString": "<strong>except</strong> when specified elsewhere in this schedule"
}
],
"url": "http://hl7.org.nz/fhir/StructureDefinition/nzf-legalclass"
}
Extension - nzf-legalclass extension
Valueset - Definition
NZF Pack details based on linked NZMT TPUU (Trade Product Unit of Use) details are added to CTPPs via the nzf-pack extension.
Example FHIR Data
CTPP level
{
"extension": [
{
"url": "nzmtMedicineCode",
"valueCodeableConcept": {
"coding": [
{
"system": "http://nzmt.org.nz",
"code": "10491491000116107"
}
]
}
},
{
"url": "quantity",
"valueQuantity": {
"value": 12,
"unit": "tablet",
"system": "http://nzmt.org.nz",
"code": "63011000036109"
}
},
{
"url": "size",
"valueQuantity": {
"value": 1,
"unit": "tablet",
"system": "http://nzmt.org.nz",
"code": "63011000036109"
}
}
],
"url": "http://hl7.org.nz/fhir/StructureDefinition/nzf-pack"
}
Every monograph in the both the Adult and Childrens formularies has a DocumentReference. These references contain a url link to the respective monographs on the nzf.org.nz and nzfchildren.org.nz websites.
Every medication that is contained in a monograph, both adults and children has a link to its associated monograph(s). This is done via the nzf-link extension which links to the DocumentReference(s) for the monograph.
Example FHIR Data
Url contained in monograph document reference
"content": [
{
"attachment": {
"url": "https://nzfchildren.org.nz/nzfc_2439",
"title": "paracetamol"
}
}
]
Link contained in medication resource
{
"url": "http://hl7.org.nz/fhir/StructureDefinition/nzf-link",
"valueReference": {
"reference": "DocumentReference/8b9466cb-ebe8-4526-bd8a-6ba092630525",
"identifier": {
"system": "https://standards.digital.health.nz/ns/nzf-monograph-code",
"value": "nzf_2439"
},
"display": "nzf_2439"
}
},
{
"url": "http://hl7.org.nz/fhir/StructureDefinition/nzf-link",
"valueReference": {
"reference": "DocumentReference/1421eb52-b576-4f14-a837-d35303b13982",
"identifier": {
"system": "https://standards.digital.health.nz/ns/nzf-monograph-code",
"value": "nzf_9575"
},
"display": "nzf_9575"
}
}
Example Queries
Get a list of all NZF monographs (Adult monographs)
[base]/DocumentReference?type=https://standards.digital.health.nz/ns/nzf-document-type-code|AdultMonograph
Get a list of all NZFC monographs (Child monographs)
[base]/DocumentReference?type=https://standards.digital.health.nz/ns/nzf-document-type-code|ChildMonograph
Get a list of medications that are contained in a monograph
[base]Medication?nzf-link=DocumentReference/a8e50e23-773a-46d5-8f38-544b0dc89857&_elements=code
Get a Medication including its associated document references in the returned bundle. Once returned the nzf/c monograph urls can be extracted.
[base]/Medication?code=10037191000116105&_include=Medication:nzf-link
Extension - nzf-link extension
Valueset - Definition
Aside from the legal classification information explained above there is also a number of additional pieces of medsafe information provided. These are added to CTPPs where the data exists. These are:
Example FHIR Data
{
"extension": [
{
"url": "status",
"valueCodeableConcept": {
"text": "Active"
}
},
{
"url": "regSituation",
"valueCodeableConcept": {
"text": "Consent given"
}
},
{
"url": "administrationRoute",
"valueCodeableConcept": {
"text": "Oral"
}
}
],
"url": "http://hl7.org.nz/fhir/StructureDefinition/nzf-medsafe"
}
Extension - nzf-medsafe extension
Extension - nzf-link extension
Subsidy information is added to Containered Trade Product Packs where applicable. The funding information is derived from both the PHARMAC community schedule as well as the HML.
There are two extensions added that store this information. The first is nzf-funding. This stores the general information around funding for a specific product, such as price, subsidy and for community schedules, the claim unit (further description pending) - see extension details for more information. To cater for the existence of multiple schedules this extension can be added to a product multiple times, once per schedule (i.e. the current schedule and an upcoming (draft) schedule).
To make it easy to determine which schedules are available we provide a metadata resource. This lists the available schedules on the dataset at any given time. This allows vendors to see both the current schedule information as well as an upcoming schedule between the release of the Schedule for the coming month and the end of the calendar month. To determine which set of information to use the ‘scheduleDate’ field can be used. The second extension is nzf-funding-rule. This extension once again has a schedule date so vendors can determine which schedule they would like to look at. The purpose of this extension is to provide the PHARMAC funding rules that apply to the given product.
A funding rule consists of the following data:
This rule is an amendment to other rules and is identified by a value in the waiver field. It may modify any of the rules below. In the July 2023 Pharmaceutical Schedule there are waivers on some instances of the FormMax, FormWt, TreatMax and SubRxF rules.
Where any rule has a waiver = ‘Special’, each applicable medicine has an additional text after the rule text of ‘can be waived by Special Authority’. The SA Form Id will be populated in RuleXlinkHref field.
Where any rule has a waiver = ‘SubRxF’, each applicable medicine has an additional text after the rule text of ‘can be waived by endorsement’. Where any rule has a waiver = ‘SpecEnd’, each applicable medicine has an additional text after the rule text of ‘can be waived by endorsement – Retail Pharmacy – Specialist’.
In both ‘Special’ and ‘Restricted’ rules the ruleAdditionalData field is populated with Request XML.
Each request contains one Title element and one or more Case elements. Within each case element, there will be a math block detailing the conditions of the case, plus one or more applicant elements and a Term element.
There are a large number of funding rule types in the data. Below is a list of all the rule types in the data as at Jul 2023.
Indicates that there are circumstances in which an alternate level of subsidy applies
NB: the Special Authority system requires the prescriber to obtain permission (a special authority) to subsidise a medicine before initiating therapy. The system is used to ensure the medicine is only prescribed for patients meeting defined clinical criteria.
Type | Rule Type | Value | Rule Attribute | Rule Waiver | Rule XlinkHref | Rule Text | Rule Additional Data |
Community | Alternate | Endorsement | Higher subsidy with Endorsement. | ||||
Community | Alternate | Special Authority | Higher subsidy with Special Authority. |
Indicates that a Brand Switch Fee is payable
NB: the Brand Switch Fee allows pharmacists to be reimbursed for time spent advising patients on the impact of impending changes to subsidised medicines. For charging purposes these Fees have been issued with specific pharmacodes but they are Fees only, not medicines. The text, however, is attached to the original medicine for which the fee can be charged.
Type | Rule Type | Value | Rule Attribute | Rule Waiver | Rule XlinkHref | Rule Text | Rule Additional Data |
Community | Brandswitch | [Specific product involved, e.g. Noumed Phenobarbitone] | [e.g. A35] | Brand Switch Fee payable. |
Each applicable medicine has an additional text of ‘Only in combination’.
NB: This means that the medicine is only subsidised if prescribed in combination with another subsidised medicine.
Type | Rule Type | Value | Rule Attribute | Rule Waiver | Rule XlinkHref | Rule Text | Rule Additional Data |
Community | Combined | Only in combination. |
Not displayed
Type | Rule Type | Value | Rule Attribute | Rule Waiver | Rule XlinkHref | Rule Text | Rule Additional Data |
Community | Contraceptive |
Each applicable medicine has an additional text of ‘Only on a Controlled Drug form’.
NB: Controlled Drugs are medicines which may be abused and are addictive. Their management is governed by the Misuse of Drugs Act and regulations which requires them to be prescribed on special prescription forms.
Type | Rule Type | Value | Rule Attribute | Rule Waiver | Rule XlinkHref | Rule Text | Rule Additional Data |
Community | Controlled | Only on a Controlled Drug form. |
Type | Rule Type | Value | Rule Attribute | Rule Waiver | Rule XlinkHref | Rule Text | Rule Additional Data |
Community | CostBrandSource | costbrandsource | CBS |
NB: some medicines may only be dispensed by hospital pharmacies or community pharmacies holding specific Te Whatu Ora contract variations which permit them to dispense these medicines.
Type | Rule Type | Value | Rule Attribute | Rule Waiver | Rule XlinkHref | Rule Text | Rule Additional Data |
Community | Dispensary | HP3 | Hospital Pharmacy HP3. | ||||
Community | Dispensary | HP4 | Hospital Pharmacy HP4. | ||||
Community | Dispensary | Xpharm | Hospital Pharmacy (Xpharm) |
A restrictions on the amount of medicine to be supplied per day
Type | Rule Type | Value | Rule Attribute | Rule Waiver | Rule XlinkHref | Rule Text | Rule Additional Data |
Community | DoseDMax | No more than [value] [units] per day. [e.g. No more than 2 dose per day.] |
A restrictions on the amount of medicine to be supplied per dose
Type | Rule Type | Value | Rule Attribute | Rule Waiver | Rule XlinkHref | Rule Text | Rule Additional Data |
Community | DoseSWt | No more than [ps_rule.value] mg per dose. [e.g. No more than 100 mg per dose.] |
A restrictions on the amount of medicine to be supplied per week
Type | Rule Type | Value | Rule Attribute | Rule Waiver | Rule XlinkHref | Rule Text | Rule Additional Data |
Community | DoseWMax | No more than [value] [units] per week. [e.g. No more than 1 patch per week.] |
These are similar restriction rules to above which could be used but are not in the current dataset.
This means either the national or individual limit placed on a particular pharmaceutical with Hospital Supply Status.
Type | Rule Type | Value | Rule Attribute | Rule Waiver | Rule XlinkHref | Rule Text | Rule Additional Data |
HML | DVLimit | value | [e.g. DV Sep-22 to 2025] | [value]% DV [attribute] - [e.g. 5% DV Sep-22 to 2025] |
Each applicable medicine has an additional text ‘Not on a [attribute]’.
NB: this rule allows prescribing of a medicine to be restricted to particular prescription form types.
Type | Rule Type | Value | Rule Attribute | Rule Waiver | Rule XlinkHref | Rule Text | Rule Additional Data |
HML | FormBan | [populated, July 2023 dataset only has BSO used] | Not on a BSO. |
Where the waiver = ‘Special’ then ‘Can be waived by Special Authority’ is appended to the rule text.
NB: This allows for quantities to be limited when prescribed on a particular form type.
Type | Rule Type | Value | Rule Attribute | Rule Waiver | Rule XlinkHref | Rule Text | Rule Additional Data |
Community | FormMax | PSO | Up to [value] [units] available on a PSO. [e.g. Up to 5 tab available on a PSO.] | ||||
Community | FormMax | Rx | Maximum of [value] [units] per prescription. [e.g. Maximum of 130 g per prescription.] |
NB: this rule allows prescribing of a medicine to be restricted to particular prescription form type.
Type | Rule Type | Value | Rule Attribute | Rule Waiver | Rule XlinkHref | Rule Text | Rule Additional Data |
Community | FormReqd | Rx | Only on a prescription. | ||||
Community | FormReqd | PSO | Only on a PSO. | ||||
Community | FormReqd | QEC | Only on a Quitcard. |
Where the waiver = ‘Special’ then ‘Can be waived by Special Authority’ is appended to the rule text.
Type | Rule Type | Value | Rule Attribute | Rule Waiver | Rule XlinkHref | Rule Text | Rule Additional Data |
Community | FormWt | PSO | Maximum of [ps_rule.value] mg per PSO. | ||||
Community | FormMax | Rx | Maximum of [value] mg per prescription. [e.g. Maximum of 500 mg per prescription. Can be waived by Special Authority.] |
Type | Rule Type | Value | Rule Attribute | Rule Waiver | Rule XlinkHref | Rule Text | Rule Additional Data |
HML | HospitalSupplyStatus | HSS | Hospital Supply Status. |
Where the value = ‘0’, each applicable medicine has an additional text of ‘No patient co-payment payable’. Where the value > ‘0’, each applicable medicine has an additional text of ‘Maximum patient co-payment payable: $[ps_rule.value]’.
NB: CoPayments are charges the patient must pay for a subsidised medicine..
Type | Rule Type | Value | Rule Attribute | Rule Waiver | Rule XlinkHref | Rule Text | Rule Additional Data |
Community | MaxCoPayment | 0 | No patient co-payment payable. | ||||
Community | MaxCoPayment | value | Maximum patient co-payment payable: $[value] [e.g. Maximum patient co-payment payable: $5] |
NB: This means a medicine is not subsidised if prescribed as a compound with other ingredients.
Type | Rule Type | Value | Rule Attribute | Rule Waiver | Rule XlinkHref | Rule Text | Rule Additional Data |
Community | NotCombined | Not in combination. |
Type | Rule Type | Value | Rule Attribute | Rule Waiver | Rule XlinkHref | Rule Text | Rule Additional Data |
Community, HML | Note | [HTML from schedule] |
Type | Rule Type | Value | Rule Attribute | Rule Waiver | Rule XlinkHref | Rule Text | Rule Additional Data |
Community | OriginalPack | Original Pack. |
Where the ps_rule.attribute is blank, each applicable medicine has an additional text of ‘PCT’.
Where the ps_rule.attribute is ‘only’, each applicable medicine has an additional text of ‘PCT only’.
Type | Rule Type | Value | Rule Attribute | Rule Waiver | Rule XlinkHref | Rule Text | Rule Additional Data |
Community | PCT | Pharmaceutical Cancer Treatment. | |||||
Community | PCT | only | Pharmaceutical Cancer Treatment only. |
Each applicable medicine has an additional text of ‘Eligible for a subsidy by a Pharmacist’.
Products with this rule are usually accompanied by a ps_note record reading ‘Note: Direct Provision by a pharmacist permitted under the provisions in Part I of Section A.’
NB: This rule allows community pharmacists to provide subsidised product to patients without the patient needing a prescription. It is designed to remove access barriers for emergency contraception and smoking cessation therapy.
Type | Rule Type | Value | Rule Attribute | Rule Waiver | Rule XlinkHref | Rule Text | Rule Additional Data |
Community | ProvAllow | Eligible for a subsidy by a Pharmacist. |
[TODO]
Type | Rule Type | Value | Rule Attribute | Rule Waiver | Rule XlinkHref | Rule Text | Rule Additional Data |
Community, HML | pss | Principal Supply Status |
Not currently in use in the xml version of the Pharmaceutical Schedule.
This Rule Type is not printed.
Type | Rule Type | Value | Rule Attribute | Rule Waiver | Rule XlinkHref | Rule Text | Rule Additional Data |
HML | Restricted | HML Restriction. | Request XML |
Type | Rule Type | Value | Rule Attribute | Rule Waiver | Rule XlinkHref | Rule Text | Rule Additional Data |
Community | RFPP | value | The maximum quantity ordered on a PSO for providers in the Rheumatic Fever Prevention Programme (RFPP) may be up to [value] times the maximum quantity . The PSO must specify the order quantity in course-specific amounts to enable the pharmacy to dispense each course separately. |
[TODO]
Type | Rule Type | Value | Rule Attribute | Rule Waiver | Rule XlinkHref | Rule Text | Rule Additional Data |
Community | SafetyListMedicine | Safety medicine; prescriber may determine dispensing frequency |
NB: section 29 medicines have not been granted formal consent to distribute by Medsafe. They are supplied under the compassionate use provisions of Section 29 of the Medicines Act
Type | Rule Type | Value | Rule Attribute | Rule Waiver | Rule XlinkHref | Rule Text | Rule Additional Data |
Community | Section29 | Unapproved medicine supplied under Section 29 |
Type | Rule Type | Value | Rule Attribute | Rule Waiver | Rule XlinkHref | Rule Text | Rule Additional Data |
Community | SoleSupply | Sole Subsidised Supply |
If the ps_rule.attribute of this rule is ‘Retail’ each applicable medicine has an additional text of ‘Retail pharmacy - Specialist’.
If the ps_rule.attribute of this rule is ‘Hospital’ or blank each applicable medicine has an additional text of ‘Specialist’.
The waiver field can be populated and this adjusts the rule text.
NB: This means that a medicine is only subsidised if prescribed by a specialist or endorsed as being recommended by a specialist.
Type | Rule Type | Value | Rule Attribute | Rule Waiver | Rule XlinkHref | Rule Text | Rule Additional Data |
Community | SpecEnd | Specialist. | |||||
Community | SpecEnd | Hospital | Specialist. | ||||
Community | SpecEnd | Retail | Retail pharmacy – Specialist. |
Not currently used
NB: This means that the medicine is only subsidised if prescribed by a specialist.
Each applicable medicine has an additional text ‘Special Authority see [ps_rule.sa_form] below’.
Type | Rule Type | Value | Rule Attribute | Rule Waiver | Rule XlinkHref | Rule Text | Rule Additional Data |
Community | Special | Subsidy | Special Authority Form Id [e.g. SA2229] | Special Authority | [The request xml, including MathML] | ||
Community | Special | Price | Special Authority Form Id [e.g. SA2229] | Additional subsidy by Special Authority | [The request xml, including MathML] |
Type | Rule Type | Value | Rule Attribute | Rule Waiver | Rule XlinkHref | Rule Text | Rule Additional Data |
Community | Statim | Must | Statim: Three months or six months, as applicable, dispensed all-at-once. | ||||
Community | Statim | May | Statim: Three months supply may be dispensed at one time if endorsed ‘certified exemption’ by the prescriber. |
Each applicable medicine has an additional text ‘Subsidy by Endorsement’.
PHARMAC’s convention in the Pharmaceutical Schedule is to print the related note describing the endorsement conditions (present in div tag on the Schedule describing prescription conditions) after all applicable medicines.
The waiver field can be populated and this adjusts the rule text.
Type | Rule Type | Value | Rule Attribute | Rule Waiver | Rule XlinkHref | Rule Text | Rule Additional Data |
Community | SubRxF | Must | Subsidy by Endorsement. |
Not currently in use in the xml version of the Pharmaceutical Schedule.
Each applicable medicine has an additional text ‘Wastage rule applies’.
Type | Rule Type | Value | Rule Attribute | Rule Waiver | Rule XlinkHref | Rule Text | Rule Additional Data |
Community | Wastage | Wastage rule applies |
Example FHIR Data
{
"resourceType": "Basic",
"id": "metadata",
"extension": [
{
"extension": [
{
"url": "date",
"valueDate": "2023-07-01"
},
{
"url": "type",
"valueCodeableConcept": {
"coding": [
{
"system": "https://standards.digital.health.nz/ns/nzf-funding-type",
"code": "community",
"display": "community"
}
],
"text": "community"
}
},
{
"url": "id",
"valueString": "929"
}
],
"url": "pharmacSchedule"
},
{
"extension": [
{
"url": "date",
"valueDate": "2023-07-01"
},
{
"url": "type",
"valueCodeableConcept": {
"coding": [
{
"system": "https://standards.digital.health.nz/ns/nzf-funding-type",
"code": "hml",
"display": "hml"
}
],
"text": "hml"
}
},
{
"url": "id",
"valueString": "927"
}
],
"url": "pharmacSchedule"
}
],
"code": {
"text": "metadata"
}
}
Example Queries
Get the API metadata, which includes the schedule details.
[base]/Basic/metadata
Get all medications that have funding information for the given schedule data.
[base]/Medication?nzf-funding-schedule-date=2023-07-01
Get all medications that have funding rules for the given schedule data.
[base]/Medication?nzf-funding-rule-schedule-date=2023-07-01
Extension - nzf-funding extension
Extension - nzf-funding-rule extension
Where applicable Pharmacodes® are added to CTPP resources.
These codes are added as a code in the medication code field alongside the NZMT code and any other applicable code.
A primary pharmacode is indicated via the nzf-is-primary-coding extension (shown below) and older codes are also added where applicable.
Note - the code system used for Pharmacode® is https://standards.digital.health.nz/ns/pharmac-subsidy-code. The reason for this is that on occassion a new code can be created by PHARMAC for generic funding purposes.
Example FHIR Data
"coding": [
{
"system": "http://nzmt.org.nz",
"code": "50059891000117106",
"display": "Nurofen Cold & Flu With Decongestant tablet: film-coated, 24 tablets, blister pack"
},
{
"system": "https://www.gs1.org/gtin",
"code": "05000167010886"
},
{
"extension": [
{
"url": "http://hl7.org.nz/fhir/StructureDefinition/nzf-is-primary-coding",
"valueBoolean": true
}
],
"system": "https://standards.digital.health.nz/ns/pharmac-subsidy-code",
"code": "270180"
}
]
Examples Queries
Get a medication based on Pharmacode®
[base]/Medication?code=https://standards.digital.health.nz/ns/pharmac-subsidy-code|270180
Get all medications that have a Pharmacode® assigned
[base]Medication?code=https://standards.digital.health.nz/ns/pharmac-subsidy-code|
Pharmac provide details on supply issues, discontinuations, and brand changes associated with Pharmac funded medicines. These are applied at any of the main NZMT concept levels.
Example FHIR Data
{
"extension": [
{
"url": "type",
"valueCodeableConcept": {
"text": "Supply"
}
},
{
"url": "duration",
"valueCodeableConcept": {
"text": "Permanent"
}
},
{
"url": "solution",
"valueString": "No replacement"
},
{
"url": "action",
"valueString": "Prescribing action"
},
{
"url": "title",
"valueString": "Cilazapril: No new patients from 1 May 2021"
},
{
"url": "date",
"valueDateTime": "2021-03-11T00:00:00+13:00"
},
{
"url": "information",
"valueString": "Cilazapril funded access will be for existing patients only from 1 April 2021 in hospitals and from 1 May 2021 in the community"
},
{
"url": "url",
"valueUrl": "https://pharmac.govt.nz/medicine-funding-and-supply/medicine-notices/cilazapril/"
}
],
"url": "http://hl7.org.nz/fhir/StructureDefinition/nzf-supply-information"
}
Example Queries
To get a list of all the medications with pharmac supply information.
[base]/Medication?nzf-supply-information-type:missing=false
Extension - nzf-supply-information extension
Custom search parameter - see details
Cautionary Advisory Labels provide brief, important information for patients. Medicines dispensed by pharmacies usually include this information within their labelling or as a supplementary yellow label. Additional comments provide practical advice on how to take the medicine. [FROM BPAC]
CALs are assigned at an MPUU level and are provided for medications via the nzf-cal extension. This extension is added to applicable MPUUs but is also added to MPP, TPP and CTPPs via their associated MPUUs.
Example FHIR Data
{
"url": "id",
"valueId": "155"
},
{
"url": "labelType",
"valueString": "comment"
},
{
"url": "text",
"valueString": "Maximum dose 4g paracetamol daily (adults)."
}
],
"url": "http://hl7.org.nz/fhir/StructureDefinition/nzf-cal"
}
The New Zealand contains or links to a number of Patient Information Leaflets.
Each of these Patient Information leaflets is referenced by a DocumentReference resource. A patient information contains links to PDFs which can have varying page sizes (A4,A5) and can potentially be in English or Te Reo.
A patient information leaflet can potentially also have more information around its context, for example, the dose form it applies to. See the extension definition for more details.
Example FHIR Data
Document reference content, detailing urls, page size and language.
"content": [
{
"attachment": {
"extension": [
{
"url": "http://hl7.org.nz/fhir/StructureDefinition/nzf-page-size",
"valueCodeableConcept": {
"coding": [
{
"system": "https://standards.digital.health.nz/ns/nzf-page-size-code",
"code": "A4",
"display": "A4"
}
],
"text": "A4"
}
}
],
"contentType": "application/pdf",
"language": "en-NZ",
"url": "http://www.mymedicines.nz/home/sheet/Paracetamol?format=pdfA4&inline=true",
"title": "Paracetamol"
}
},
{
"attachment": {
"extension": [
{
"url": "http://hl7.org.nz/fhir/StructureDefinition/nzf-page-size",
"valueCodeableConcept": {
"coding": [
{
"system": "https://standards.digital.health.nz/ns/nzf-page-size-code",
"code": "A5",
"display": "A5"
}
],
"text": "A5"
}
}
],
"contentType": "application/pdf",
"language": "en-NZ",
"url": "http://www.mymedicines.nz/home/sheet/Paracetamol?format=pdfA5&inline=true",
"title": "Paracetamol"
}
},
{
"attachment": {
"extension": [
{
"url": "http://hl7.org.nz/fhir/StructureDefinition/nzf-page-size",
"valueCodeableConcept": {
"coding": [
{
"system": "https://standards.digital.health.nz/ns/nzf-page-size-code",
"code": "A4",
"display": "A4"
}
],
"text": "A4"
}
}
],
"contentType": "application/pdf",
"language": "mi",
"url": "https://mymedicines.nz/TeReo/NZF/Paracetamol.pdf",
"title": "Paracetamol"
}
}
],
"context": {
"extension": [
{
"url": "http://hl7.org.nz/fhir/StructureDefinition/nzf-pil-source",
"valueCodeableConcept": {
"text": "MyMedicine"
}
},
{
"url": "http://hl7.org.nz/fhir/StructureDefinition/nzf-pil-formulary",
"valueCodeableConcept": {
"text": "NZF"
}
}
]
}
Link contained in medication resource
{
"url": "http://hl7.org.nz/fhir/StructureDefinition/nzf-link",
"valueReference": {
"reference": "DocumentReference/aa21fb13-46c5-4ebe-93cf-3bbfb4da68a3",
"display": "Patient Information Leaflet"
}
}
Example Queries
Get a list of all NZF monographs (Adult monographs)
[base]/DocumentReference?type=https://standards.digital.health.nz/ns/nzf-document-type-code|PIL
Get a Medication including its associated document references in the returned bundle. Once returned these can be used to extract the PIL urls.
[base]/Medication?code=10037191000116105&_include=Medication:nzf-link
Extension - nzf-link extension
Medication sponsor details are added to TPs using an Organization resource reference in the nzf-medication-sponsor extension.
Example FHIR Data
TP level
{
"extension": [
{
"url": "http://hl7.org.nz/fhir/StructureDefinition/nzf-medication-sponsor",
"resourceReference": [
{
"reference": "Organization/48441981000116107",
"display": "48441981000116107"
}
]
}
]
}