Request Headers

Purpose of Use

The Category header may be used to indicate the ‘reason for access’ when making API requests to the Spine, where this information may be required for Privacy Audit purposes. The Spine extends the FHIR Security Labels standard to allow clients to indicate the purpose of the request, and potentially also a free-text reason to add further detail.

Clients accessing the BadgerNet Spine in New Zealand must include a valid Category header with every request to the API, in other regions this header is optional.

Example

In the following example, the client sends a Category header including the code: ETREAT indicating that the request is due to an emergency scenario, and includes a free-text reason.

Category:

http://terminology.hl7.org/CodeSystem/v3-ActReason#ETREAT; scheme=http://hl7.org/fhir/tag/security; reason="Patient is unconscious, emergency access"

There are four main sections to the header value:

Category URI - A fixed value of: http://terminology.hl7.org/CodeSystem/v3-ActReason
Purpose of Use Code - A valid Purpose of Use Code, as a URI fragment suffix to the Category URI
Scheme - A fixed value of: http://hl7.org/fhir/tag/security
Reason - An optional free-text reason for access. For certain Purpose of Use Codes, this is required

Purpose of Use Code

The Purpose of Use code must be one of a fixed set of values, see Appendix A below for a complete list of supported codes.

Reason

In addition to the Purpose of Use Code, the reason field may be used to include some free-text information about the purpose of the request. While this may be included with any Purpose of Use Code, for certain codes this field is mandatory, specifically:

ETREAT - Emergency Treatment
BTG - Break the Glass
ERTREAT - Emergency Room Treatment

A maximum of 500 characters may be included in the reason field, and when the field is mandatory, it must be at least 5 characters long.

Associated Person

The From header may be used to indicate a user and/or organisation associated with the request for auditing purposes.

Clients accessing the BadgerNet Spine in New Zealand must include a valid From header containing both user and organisation fields with every request to the API, in other regions this header is optional.

Example

In the following example, the client associates the request with specific user and organisation identifiers.

From:

user="24601";organisation="E12345"

The user and organisation fields may each be a maximum of 75 characters long, and may contain any identifiers appropriate to the Spine Client System. For example, a professional registration number or internal system ID.

Request ID

Spine Client Systems may optionally send a client-generated unique ID in the X-Request-Id header when calling the Spine API. Similarly, the Spine will always include a server-generated X-Request-Id header in responses. To allow clients to correlate sent messages with their responses, the Spine will echo any inbound X-Request-Id headers back to the client in the response using the key: X-Correlation-Id. This is in conformance with the FHIR Specification on Custom Headers.

Appendix A: Purpose of Use Codes

Code	Description	Requires Reason
`BIORCH`	Biomedical Research
`BTG`	Break the Glass	✅
`CAREMGT`	Care Management
`CLINTRCH`	Clinical Trial Research
`CLINTRCHNPC`	Clinical Trial Research Without Patient Care
`CLINTRCHPC`	Clinical Trial Research With Patient Care
`CLINTRL`	Clinical Trial
`CLMATTCH`	Claim Attachment
`COC`	Coordination of Care
`COVAUTH`	Coverage Authorization
`DISASTER`	Disaster
`DSRCH`	Disease Specific Healthcare Research
`ELIGDTRM`	Eligibility Determination
`ELIGVER`	Eligibility Verification
`ENROLLM`	Enrollment
`ERTREAT`	Emergency Room Treatment	✅
`ETREAT`	Emergency Treatment	✅
`FAMRQT`	Family Requested
`FRAUD`	Fraud
`HACCRED`	Health Accreditation
`HCOMPL`	Health Compliance
`HDECD`	Decedent
`HDIRECT`	Directory
`HDM`	Healthcare Delivery Management
`HLEGAL`	Legal
`HOPERAT`	Healthcare Operations
`HOUTCOMS`	Health Outcome Measure
`HPAYMT`	Healthcare Payment
`HPRGRP`	Health Program Reporting
`HQUALIMP`	Health Quality Improvement
`HRESCH`	Healthcare Research
`HSYSADMIN`	Health System Administration
`HTEST`	Test Health Data
`LABELING`	Labeling
`METAMGT`	Metadata Management
`PATADMIN`	Patient Administration
`PATRQT`	Patient Requested
`PATSFTY`	Patient Safety
`PERFMSR`	Performance Measure
`POARCH`	Population Origins or Ancestry Healthcare Research
`POPHLTH`	Population Health
`PRECLINTRCH`	Preclinical Trial Research
`PUBHLTH`	Public Health
`PWATRNY`	Power of Attorney
`RECORDMGT`	Records Management
`REMITADV`	Remittance Advice
`SUPNWK`	Support Network
`THREAT`	Threat
`TRAIN`	Training
`TRANSRCH`	Translational Healthcare Research
`TREAT`	Treatment

This documentation space has been classified as:
COMMERCIAL IN CONFIDENCE

Confidentiality/document control

This document contains information that is confidential to System C Healthcare Ltd (System C) and is intended for our customers to use in connection with our products and services and it must not be used for any other purpose nor disclosed to any other party, either whole or in part, without the prior written consent of System C except as follows. A customer may permit those of its employees, advisors and agents having a need to know the contents of this platform, to have access to such of the contents as are strictly necessary, but that customer shall ensure that such employees, advisors and agents are bound to it by an obligation, in similar term, to keep it confidential. A customer's acceptance of these obligations shall be indicated by that customer's use of any of the information contained in this document.

System C acknowledges that a customer may be bound by the Freedom of Information Act 2000 (FOIA). In such a case System C considers that the contents of this document are confidential and exempt from disclosure pursuant to section 41 of the FOIA. A customer should consult System C before making any disclosure of information relating to System C under the FOIA. System C's business information, methodologies, solutions, as well as reference to System C clients and their projects are always considered by System C to be exempt from disclosure by virtue of section 41 and 43 of the FOIA, whether indicated or not.

Warning: Paper or PDF copies of this document are not version controlled and will automatically be considered obsolete and superseded at the time of printing or conversion.