DocumentReference

Overview

The DocumentReference resource provides "a reference to a document of any kind for any purpose". It also "provides metadata about the document so that the document can be discovered and managed." This resource enables healthcare systems to reference clinical documents, reports, and other healthcare-related documents while maintaining metadata for discovery and management.

Resource Schema

Key fields in the DocumentReference resource:

{
  "resourceType": "DocumentReference",
  "id": "example-doc-ref",
  "status": "current",
  "type": {
    "coding": [{
      "system": "http://loinc.org",
      "code": "18748-4",
      "display": "Diagnostic imaging study"
    }]
  },
  "category": [{
    "coding": [{
      "system": "http://hl7.org/fhir/us/core/CodeSystem/us-core-documentreference-category",
      "code": "clinical-note"
    }]
  }],
  "subject": {
    "reference": "Patient/123"
  },
  "date": "2023-01-15T10:30:00Z",
  "content": [{
    "attachment": {
      "contentType": "application/pdf",
      "url": "https://example.com/document.pdf"
    }
  }]
}

Operations

The DocumentReference resource supports the following operations:

CareRecord / Solution	Create	Read	Update	Search
GEHRIMED	Yes	Yes	Yes	Yes
myAvatar	Yes	Yes	Yes	Yes
myEvolv	Yes	Yes	Yes	Yes
myUnity	Yes	Yes	Yes	Yes
TheraOffice	Yes	Yes	Yes	Yes

Create

Create a new DocumentReference resource.

Production
Preview

POST /DocumentReference
Content-Type: application/fhir+json

{
  "resourceType": "DocumentReference",
  "status": "current",
  "type": {
    "coding": [{
      "system": "http://loinc.org",
      "code": "18748-4",
      "display": "Diagnostic imaging study"
    }]
  },
  "subject": {
    "reference": "Patient/123"
  },
  "date": "2023-01-15T10:30:00Z",
  "content": [{
    "attachment": {
      "contentType": "application/pdf",
      "url": "https://example.com/document.pdf"
    }
  }]
}

POST /DocumentReference
Content-Type: application/fhir+json

{
  "resourceType": "DocumentReference",
  "status": "current",
  "type": {
    "coding": [{
      "system": "http://loinc.org",
      "code": "18748-4",
      "display": "Diagnostic imaging study"
    }]
  },
  "subject": {
    "reference": "Patient/123"
  },
  "date": "2023-01-15T10:30:00Z",
  "content": [{
    "attachment": {
      "contentType": "application/pdf",
      "url": "https://example.com/document.pdf"
    }
  }]
}

Read

Retrieve a specific DocumentReference by its ID.

Production
Preview

GET /DocumentReference/{id}

GET /DocumentReference/{id}

Update

Update an existing DocumentReference resource.

Production
Preview

PUT /DocumentReference/{id}
Content-Type: application/fhir+json

{
  "resourceType": "DocumentReference",
  "id": "{id}",
  "status": "current",
  "type": {
    "coding": [{
      "system": "http://loinc.org",
      "code": "18748-4",
      "display": "Diagnostic imaging study"
    }]
  },
  "subject": {
    "reference": "Patient/123"
  },
  "date": "2023-01-15T10:30:00Z",
  "content": [{
    "attachment": {
      "contentType": "application/pdf",
      "url": "https://example.com/document.pdf"
    }
  }]
}

PUT /DocumentReference/{id}
Content-Type: application/fhir+json

{
  "resourceType": "DocumentReference",
  "id": "{id}",
  "status": "current",
  "type": {
    "coding": [{
      "system": "http://loinc.org",
      "code": "18748-4",
      "display": "Diagnostic imaging study"
    }]
  },
  "subject": {
    "reference": "Patient/123"
  },
  "date": "2023-01-15T10:30:00Z",
  "content": [{
    "attachment": {
      "contentType": "application/pdf",
      "url": "https://example.com/document.pdf"
    }
  }]
}

Search

Search for document references using various criteria.

