Clinical Notes
Overview
FHIR Clinical Notes addresses to the DocumentReference HL7® FHIR® resource. A DocumentReference resource is used to index a document, clinical note, and other binary objects to make them available to a healthcare system. A document is some sequence of bytes that is identifiable, establishes its own context (e.g., what subject, author, etc. can be displayed to the user), and has defined update management.
Example Usage Scenarios:
The following are example usage scenarios for the US Core DocumentReference profile. See the Clinical Notes section for additional detail on using this profile for Clinical Notes:
- Query for all documents belonging to a Patient
- Query for a specific Clinical Note type (e.g. Discharge Summary or Continuity of Care Document (CCD))
- Query for all Clinical Notes belonging to a Patient
- Write a new Note to a Patient’s Chart
Each DocumentReference has next elements:
- a status
- a code describing the type of document
- a document category
- a patient
- an address (e.g. url) where the document can be retrieved or the content as inline base64 encoded data
- the MIME type (i.e. contentType) of the document
Each DocumentReference must support:
- a business identifier for the DocumentReference (possibly generated by the transcription system or EHR)
- date and time the reference was created
- an author
- the organization responsible for the document, referred to as custodian
- a code identifying the specific details about the format of the document — over and above the content’s MIME type
- the patient encounter that is being referenced
- clinically relevant date
Profile specific implementation guidance:
- See Clinical Notes
- The DocumentReference.type binding must support at a minimum the 5 Common Clinical Notes and may extend to the full US Core DocumentReference Type Value Set
- For a C-CDA Clinical Summary of Care (CCD):
- The document type code is the LOINC code 34133-9 Summary of episode note.
- The format code is
urn:hl7-org:sdwg:ccda-structuredBody:2.1
- The content.url may refer to a FHIR Binary Resource (i.e. [base]/Binary/[id]), FHIR Document Bundle (i.e [base]/Bundle/[id] or other endpoint.
This resource conforms to USCDI V1 profile for DocumentReference - refers to StructureDefinition US Core DocumentReference.
DocumentReference response will be provided in JSON (refers to Capability Statement) format as per FHIR standard R4 version.
Must support elements, mandatory and optional search parameters
DocumentReference must support these elements:
identifierstatustypecategorysubjectdateauthorcustodiancontentattachmentcontentTypedataurl
formatcontextencounterperiod
The syntax used to describe the interactions is described here.
The following search parameters and search parameter combinations SHALL be supported (mandatory):
SHALL support fetching a DocumentReference using the _id search parameter:
SHALL support searching for all DocumentReference for a patient using the patient search parameter:
SHALL support searching using the combination of the patient and category search parameters:
GET [base url]/DocumentReference?patient={Type/}[id]&category=http://hl7.org/fhir/us/core/CodeSystem/us-core-documentreference-category|clinical-note
SHALL support searching using the combination of the patient and category and date search parameters:
- including support for these date comparators:
gt,lt,ge,le - including optional support for AND search on date (e.g.
date=[date]&date=[date]]&...)
GET [base url]/DocumentReference?patient={Type/}[id]&category=http://hl7.org/fhir/us/core/CodeSystem/us-core-documentreference-category|clinical-note&date={gt|lt|ge|le}[date]{&date={gt|lt|ge|le}[date]&...}
SHALL support searching using the combination of the patient and type search parameters:
The following search parameters and search parameter combinations SHOULD be supported (optional):
SHOULD support searching using the combination of the patient and status search parameters:
- including support for OR search on
status(e.g.status={system|}[code],{system|}[code],...)
SHOULD support searching using the combination of the patient and type and period search parameters:
- including support for these period comparators:
gt,lt,ge,le - including optional support for AND search on
period(e.g.period=[date]&period=[date]]&...)
GET [base url]/DocumentReference?patient={Type/}[id]&type={system|}[code]&period={gt|lt|ge|le}[date]{&period={gt|lt|ge|le}[date]&...}
DocumentReference By Id
Search for DocumentReference by id.
METHOD GET
or
PARAMS
- [base url] - FHIR base url
- [id] - Id for the DocumentReference
HEADERS
The Authorization token SHALL be obtained during Authentication and Authorization process. Goto Authentication and Authorization for further details.
| Header | Type | Required/Optional | Value |
|---|---|---|---|
| Authorization | string | required | 'Bearer' |
RESPONSES
| Code | Description | Comment |
|---|---|---|
| 200 | OK | The request was processed successfully |
| 400 | Bad request | Invalid request parameters or FHIR operation outcome resource returned |
| 401 | Unauthorized | This code indicates that the client request has not been completed because it lacks valid authentication credentials for the requested resource |
| 404 | no Route matched with those values | The request was able to communicate with a given server, but the server could not find what was requested |
| 500 | Internal Server Error | The server has encountered a situation it doesn't know how to handle |
EXAMPLE:
curl --location --request GET 'https://demo.kodjin.com/fhir/DocumentReference/a11b21f6-1ac7-ca23-1ba2-a021f6532a5d' \
--header 'Authorization: Bearer fe1cd986-1ac7-4c26-b8b3-d632a48408fd'
DocumentReference By patient
Search for All DocumentReference by a specific patient.
METHOD GET
PARAMS
- [base url] - FHIR base url
- {Type/} - Type for the Reference. Example:
Patient/ - [id] - Id for Patient resource
HEADERS
The Authorization token SHALL be obtained during Authentication and Authorization process. Goto Authentication and Authorization for further details.
| Header | Type | Required/Optional | Value |
|---|---|---|---|
| Authorization | string | required | 'Bearer' |
RESPONSES
| Code | Description | Comment |
|---|---|---|
| 200 | OK | The request was processed successfully |
| 400 | Bad request | Invalid request parameters or FHIR operation outcome resource returned |
| 401 | Unauthorized | This code indicates that the client request has not been completed because it lacks valid authentication credentials for the requested resource |
| 404 | no Route matched with those values | The request was able to communicate with a given server, but the server could not find what was requested |
| 500 | Internal Server Error | The server has encountered a situation it doesn't know how to handle |
EXAMPLE:
curl --location --request GET 'https://demo.kodjin.com/fhir/DocumentReference?patient=Patient/1137192' \
--header 'Authorization: Bearer fe1cd986-1ac7-4c26-b8b3-d632a48408fd'
DocumentReference By patient and category
Fetches a bundle of all DocumentReference resources for the specified patient and category = clinical-note
METHOD GET
GET [base url]/DocumentReference?patient={Type/}[id]&category=http://hl7.org/fhir/us/core/CodeSystem/us-core-documentreference-category|clinical-note
PARAMS
- [base url] - FHIR base url
- {Type/} - Type for the Reference. Example:
Patient/ - [id] - Id for Patient resource
HEADERS
The Authorization token SHALL be obtained during Authentication and Authorization process. Goto Authentication and Authorization for further details.
| Header | Type | Required/Optional | Value |
|---|---|---|---|
| Authorization | string | required | 'Bearer' |
RESPONSES
| Code | Description | Comment |
|---|---|---|
| 200 | OK | The request was processed successfully |
| 400 | Bad request | Invalid request parameters or FHIR operation outcome resource returned |
| 401 | Unauthorized | This code indicates that the client request has not been completed because it lacks valid authentication credentials for the requested resource |
| 404 | no Route matched with those values | The request was able to communicate with a given server, but the server could not find what was requested |
| 500 | Internal Server Error | The server has encountered a situation it doesn't know how to handle |
EXAMPLE:
curl --location --request GET 'https://demo.kodjin.com/fhir/DocumentReference?patient=Patient/1137192&category=http://hl7.org/fhir/us/core/CodeSystem/us-core-documentreference-category|clinical-note' \
--header 'Authorization: Bearer fe1cd986-1ac7-4c26-b8b3-d632a48408fd'
DocumentReference By patient and category and date
Fetches a bundle of all DocumentReference resources for the specified patient and category = clinical=note and date
METHOD GET
GET [base url]/DocumentReference?patient={Type/}[id]&category=http://hl7.org/fhir/us/core/CodeSystem/us-core-documentreference-category|clinical-note&date={gt|lt|ge|le}[date]{&date={gt|lt|ge|le}[date]&...}
PARAMS
- [base url] - FHIR base url
- {Type/} - Type for the Reference. Example:
Patient/ - [id] - Id for Patient resource
- {gt|lt|ge|le} - Search modifiers for the date. See Search specification for more information.
- [date] - Beginning and/or ending for a period
HEADERS
The Authorization token SHALL be obtained during Authentication and Authorization process. Goto Authentication and Authorization for further details.
| Header | Type | Required/Optional | Value |
|---|---|---|---|
| Authorization | string | required | 'Bearer' |
RESPONSES
| Code | Description | Comment |
|---|---|---|
| 200 | OK | The request was processed successfully |
| 400 | Bad request | Invalid request parameters or FHIR operation outcome resource returned |
| 401 | Unauthorized | This code indicates that the client request has not been completed because it lacks valid authentication credentials for the requested resource |
| 404 | no Route matched with those values | The request was able to communicate with a given server, but the server could not find what was requested |
| 500 | Internal Server Error | The server has encountered a situation it doesn't know how to handle |
EXAMPLE:
curl --location --request GET 'https://demo.kodjin.com/fhir/DocumentReference?patient=Patient/1235541&category=http://hl7.org/fhir/us/core/CodeSystem/us-core-documentreference-category|clinical-note&date=ge2020-01-01T00:00:00Z' \
--header 'Authorization: Bearer fe1cd986-1ac7-4c26-b8b3-d632a48408fd'
DocumentReference By patient and type
Fetches a bundle of all DocumentReference resources for the specified patient and type
METHOD GET
PARAMS
- [base url] - FHIR base url
- {Type/} - Type for the Reference. Example:
Patient/ - [id] - Id for Patient resource
- {system|} - Type system. FHIR search token parameter. See Search specification for more information.
- [code] - Type code. FHIR search token parameter. See Search specification for more information.
HEADERS
The Authorization token SHALL be obtained during Authentication and Authorization process. Goto Authentication and Authorization for further details.
| Header | Type | Required/Optional | Value |
|---|---|---|---|
| Authorization | string | required | 'Bearer' |
RESPONSES
| Code | Description | Comment |
|---|---|---|
| 200 | OK | The request was processed successfully |
| 400 | Bad request | Invalid request parameters or FHIR operation outcome resource returned |
| 401 | Unauthorized | This code indicates that the client request has not been completed because it lacks valid authentication credentials for the requested resource |
| 404 | no Route matched with those values | The request was able to communicate with a given server, but the server could not find what was requested |
| 500 | Internal Server Error | The server has encountered a situation it doesn't know how to handle |
EXAMPLE:
curl --location --request GET 'https://demo.kodjin.com/fhir/DocumentReference?patient=Patient/1316024&type=http://loinc.org|18842-5' \
--header 'Authorization: Bearer fe1cd986-1ac7-4c26-b8b3-d632a48408fd'
DocumentReference By patient and status
Fetches a bundle of all DocumentReference resources for the specified patient and status
METHOD GET
PARAMS
- [base url] - FHIR base url
- {Type/} - Type for the Reference. Example:
Patient/ - [id] - Id for Patient resource
- {system|} - Status system. FHIR search token parameter. See Search specification for more information.
- [code] - Status code. FHIR search token parameter. See Search specification for more information.
HEADERS
The Authorization token SHALL be obtained during Authentication and Authorization process. Goto Authentication and Authorization for further details.
| Header | Type | Required/Optional | Value |
|---|---|---|---|
| Authorization | string | required | 'Bearer' |
RESPONSES
| Code | Description | Comment |
|---|---|---|
| 200 | OK | The request was processed successfully |
| 400 | Bad request | Invalid request parameters or FHIR operation outcome resource returned |
| 401 | Unauthorized | This code indicates that the client request has not been completed because it lacks valid authentication credentials for the requested resource |
| 404 | no Route matched with those values | The request was able to communicate with a given server, but the server could not find what was requested |
| 500 | Internal Server Error | The server has encountered a situation it doesn't know how to handle |
EXAMPLE:
curl --location --request GET 'https://demo.kodjin.com/fhir/DocumentReference?patient=Patient/1316024&status=superseded' \
--header 'Authorization: Bearer fe1cd986-1ac7-4c26-b8b3-d632a48408fd'
DocumentReference By patient and type and period
Fetches a bundle of all DocumentReference resources for the specified patient and type and period.
METHOD GET
GET [base]/DocumentReference?patient={Type/}[id]&type={system|}[code]&period={gt|lt|ge|le}[date]{&period={gt|lt|ge|le}[date]&...}
PARAMS
- [base url] - FHIR base url
- {Type/} - Type for the Reference. Example:
Patient/ - [id] - Id for Patient resource
- {system|} - Type system. FHIR search token parameter. See Search specification for more information.
- [code] - Type code. FHIR search token parameter. See Search specification for more information.
- {gt|lt|ge|le} - Search modifiers for the date. See Search specification for more information.
- [date] - Beginning and/or ending for a period
HEADERS
The Authorization token SHALL be obtained during Authentication and Authorization process. Goto Authentication and Authorization for further details.
| Header | Type | Required/Optional | Value |
|---|---|---|---|
| Authorization | string | required | 'Bearer' |
RESPONSES
| Code | Description | Comment |
|---|---|---|
| 200 | OK | The request was processed successfully |
| 400 | Bad request | Invalid request parameters or FHIR operation outcome resource returned |
| 401 | Unauthorized | This code indicates that the client request has not been completed because it lacks valid authentication credentials for the requested resource |
| 404 | no Route matched with those values | The request was able to communicate with a given server, but the server could not find what was requested |
| 500 | Internal Server Error | The server has encountered a situation it doesn't know how to handle |
EXAMPLE: