DocumentReference

Work with FHIR R4 4.0.1 DocumentReference resources.

Choose an operation for this resource:

The diagram summarizes DocumentReference requests and responses. See Supported FHIR REST Interactions for the shared interaction model.

FHIR R4 definition: https://hl7.org/fhir/R4/documentreference.html. See interaction response codes and common error responses.

The base endpoint is /api/fhir/r4/DocumentReference. Store document metadata and attachment descriptions here. DDFS preserves the supplied content and historical versions, including extensions and primitive companion metadata. It does not fetch attachment URLs, expose a Binary endpoint, ingest external documents, or process document contents.

Interactions and responses

Request	Successful response
`POST /DocumentReference`	201 Created; the server assigns the logical ID and version.
`GET /DocumentReference/{id}`	200 with the current resource.
`GET /DocumentReference/{id}/_history/{version}`	200 with the requested historical resource.
`PUT /DocumentReference/{id}`	200 for replacement; 201 for PUT-as-create or restoration. The body ID must match the URL ID.
`DELETE /DocumentReference/{id}`	204 after soft deletion. The resource is excluded from current searches.
`GET /DocumentReference` or form-encoded `POST /DocumentReference/_search`	200 with a `searchset` Bundle.
`POST /DocumentReference/{id}/$hardDelete`	200 with an `OperationOutcome` after permanent removal of a soft-deleted resource. Soft-delete the resource first.
`POST /DocumentReference/$purgeDeleted`	200 with an OperationOutcome. Supply the existing FHIR Parameters body with `before` and `limit`; only eligible soft-deleted resources are purged.

Resource lifecycle: create, read, versioned read, update, soft deletion and version preconditions.
PUT-as-create and restoration: creation/restoration, server-managed metadata, response headers and return preferences.
Interaction responses: success status codes.
OperationOutcome errors: common errors and response bodies.
Batch requests: independent entry processing.

DocumentReference capability	Support or requirement
Conditional create	Not supported.
Conditional update	Not supported.
Transaction bundles	Not supported.

Supported searches

Search operation: endpoints, complete parameter table, supported forms and examples.
Common Search Controls: shared controls and server-provided paging links.
Value Types and Syntax and Comparators, Modifiers, and Chains: shared syntax. Use only the forms supported by this resource.

DocumentReference detail	Requirement or behavior
Date filters	Date, `period` and `_lastUpdated` support up to two repeated bounds and the `eq`, `ne`, `gt`, `lt`, `ge`, `le`, `sa`, `eb` and `ap` comparators.
Limitations	Comma alternatives are unsupported.
Limitations	Resource token and reference parameters accept one occurrence; token modifiers and new reference chains are unsupported.
Resource rule	Follow the `next` Bundle link unchanged for pagination.
Resource rule	The `_sort` parameter is ignored.
Write provenance	The existing `_revinclude`=`Provenance:target` expansion is available with the required Provenance access.
Resource rule	See supported search parameters.

Parameter	Meaning
`identifier`	Matches masterIdentifier and `identifier` using one unmodified token: value, `system\|value`, `\|value` (no system), or system\|.
`patient`	Matches `subject` restricted to Patient targets. The existing `:identifier` modifier searches the `identifier` carried on the reference.
`category`, `type`, `status`	Token searches on the corresponding DocumentReference fields. Status values are current, superseded and entered-in-error. Status has the implicit system `http://hl7.org/fhir/document-reference-status`; use a `code`, `system\|code`, or system\|. An explicit no-system token such as `\|current` does not match.
`date`	Reference creation time in DocumentReference.date; the supplied value is an instant.
`period`	Clinical service `period` in DocumentReference.context.period.

GET /api/fhir/r4/DocumentReference?patient=Patient/patient-1&category=genetics&status=current&date=ge2026-01-01&date=lt2027-01-01
POST /api/fhir/r4/DocumentReference/_search
Content-Type: application/x-www-form-urlencoded

patient=Patient%2Fpatient-1&period=ge2026-02-01&period=lt2026-03-01

Create example

DocumentReference detail	Requirement or behavior
Status	Status and at least one content element are required; each content element requires an Attachment.
Resource rule	The optional `docStatus` binding permits `preliminary`, `final`, `amended` and entered-in-error.
References	References must use the targets allowed by the R4 resource definition.
Write provenance	The generated Provenance describes the change to the reference resource.

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

{
  "resourceType": "DocumentReference",
  "status": "current",
  "masterIdentifier": {"system": "urn:example:documents", "value": "synthetic-report-1"},
  "subject": {"reference": "Patient/patient-1"},
  "date": "2026-04-20T10:11:12Z",
  "content": [{"attachment": {"contentType": "text/plain", "url": "https://example.test/synthetic-report"}}],
  "context": {"period": {"start": "2026-02-01", "end": "2026-02-28"}}
}

Permissions and limits

Authentication and Scopes: bearer tokens, scope configuration and constrained access. Required resource scopes are listed on each operation page.
Data Deletion and Purge Operations: permanent-deletion eligibility and additional permissions.
Hard Delete and Purge Deleted: resource endpoints and required scopes; see also shared purge guidance.

Item	Requirement or behavior
Limitations	Conditional create, conditional update and transaction participation are not supported.
References	Does not provide R6 DocumentReference endpoint, encounter/context filters, clinician/organization filters, full-text search, attachment retrieval service or US Core certification.

Oracle Cloud Infrastructure Documentation

DocumentReference

Interactions and responses

Supported searches

Create example

Permissions and limits