GET Method

Use GET for simple searches with parameters in the query string.

Production
Preview

GET /DocumentReference?parameter=value

GET /DocumentReference?parameter=value

POST Method

Use POST for complex searches with form-encoded parameters.

Production
Preview

POST /DocumentReference/_search

POST /DocumentReference/_search

Search Parameters

Patient-based Search:

Parameter	Type	Required	Description	Example
`patient`	reference	Yes	Who/what is the subject of the document	`patient=value`
`category`	token	No	Categorization of document	`category=value`
`date`	date	No	When this document reference was created	`date=value`
`type`	token	No	Kind of document (LOINC if possible)	`type=value`
`_lastUpdated`	date	No	Only return resources which were last updated as specified by the given range	`_lastUpdated=value`

ID-based Search:

Parameter	Type	Required	Description	Example
`_id`	string	Yes	The ID of the resource	`_id=value`
`category`	token	No	Categorization of document	`category=value`
`date`	date	No	When this document reference was created	`date=value`
`type`	token	No	Kind of document (LOINC if possible)	`type=value`
`_lastUpdated`	date	No	Only return resources which were last updated as specified by the given range	`_lastUpdated=value`

GET Method

Use GET for simple requests with query parameters. The GET method does not support the type parameter.

Production
Preview

GET /DocumentReference/$docref?patient=123

GET /DocumentReference/$docref?patient=123

POST Method

Use POST with a FHIR Parameters resource for advanced requests, including the type parameter.

Production
Preview

POST /DocumentReference/$docref
Content-Type: application/fhir+json

{
  "resourceType": "Parameters",
  "parameter": [
    {
      "name": "patient",
      "valueId": "123"
    }
  ]
}

POST /DocumentReference/$docref
Content-Type: application/fhir+json

{
  "resourceType": "Parameters",
  "parameter": [
    {
      "name": "patient",
      "valueId": "123"
    }
  ]
}

Operation Parameters

Parameter	Type	Required	Description	GET Support
patient	id	Yes	The patient whose documents are being retrieved	Yes
start	dateTime	No	Start date for document search	Yes
end	dateTime	No	End date for document search	Yes
type	Coding	No	Document type code (LOINC)	No (POST only)
on-demand	boolean	No	Controls operation mode: true for on-demand document generation, false for stable document search. Defaults to true when only patient is provided, false otherwise	Yes

GET Method

Use GET for simple requests with query parameters. The GET method does not support the type parameter.

Production
Preview

GET /DocumentReference/$docref?patient=123

GET /DocumentReference/$docref?patient=123

POST Method

Use POST with a FHIR Parameters resource for advanced requests, including the type parameter.

Production
Preview

POST /DocumentReference/$docref
Content-Type: application/fhir+json

{
  "resourceType": "Parameters",
  "parameter": [
    {
      "name": "patient",
      "valueId": "123"
    }
  ]
}

POST /DocumentReference/$docref
Content-Type: application/fhir+json

{
  "resourceType": "Parameters",
  "parameter": [
    {
      "name": "patient",
      "valueId": "123"
    }
  ]
}

Operation Parameters

Parameter	Type	Required	Description	GET Support
patient	id	Yes	The patient whose documents are being retrieved	Yes
start	dateTime	No	Start date for document search	Yes
end	dateTime	No	End date for document search	Yes
type	Coding	No	Document type code (LOINC)	No (POST only)
on-demand	boolean	No	Controls operation mode: true for on-demand document generation, false for stable document search. Defaults to true when only patient is provided, false otherwise	Yes

For more details, see the US Core DocumentReference Operation Definition.

Examples

Create a DocumentReference

Production
Preview

