DocumentReference
Overview
The DocumentReference resource is used to reference a clinical document for a patient within the health system. This resource supports reading Continuity of Care Documents (CCD), returning a list of clinical documents, and a reference to retrieve a document as a PDF. Additionally, this resource supports writing an unstructured document. References to implicitRules, relatesTo, and modifierExtensions are NOT supported and will fail a create request.
For fields supported on write, see the create section.
The following fields are returned if valued for the docref operation (CCD read):
- DocumentReference id
- Subject (patient)
- Document type
- Index date/time (when document reference created)
- Status (current)
- Format
- ContentType and URL (fully qualified link to the Binary CCD)
The following fields are returned if valued for clinical documents:
- DocumentReference id
- Subject (patient)
- Document type
- Document description/title
- Authenticator/verifying provider
- Create date/time
- Indexed date/time
- Status (typically current)
- Document status (typically final or amended)
- Content
- Patient encounter
Terminology Bindings
DocumentReference.type |
|
Search
Search for DocumentReferences that meet supplied query parameters:
GET /DocumentReference?:parameters
Implementation Notes
- Search results are currently limited to published clinical documents.
- Contents of the document are found by following the Attachment URL. See more information on the Binary resource to determine what Authorization scopes are required, and how to set the Accept header when downloading document contents.
Authorization Types
Parameters
Name | Required? | Type | Description |
---|---|---|---|
_id |
This, or one of patient or subject
|
token |
The logical resource id associated with the resource. Example: _id=7891
|
patient |
This, or one of _id or subject
|
reference |
The patient to which the document reference belongs. Example: patient=12345
|
subject |
This, or one of _id or patient
|
reference |
The subject of the document reference. Must represent a Patient resource. May use the :Patient modifier. Example: subject=Patient/12345 or subject:Patient=12345
|
encounter |
No | reference |
The encounter to which the document reference belongs. Must represent an Encounter resource. May include a single or comma separated list of references. Example: encounter=4567
|
created |
No | date |
A date/time the referenced document was created. Must use the ge and le prefixes. Example: created=ge2017-01-07&created=le2017-02-05
|
_count |
No | number |
The maximum number of results to return. |
Notes:
- The
_id
parameter may not be provided at the same time as thepatient
,subject
,encounter
,created
, or_count
parameters. - When the
created
parameter is provided:- It must be provided twice, once with the
ge
parameter and once with thele
parameter. - The two provided date/times may not be equal and must form a closed range.
- If one
created
parameter includes a time, both must include a time.
- It must be provided twice, once with the
Headers
Accept: application/json+fhir
Authorization: <OAuth2 Bearer Token>
Example
Request
GET https://fhir-open.cerner.com/dstu2/ec2458f2-1e24-41c8-b71b-0e701af7583d/DocumentReference?patient=12724066&created=ge2020-01-01&created=le2020-12-31
Response
Status: 200 OK
{
"resourceType": "Bundle",
"id": "0be75cc8-da20-460a-a39e-9825bdb87472",
"type": "searchset",
"total": 1,
"link": [
{
"relation": "self",
"url": "https://fhir-open.cerner.com/dstu2/ec2458f2-1e24-41c8-b71b-0e701af7583d/DocumentReference?patient=12724066&created=ge2020-01-01&created=le2020-12-31"
}
],
"entry": [
{
"fullUrl": "https://fhir-open.cerner.com/dstu2/ec2458f2-1e24-41c8-b71b-0e701af7583d/DocumentReference/197286315",
"resource": {
"resourceType": "DocumentReference",
"id": "197286315",
"meta": {
"versionId": "197286314",
"lastUpdated": "2020-04-05T04:00:46.000Z"
},
"text": {
"status": "generated",
"div": "<div><p><b>Document Reference</b></p><p><b>Patient Name</b>: SMART, NANCY</p><p><b>Document Type</b>: Pregnancy Summary Document</p><p><b>Document Title</b>: Pregnancy Summary Document</p><p><b>Date</b>: Apr 5, 2020 4:00 A.M. UTC</p><p><b>Document Status</b>: Auth (Verified)</p></div>"
},
"subject": {
"reference": "Patient/12724066",
"display": "SMART, NANCY"
},
"type": {
"coding": [
{
"system": "https://fhir.cerner.com/ec2458f2-1e24-41c8-b71b-0e701af7583d/codeSet/72",
"code": "22520442",
"display": "Pregnancy Summary Document",
"userSelected": true
},
{
"system": "http://terminology.hl7.org/CodeSystem/v3-NullFlavor",
"code": "UNK",
"display": "unknown"
}
],
"text": "Pregnancy Summary Document"
},
"created": "2020-04-05T04:00:45.000Z",
"indexed": "2020-04-05T04:00:45.000Z",
"status": "current",
"docStatus": {
"coding": [
{
"system": "http://hl7.org/fhir/composition-status",
"code": "final",
"display": "Final"
}
],
"text": "Auth (Verified)"
},
"description": "Pregnancy Summary Document",
"content": [
{
"attachment": {
"contentType": "application/pdf",
"url": "https://fhir-open.cerner.com/dstu2/ec2458f2-1e24-41c8-b71b-0e701af7583d/Binary/XR-197286315",
"title": "Pregnancy Summary Document"
}
}
]
}
}
]
}
Note: The examples provided here are non-normative and replaying them in the public sandbox is not guaranteed to yield the results shown on the site.
Errors
The common errors and OperationOutcomes may be returned.
Retrieve by id
List an individual DocumentReference by its id:
GET /DocumentReference/:id
Implementation Notes
- Contents of the document are found by following the Attachment URL. See more information on the Binary resource to determine what Authorization scopes are required, and how to set the Accept header when downloading document contents.
- If no mappings are available for LOINC codes when returning DocumentReference.type codings, an unknown data absent reason will be returned in place of the LOINC codes. This is to follow the Argonaut profile’s required binding for type. When available, Proprietary codings will be returned in addition to the data absent reason.
Authorization Types
Headers
Accept: application/json+fhir
Authorization: <OAuth2 Bearer Token>
Example
Request
GET https://fhir-open.cerner.com/dstu2/ec2458f2-1e24-41c8-b71b-0e701af7583d/DocumentReference/197286315
Response
Status: 200 OK
{
"resourceType": "DocumentReference",
"id": "197286315",
"meta": {
"versionId": "197286314",
"lastUpdated": "2020-04-05T04:00:46.000Z"
},
"text": {
"status": "generated",
"div": "<div><p><b>Document Reference</b></p><p><b>Patient Name</b>: SMART, NANCY</p><p><b>Document Type</b>: Pregnancy Summary Document</p><p><b>Document Title</b>: Pregnancy Summary Document</p><p><b>Date</b>: Apr 5, 2020 4:00 A.M. UTC</p><p><b>Document Status</b>: Auth (Verified)</p></div>"
},
"subject": {
"reference": "Patient/12724066",
"display": "SMART, NANCY"
},
"type": {
"coding": [
{
"system": "https://fhir.cerner.com/ec2458f2-1e24-41c8-b71b-0e701af7583d/codeSet/72",
"code": "22520442",
"display": "Pregnancy Summary Document",
"userSelected": true
},
{
"system": "http://terminology.hl7.org/CodeSystem/v3-NullFlavor",
"code": "UNK",
"display": "unknown"
}
],
"text": "Pregnancy Summary Document"
},
"created": "2020-04-05T04:00:45.000Z",
"indexed": "2020-04-05T04:00:45.000Z",
"status": "current",
"docStatus": {
"coding": [
{
"system": "http://hl7.org/fhir/composition-status",
"code": "final",
"display": "Final"
}
],
"text": "Auth (Verified)"
},
"description": "Pregnancy Summary Document",
"content": [
{
"attachment": {
"contentType": "application/pdf",
"url": "https://fhir-open.cerner.com/dstu2/ec2458f2-1e24-41c8-b71b-0e701af7583d/Binary/XR-197286315",
"title": "Pregnancy Summary Document"
}
}
]
}
Note: The examples provided here are non-normative and replaying them in the public sandbox is not guaranteed to yield the results shown on the site.
Errors
The common errors and OperationOutcomes may be returned.
Create
Create new documents. Currently limited to unstructured clinical notes or documentation. For example, a document with display formatting or styling can be written, but a CCD cannot.
POST /DocumentReference
Implementation Notes
- The modifier elements implicitRules, modifierExtension and relatesTo are not supported and will be rejected if present.
- Currently only XHTML formatted documents are supported. You can validate your document using any available strict XHTML 1.0 validator (eg: w3 validator or this html5 validator).
Authorization Types
Headers
Authorization: <OAuth2 Bearer Token>
Accept: application/json+fhir
Content-Type: application/json+fhir
Body fields
Name | Required | Type | |
---|---|---|---|
resourceType
|
Yes |
string |
|
|
|||
subject
|
Yes |
Reference (Patient ) |
|
|
|||
type
|
Yes |
CodeableConcept |
|
|
|||
author
|
No |
List of Reference (Practitioner ) |
|
|
|||
indexed
|
Yes |
instant |
|
|
|||
status
|
Yes |
code |
|
|
|||
docStatus
|
No |
CodeableConcept |
|
|
|||
description
|
No |
string |
|
|
|||
content
|
Yes |
List of BackboneElement |
|
|
|||
content.attachment
|
Yes |
Attachment |
|
|
|||
content.attachment.contentType
|
Yes |
string |
|
|
|||
content.attachment.data
|
Yes |
string |
|
|
|||
context
|
Yes |
BackboneElement |
|
|
|||
context.encounter
|
Yes |
Reference (Encounter ) |
|
|
|||
context.period
|
No |
Period |
|
|
Example
Request
POST https://fhir-ehr-code.cerner.com/dstu2/ec2458f2-1e24-41c8-b71b-0e701af7583d/DocumentReference
Body
{
"resourceType": "DocumentReference",
"subject": {
"reference": "Patient/53663272"
},
"type": {
"coding": [
{
"system": "http://loinc.org",
"code": "34840-9"
}
]
},
"author": [
{
"reference": "Practitioner/21500981"
}
],
"indexed": "2015-11-18T18:00:00Z",
"status": "current",
"docStatus": {
"coding": [
{
"system": "http://hl7.org/fhir/composition-status",
"code": "final"
}
]
},
"description": "Rheumatology Note",
"content": [
{
"attachment": {
"contentType": "application/xhtml+xml;charset=utf-8",
"data": "<snipped for brevity>"
}
}
],
"context": {
"encounter": {
"reference": "Encounter/4208059"
},
"period": {
"end": "2015-08-20T09:10:14Z"
}
}
}
Response
Status: 201 Created
Connection: Keep-Alive Content-Encoding: gzip Content-Length: 20 Content-Type: text/html; charset=UTF-8 Date: Wed, 06 Jan 2016 18:09:18 GMT Keep-Alive: timeout=15, max=100 access-control-allow-methods: DELETE, GET, POST, PUT, OPTIONS, HEAD access-control-allow-origin: * access-control-expose-headers: ETag, Content-Location, Location, X-Request-Id, WWW-Authenticate, Date access-control-max-age: 0 cache-control: no-cache location: https://fhir-ehr-code.cerner.com/dstu2/ec2458f2-1e24-41c8-b71b-0e701af7583d/DocumentReference/5789254 strict-transport-security: max-age=631152000 vary: Origin,User-Agent,Accept-Encoding x-content-type-options: nosniff x-frame-options: SAMEORIGIN x-request-id: 9c7510c0-0bb5-4148-b37e-51a774c4091b x-xss-protection: 1; mode=block
Note: The examples provided here are non-normative and replaying them in the public sandbox is not guaranteed to yield the results shown on the site.
Errors
The common errors and OperationOutcomes may be returned. Additional OperationOutcomes may be returned in the following scenarios:
HTTP Status | Cause | Severity | Code |
---|---|---|---|
422 | Body contained relatesTo | error | not-supported |
Operation: docref
Argonaut operation for querying DocumentReferences for the supplied parameters:
GET /DocumentReference/$docref?:parameters
Implementation Notes
- The DocumentReference.relatesTo modifier element is not supported and will not be returned.
Authorization Types
Terminology Bindings
DocumentReference.type |
|
DocumentReference.content.format |
|
Parameters
Name | Required? | Type | Description |
---|---|---|---|
patient |
Y | reference |
A reference to the patient whose document references are required. Example: 12345
|
type |
Y | token |
The document reference type, can be a list of comma separated values. Example: http://loinc.org|34133-9
|
start |
N | date |
The start of the date range from which document reference records should be included. If not provided, then all records from the beginning of time are included. Example: 2014-09-24T12:00:00.000Z
|
end |
N | date |
The end of the date range till which document reference records should be included. If not provided, then all records up to the current date are included. Example: 2016-09-24T12:00:00.000Z
|
Notes:
- The
type
parameter must include both a system and a code. (e.g.&type=http://loinc.org|34133-9
) - The
start
andend
parameters must be valid dateTimes with a time component. They must have prefixes ofeq
or nothing.
Headers
Accept: application/json+fhir
Authorization: <OAuth2 Bearer Token>
Example
Request
GET https://fhir-open.cerner.com/dstu2/ec2458f2-1e24-41c8-b71b-0e701af7583d/DocumentReference/$docref?patient=12724066&type=http%3A%2F%2Floinc.org%7C34133-9
Response
Status: 200 OK
{
"resourceType": "Bundle",
"id": "33c6587c-ab3c-4846-a2c6-05724fe4013e",
"type": "searchset",
"total": 1,
"link": [
{
"relation": "self",
"url": "https://fhir-open.cerner.com/dstu2/ec2458f2-1e24-41c8-b71b-0e701af7583d/DocumentReference/$docref?patient=12724066&type=http%3A%2F%2Floinc.org%7C34133-9"
}
],
"entry": [
{
"fullUrl": "https://fhir-open.cerner.com/dstu2/ec2458f2-1e24-41c8-b71b-0e701af7583d/DocumentReference/c7d249c7-1742-47a8-9fca-1fc361728aa8",
"resource": {
"resourceType": "DocumentReference",
"id": "c7d249c7-1742-47a8-9fca-1fc361728aa8",
"subject": {
"reference": "Patient/12724066"
},
"type": {
"coding": [
{
"system": "http://loinc.org",
"code": "34133-9"
}
],
"text": "Summary of episode note"
},
"indexed": "2020-07-08T17:05:01Z",
"status": "current",
"content": [
{
"attachment": {
"contentType": "application/xml",
"url": "https://fhir-open.cerner.com/dstu2/ec2458f2-1e24-41c8-b71b-0e701af7583d/Binary/$autogen-ccd-if?patient=12724066"
},
"format": [
{
"system": "urn:oid:1.3.6.1.4.1.19376.1.2.3",
"code": "urn:hl7-org:sdwg:ccda-structuredBody:2.1",
"display": "For documents following C-CDA constraints using a structured body."
}
]
}
]
}
}
]
}
Note: The examples provided here are non-normative and replaying them in the public sandbox is not guaranteed to yield the results shown on the site.
Errors
The common errors and OperationOutcomes may be returned.