curl -X POST https://fhir.netsmartcloud.com/provider/patient-access/v2/{tenant-id}/DocumentReference \
    -H "Authorization: {Bearer Token}" \
    -H "Accept: application/fhir+json" \
    -H "Content-Type: application/fhir+json" \
    -d '{
  "resourceType": "DocumentReference",
  "status": "current",
  "type": {
    "coding": [{
      "system": "http://loinc.org",
      "code": "34133-9",
      "display": "Summary of episode note"
    }]
  },
  "category": [{
    "coding": [{
      "system": "http://hl7.org/fhir/us/core/CodeSystem/us-core-documentreference-category",
      "code": "clinical-note"
    }]
  }],
  "subject": {
    "reference": "Patient/123"
  },
  "date": "2024-01-15T10:30:00Z",
  "content": [{
    "attachment": {
      "contentType": "application/pdf",
      "url": "https://example.com/clinical-note.pdf"
    }
  }]
}'

curl -X POST https://fhirtest.netsmartcloud.com/provider/patient-access/v2/DocumentReference \
    -H "Authorization: {Bearer Token}" \
    -H "Accept: application/fhir+json" \
    -H "Content-Type: application/fhir+json" \
    -d '{
  "resourceType": "DocumentReference",
  "status": "current",
  "type": {
    "coding": [{
      "system": "http://loinc.org",
      "code": "34133-9",
      "display": "Summary of episode note"
    }]
  },
  "category": [{
    "coding": [{
      "system": "http://hl7.org/fhir/us/core/CodeSystem/us-core-documentreference-category",
      "code": "clinical-note"
    }]
  }],
  "subject": {
    "reference": "Patient/123"
  },
  "date": "2024-01-15T10:30:00Z",
  "content": [{
    "attachment": {
      "contentType": "application/pdf",
      "url": "https://example.com/clinical-note.pdf"
    }
  }]
}'

Update a DocumentReference

Production
Preview

curl -X PUT https://fhir.netsmartcloud.com/provider/patient-access/v2/{tenant-id}/DocumentReference/doc-123 \
    -H "Authorization: {Bearer Token}" \
    -H "Accept: application/fhir+json" \
    -H "Content-Type: application/fhir+json" \
    -d '{
  "resourceType": "DocumentReference",
  "id": "doc-123",
  "status": "current",
  "type": {
    "coding": [{
      "system": "http://loinc.org",
      "code": "34133-9",
      "display": "Summary of episode note"
    }]
  },
  "subject": {
    "reference": "Patient/123"
  },
  "date": "2024-01-15T10:30:00Z",
  "content": [{
    "attachment": {
      "contentType": "application/pdf",
      "url": "https://example.com/updated-note.pdf"
    }
  }]
}'

curl -X PUT https://fhirtest.netsmartcloud.com/provider/patient-access/v2/DocumentReference/doc-123 \
    -H "Authorization: {Bearer Token}" \
    -H "Accept: application/fhir+json" \
    -H "Content-Type: application/fhir+json" \
    -d '{
  "resourceType": "DocumentReference",
  "id": "doc-123",
  "status": "current",
  "type": {
    "coding": [{
      "system": "http://loinc.org",
      "code": "34133-9",
      "display": "Summary of episode note"
    }]
  },
  "subject": {
    "reference": "Patient/123"
  },
  "date": "2024-01-15T10:30:00Z",
  "content": [{
    "attachment": {
      "contentType": "application/pdf",
      "url": "https://example.com/updated-note.pdf"
    }
  }]
}'

Search by Patient and Type

Production
Preview

curl -X POST https://fhir.netsmartcloud.com/provider/patient-access/v2/{tenant-id}/DocumentReference/_search \
    -H "Authorization: {Bearer Token}" \
    -H "Accept: application/fhir+json" \
    -H "Content-Type: application/x-form-urlencoded" \
    -d "patient=Patient/123" \
    -d "type=http://loinc.org|18748-4"

curl -X POST https://fhirtest.netsmartcloud.com/provider/patient-access/v2/DocumentReference/_search \
    -H "Authorization: {Bearer Token}" \
    -H "Accept: application/fhir+json" \
    -H "Content-Type: application/x-form-urlencoded" \
    -d "patient=Patient/123" \
    -d "type=http://loinc.org|18748-4"

Fetch Documents Using $docref Operation (GET)

Production
Preview

curl -X GET 'https://fhir.netsmartcloud.com/provider/patient-access/v2/{tenant-id}/DocumentReference/\$docref?patient=123' \
    -H "Authorization: {Bearer Token}" \
    -H "Accept: application/fhir+json"

With Date Range
curl -X GET 'https://fhir.netsmartcloud.com/provider/patient-access/v2/{tenant-id}/DocumentReference/\$docref?patient=123&start=2024-01-01&end=2024-12-31' \
    -H "Authorization: {Bearer Token}" \
    -H "Accept: application/fhir+json"

curl -X GET 'https://fhirtest.netsmartcloud.com/provider/patient-access/v2/DocumentReference/\$docref?patient=123' \
    -H "Authorization: {Bearer Token}" \
    -H "Accept: application/fhir+json"

With Date Range
curl -X GET 'https://fhirtest.netsmartcloud.com/provider/patient-access/v2/DocumentReference/\$docref?patient=123&start=2024-01-01&end=2024-12-31' \
    -H "Authorization: {Bearer Token}" \
    -H "Accept: application/fhir+json"

Fetch Documents Using $docref Operation (POST)

Production
Preview

With Document Type
curl -X POST https://fhir.netsmartcloud.com/provider/patient-access/v2/{tenant-id}/DocumentReference/\$docref \
    -H "Authorization: {Bearer Token}" \
    -H "Accept: application/fhir+json" \
    -H "Content-Type: application/fhir+json" \
    -d '{
  "resourceType": "Parameters",
  "parameter": [
    {
      "name": "patient",
      "valueId": "123"
    },
    {
      "name": "type",
      "valueCoding": {
        "system": "http://loinc.org",
        "code": "34133-9"
      }
    }
  ]
}'

With Document Type
curl -X POST https://fhirtest.netsmartcloud.com/provider/patient-access/v2/DocumentReference/\$docref \
    -H "Authorization: {Bearer Token}" \
    -H "Accept: application/fhir+json" \
    -H "Content-Type: application/fhir+json" \
    -d '{
  "resourceType": "Parameters",
  "parameter": [
    {
      "name": "patient",
      "valueId": "123"
    },
    {
      "name": "type",
      "valueCoding": {
        "system": "http://loinc.org",
        "code": "34133-9"
      }
    }
  ]
}'

Integration Patterns

Common workflows involving DocumentReference:

Document Creation: Create new document references for clinical notes, reports, and imaging studies
Document Management: Update document metadata and status as documents are amended or superseded
Document Discovery: Search for documents by patient, type, or category using standard search or the $docref operation
Clinical Document Access: Retrieve references to clinical notes, reports, and imaging studies
Care Coordination: Share document references across healthcare systems

Related resources: Patient, Practitioner, Organization, Provenance

Error Handling

For error responses and troubleshooting, see the Error Handling Guide.

Supported Profiles

This API supports the following FHIR profiles:

US Core DocumentReference

Overview​

Resource Schema​

Operations​

Create​

Read​

Update​

Search​

GET Method​

POST Method​

Search Parameters​

GET Method​

POST Method​

Operation Parameters​

GET Method​

POST Method​

Operation Parameters​

Examples​

Create a DocumentReference​

Update a DocumentReference​

Search by Patient and Type​

Fetch Documents Using $docref Operation (GET)​

Fetch Documents Using $docref Operation (POST)​

Integration Patterns​

Error Handling​

Supported Profiles​

Overview

Resource Schema

Operations

Create

Read

Update

Search

GET Method

POST Method

Search Parameters

GET Method

POST Method

Operation Parameters

GET Method

POST Method

Operation Parameters

Examples

Create a DocumentReference

Update a DocumentReference

Search by Patient and Type

Fetch Documents Using $docref Operation (GET)

Fetch Documents Using $docref Operation (POST)

Integration Patterns

Error Handling

Supported Profiles