US Core Implementation Guide
10.0.0-ballot - STU 10 Ballot United States of America flag

US Core Implementation Guide, published by HL7 International / Cross-Group Projects. This guide is not an authorized publication; it is the continuous build for version 10.0.0-ballot built by the FHIR (HL7® FHIR® Standard) CI Build. This version is based on the current content of https://github.com/HL7/US-Core/ and changes regularly. See the Directory of published versions

Writing Documents

Page standards status: Informative

The conformance verbs used below describe the intended semantics if the content is adopted, but they carry no US Core conformance or certification requirements until the page standards status changes from 'informative'.

Purpose and Scope

This page defines a US Core approach to writing any document type, such as clinical notes, insurance cards, and advance directives, to a FHIR server as DocumentReference resources. It does not change how servers return documents in searches. It replaces US Core's Version 9 Clinical Notes guidance page and adopts conventions used in Writing Vital Signs and the Continuous Glucose Monitoring Implementation Guide.

In Scope

  • Writing DocumentReference resources using FHIR RESTful create
    • Optional $submit-bundle transaction
  • Server documentation and discovery
  • DocumentReference required and Must-Support elements
  • Submission Modes
  • Corrections and Replacements
  • Provenance
  • SMART scopes

Out of Scope

  • Specific directions on how to exchange CDA or FHIR documents
  • Stateful or draft workflows (for example, ambient scribing or continuous audio capture)
  • FHIR batch and transaction interactions
  • Downstream workflows after a server accepts a document

Experimental Topics


Definitions

Below is a glossary of terms used on page.

  • Server: a FHIR Server that creates, updates, and exposes clinical data via FHIR's RESTful APIs
  • App: Also referred to as a client or application, an app is a software application developed by a vendor that operates with a health data platform or Electronic Health Record (EHR) system to access clinical data.
  • Provider Write: A provider-facing app adds a document to a patient's record at a practitioner's direction. The document is available through read and search as soon as the server accepts it.
  • Patient Write: A patient-facing app, used by the patient or an authorized representative, sends a document to the patient's provider. Patient Write covers both Patient Mediated Write and Patient Generated Write. These documents carry the PATAST security label.
  • Patient Mediated Write: A Patient Write where the patient forwards a document that someone else authored, such as a discharge summary from a previous provider. The patient delivers the document but did not create it.
  • Patient Generated Write: A Patient Write where the patient authored all or part of the content, such as an insurance card photo, an advance directive, or an activity report.
  • Solicited Submissions: A Patient Write that responds to a provider's request for a specific document, recorded as a ServiceRequest. The submitted document references that request in context.related. Provider Writes are always treated as solicited.
  • Unsolicited Submissions: A Patient Write sent without a specific provider request. The server may hold the document for review before it becomes available through read and search.

Writing DocumentReference

This documentation establishes client and server rules and guidance for writing documents to a FHIR server. The FHIR RESTful create transport mechanism refers to the ability of a client to instantiate a new resource via HTTP POST. It builds directly on the US Core DocumentReference profile and US Core Clinical Notes guidance. This mechanism allows for simple exchange in scenarios where no additional resources are necessary.

$submit-bundle Operation

Servers have the option of supporting the $submit-bundle Operation. It allows additional FHIR resources to be submitted by the client but permits partial acceptance by the server. Servers process the DocumentReference under the same rules as one submitted with RESTful create, including the processing expectation, submission modes, solicitation, and documented support.


Processing Expectation

Servers accept only the documents that the organization will actually process or review. Patients usually assume that a submitted document reaches their care team. Accepting content that no one will process or review creates a false expectation.

Requirements

  • Servers SHALL support create for DocumentReference.§
  • Servers SHALL only accept documents that the organization can and intends to process or review.§
  • Servers SHALL NOT document support for a DocumentReference category or type that the organization cannot or does not intend to process or review.§
  • Servers SHALL respond 201 Created with a Location header when the document is available on return.§
  • Servers SHALL respond 202 Accepted when it is held for review.§
  • Servers SHOULD return an OperationOutcome on failed writes.§

Guidance

"Process or review" includes filing an insurance card, routing a document to a later review queue, and rejecting content the deployment cannot handle. A person does not need to inspect every submission. See the Document Type and Category below for specific guidance on categories and types.

Whether the server returns a 201 Created or a 202 Accepted depends on the Submission mode:

Submission Mode Response Available through read and search
Provider Write (always solicited) 201 Created Immediately
Patient Solicited 201 Created Immediately
Patient Unsolicited 201 Created or 202 Accepted Server policy

See the Submission Modes Section below for further guidance and examples.


Discovery

For integrated-application workflows (for example, provider-facing apps), capabilities are negotiated while working through integration and runtime advertisement and client discovery is not needed. However, for patient-facing applications, runtime advertisement and client discovery are critical to proper function.

Requirements

  • Servers SHALL publish API documentation covering supported categories and types, MIME types, size limits, $submit-bundle support, and review policy.§
  • Servers SHOULD support ValueSet/$expand with contextDirection=incoming.§

Guidance

The rules on this page do not require a server to support any particular category, type, or MIME type. See the Document Type and Category below for specific guidance on these parameters. How a Client can determine the note and report types supported by a server using the ValueSet/$expand operation is described on the Clinical Notes page.

Note that the FHIR R5 based Application Feature Framework can also express support and enumerate specific types and categories. A worked example is provided here


Required and Must-Support Elements

This section builds directly on the US Core DocumentReference profile. It adds the following rules, guidance, and terminology to facilitate document write exchange. Note that this guidance also aligns with the US Core ADI DocumentReference Profile.

US Core Must Support and Writing

All US Core Profiles identify elements with a must-support flag that imposes conformance requirements on both the client and server. However, the US Core Must Support definition is framed entirely in terms of requesters and responders - reading or returning data. None of its provisions is scoped to writing. The following clarifications apply for the purposes of this guidance:

  • Unless the element has a minimum cardinality greater than 0, a submitted DocumentReference that omits a must-support element is still conformant.
  • Servers can accept resources that omit must-support elements and might reject a submission because of a business rule whether or not it is a must-support element.

Document Type and Category

The DocumentReference.type and DocumentReference.category elements are necessary for understanding what the document is. They are used by a server to advertise support and by a client to identify the contents of its submission.

  • category is the broad classification used to determine what kind of data is being presented. It is the primary signal for routing, for workflow selection, and as the entry point for discovering supported types. A DocumentReference instance can have multiple categories.
  • type is the specific classification used to identify the exact contents of the document. A DocumentReference instance can only have one type and is bound to LOINC document types or the concept "unknown".

Client Requirements

  • Clients SHALL populate at least one category and a type on submission.§

Server Requirements

  • Servers SHALL publish API documentation covering supported categories and types.§
  • Servers SHALL support at least one category.§
  • Servers SHALL NOT reject a submission with unsupported category codes if it contains at least one category code (as a repeating element) they support.§
  • Servers SHALL NOT reject a submission with unsupported type codes if it contains at least one code translation they support.§
  • Servers SHOULD preserve the submitted coding(s) as received.§

Guidance

  • Server documents the specific type codes for each supported category such that a patient is capable of selecting appropriate content. A server is not expected to accept categories and types it does not natively support.
  • Because type and category are CodeableConcept datatypes, clients might populate the specific advertised coding and include the other codes in the same coding array as translations.

The codes listed in this section are a starter set of recommendations, not conformance requirements. A server might use some of them or support codes that do not appear here. Actual support is established by what a server documents and advertises.

Currently, the US Core DocumentReference Category value set contains one concept, clinical-note, and the US Core ADI DocumentReference Profile lists four LOINC codes, including 42348-3 (Advance healthcare directives).

The recommended categories below address what the document is for which drives routing, workflow, and the type discovery described in this guidance.

Row Code System Display Definition
1 clinical-note http://hl7.org/fhir/us/core/CodeSystem/us-core-documentreference-category Clinical Note existing Purpose - Clinical Note
2 42348-3 http://loinc.org Advance Healthcare Directives existing Purpose - Advance Healthcare Directives
3 medical-history http://hl7.org/fhir/us/core/CodeSystem/us-core-documentreference-category Medical History Purpose - Medical History
4 insurance-document http://hl7.org/fhir/us/core/CodeSystem/us-core-documentreference-category Insurance or Coverage related documentation Purpose - Insurance or Coverage related documentation
5 identity-document http://hl7.org/fhir/us/core/CodeSystem/us-core-documentreference-category Identity documentation Purpose - Identity documentation

The US Core DocumentReference Profile DocumentReference.type has a required binding to the US Core DocumentReference Type value set, which is composed of LOINC document types plus the concept "unknown". (the US Core ADI DocumentReference Profile Advance Healthcare Directive Categories value set is a subset).

The recommended types below are grouped by category.

  • Category clinical-note: The US Core Clinical Notes page defines the eleven Common Clinical Notes types. For other note types, use codes from the US Core DocumentReference Type value set.

  • Category LOINC 42348-3 (Advance healthcare directives): Use LOINC codes drawn from the Advance Healthcare Directive Document Types Grouper value set.

  • Categories medical-history, insurance-document, and identity-document: Supported types are established entirely through server advertisement and are drawn from the US Core DocumentReference Type value set.

    For example:

    Category Code Display
    insurance-document / identity-document 64290-0 Health insurance card
    medical-history 73985-4 Exercise activity
    medical-history 55424-6 Calories burned in unspecified time by Pedometer
When No Standard Type Code Exists

US Core DocumentReference Profile required binding on DocumentReference.type means a submission with no conformant coding cannot satisfy the US Core profile.

Where a document type genuinely has no suitable LOINC code and uses a local concept, a server might choose to support that submission as a non-conformant US Core profile.

Alternatively, to satisfy the required binding, a locally-defined coding can be accompanied by a generic "catch-all" coding from the value set as a code translation. For example, these LOINC codes might be used:

Category Code Display
medical-history 11503-0 Medical records
medical-history 47045-0 Study report
Type Granularity and Mapping

When reading documents, a server commonly collapses several internal document types into a single standard code - for example, mapping ten local progress note variants onto LOINC 11506-3. That collapse is lossy and cannot be reversed on write: a server receiving only 11506-3 has no way to recover whether the source meant a pediatric or an adult progress note, and is forced to select a default.

The submitting system usually knows the correct granular answer. By populating the most specific advertised type coding, and including a more specific code in the same type.coding array as a translation, the granularity is preserved.


References: Author and Context.encounter

Client Requirements

  • Clients SHALL be capable of populating author and context.encounter when they are known.§
  • When a Client populates .author or .context.encounter, .reference SHALL be a relative reference to a resource on the Server, or a reference to a contained resource, or a logical reference.§
  • When a Client populates .author or .context.encounter, .display SHOULD be populated.§

Server Requirements

  • Servers SHALL accept both relative references to resources on the server and references to contained resources for author and context.encounter.§
  • Servers SHOULD accept logical references for author and context.encounter.§
  • Servers SHALL NOT reject a submission solely because an author or context.encounter reference cannot be resolved.§
  • Servers SHOULD attempt to match author and context.encounter references to existing resources.§
  • Servers MAY persist the content of a contained author or Encounter resource.§
  • Servers MAY require context.encounter by business rule.§

Guidance

  • For SMART apps, the launch/patient context value is a candidate for author when the patient is the author, and the launch/encounter context value is a candidate for context.encounter.
  • Relative references point to resources that already exist on the server, for example Practitioner/123 or Encounter/123. When the author or encounter has no server-side resource to reference, the client includes it as a contained resource and references it by its local id, for example #prac1 or #enc1.
  • Note that a server can require an encounter association and still accept a reference it cannot resolve.

Date Handling

Client Requirements

  • Clients SHALL use context.period to convey the clinically relevant time period.§

Guidance

DocumentReference.date is when the DocumentReference was created, not when the content was authored. DocumentReference.content.attachment.creation is when the attached content was first created. This guidance introduces no other authored-date element.


Identifier

Client Requirements

  • Clients SHOULD populate identifier with a value that is unique to the document and stays the same if the document is resubmitted.§

Server Requirements

  • Servers SHOULD support conditional create (If-None-Exist).§
  • Servers MAY detect duplicates using identifiers, hashes, or other methods.§

Guidance

  • Some servers require pre-coordination with the submitting organization before an identifier of a specific type is stored.
  • Conditional create prevents duplicates only when the client populates identifier. For example: If-None-Exist: identifier=http://example.org/docs|DS-2026-06-30-117.
  • Duplicate detection protects against network retries and resubmissions of the same document. It does not replace the relatesTo replacement mechanism for revised documents.
Context.related

Client Requirements

  • Clients SHALL populate context.related with a relative reference to the ServiceRequest when the document responds to a solicited request.§

Guidance

  • See the Submission Modes section below for further guidance and examples.
  • Other context elements might be populated, but this guidance is silent on them.

Patient-asserted Signaling

Client Requirements

  • Clients SHALL include meta.security with the code PATAST from http://terminology.hl7.org/CodeSystem/v3-ObservationValue when the content is patient-supplied.§

Server Requirements

  • Servers SHALL NOT remove the PATAST code.§
  • Servers MAY add the PATAST code by policy.§

Guidance

Patient-supplied content includes both Patient Mediated Write and Patient Generated Write submissions. See the Submission Modes section below for further guidance and examples. Because servers don't remove the code, it can be relied on to tell where the content came from.

An example of a server policy is adding PATAST to every submission made with a patient/ scope.


MIME Support

Server Requirements

  • Servers SHALL accept at least one of text/plain; charset=utf-8, application/pdf, image/jpeg, or image/png for each supported document type.§
  • Servers SHALL document the MIME types they accept for each supported document type.§

Guidance

Typical choices are application/pdf for forms and reports, image/jpeg or image/png for photos and scans such as insurance cards, and text/plain; charset=utf-8 for narrative notes.


Size Limits

Server Requirements

  • Servers SHALL accept inline content.attachment.data whose decoded content is at least 5 MiB (5,242,880 bytes).§
  • Servers SHALL document their attachment size limits.§
  • Servers SHALL NOT expose a client-supplied content.attachment.url to later readers.§
  • Servers MAY accept content by content.attachment.url, including content larger than their inline limit.§

Guidance

The 5 MiB limit applies to the decoded content, matching the meaning of Attachment.size. Base64 encoding adds about 33%, so the request body is larger. A server that accepts url content retrieves and stores it. Later readers get the server's copy, not the client's link.


Submission Modes

This section illustrates the following write submission modes and documents their unique rules and guidance:

  • Provider Write
  • Solicited Patient Write
  • Unsolicited Patient Write (Including Patient Mediated Write)

Each use case shows the interaction and an example.

Quick-reference Matrix

Every rule on this page applies to all three submission modes unless it appears in this table. This table lists only the rules and guidance that differ by mode; the Conformance Requirements tables at the end of the page list every statement in full, one table per actor, with the key cited here.

Key Rule Actor Provider Write Solicited Patient Write Unsolicited Patient Write
CONF-WD-04, CONF-WD-05 Response on a successful write Server 201 Created 201 Created 201 Created or 202 Accepted by documented policy
CONF-WD-40, CONF-WD-44 Make the document available through read and search without further action Server SHALL SHALL Server policy
CONF-WD-50 Document the review policy for patient submissions Server n/a n/a SHALL
CONF-WD-39 Support the create scope user/DocumentReference.c or system/DocumentReference.c Server SHALL n/a n/a
CONF-WD-41, CONF-WD-51, CONF-WD-70 Support the create scope patient/DocumentReference.c Server n/a SHALL SHALL
CONF-WD-42 Support the scope patient/ServiceRequest.rs Server n/a SHALL n/a
CONF-WD-43 Make ServiceRequest resources with the patient as performer available through read and search Server n/a SHALL n/a
CONF-WD-29, CONF-WD-49 Populate context.related, or the FHIR R5 basedOn extension, with the active ServiceRequest Client n/a SHALL n/a
CONF-WD-47 Document whether to populate context.related or the FHIR R5 basedOn extension Server n/a SHALL n/a
CONF-WD-30, CONF-WD-48, CONF-WD-54 Include meta.security = PATAST Client n/a SHALL SHALL
CONF-WD-31, CONF-WD-45, CONF-WD-52 Do not remove the PATAST code Server n/a SHALL NOT SHALL NOT
CONF-WD-32, CONF-WD-46, CONF-WD-53 Add the PATAST code by policy Server n/a MAY MAY
- author is the patient, with launch/patient as a candidate value Client n/a Guidance Guidance
- launch/encounter is a candidate value for context.encounter Client Guidance n/a n/a
- Support the DocumentReference Attestor R5 Extension for document types such as living wills Server n/a n/a Guidance

Reading this table

  • "Server policy" means the page sets no conformance verb and leaves the behavior to documented server policy. "Guidance" means the page offers guidance for that mode but states no conformance verb. "n/a" means the page states no rule for that mode.
  • A category-specific scope can be supported in place of any create scope listed. See SMART Scopes.
  • A rule's own preconditions stay in its statement text in the Conformance Requirements tables - for example, the .u scopes are required only of a server that allows status correction or replacement.
Provider Write

A provider-facing app adds a document to a patient's record at a practitioner's direction. The document is available through the FHIR Server that created it exposing data via its FHIR's RESTful read and search API.

Additional Rules and Guidance for Provider Write

Authorization:

  • Scopes: servers SHALL support FHIR RESTful create using <user|system>/DocumentReference.c, or category-specific version(s) such as <user|system>/DocumentReference.c?category=clinical-note.§

FHIR RESTful API:

  • Servers SHALL make the document available through read and search without further action. The response is always 201.§

DocumentReference Elements:

  • The launch/encounter parameter that an app includes in its SMART authorization request is a candidate value for context.encounter.

Example: A cardiologist uses an analytics app launched from the EHR to save a PDF trend report to a patient's record.

sequenceDiagram actor Clinician participant EHR as EHR (FHIR Server) participant App as Provider App Note over Clinician,EHR: Clinician opens the app
from the patient's chart EHR->>App: SMART EHR launch (iss, launch) App->>EHR: Authorize (user/DocumentReference.c) EHR-->>App: Access token with patient and encounter context App->>EHR: POST DocumentReference (application/pdf) EHR-->>App: 201 Created, Location App->>EHR: GET DocumentReference?patient=[id] EHR-->>App: Bundle including the new report Note over EHR: The report is also available in the patient's chart

Scenario

A cardiologist, Dr. Chris Bell, reviews a five-year blood pressure trend report for a patient, Vanessa Reyes, in an analytics app launched from the patient's chart in the EHR. At the cardiologist's direction the app saves the report to the patient's record as a PDF, then searches for it to confirm the write.

The example uses these values:

  • FHIR base URL [base]: https://ehr.example.com/r4
  • Patient: Patient/99feede8-2c8c-4135-92d1-083576edc1f8 (Vanessa Reyes)
  • Encounter: Encounter/enc-20260721-7
  • Authorizing user: Practitioner/3a7b6461-1fa6-4ba9-adff-0a7ff6668a62 (Dr. Chris Bell)
  • Document identifier: system http://example.org/trendview/reports, value rpt-202607-0042

The app and the EHR established which categories, types, MIME types, and size limits the EHR accepts during integration, so this example includes no runtime discovery step. See Discovery.


Step 1: The EHR launches the app

The cardiologist opens the app from the patient's chart. The EHR invokes the app's registered launch URL with the iss and launch parameters defined by SMART App Launch.

GET https://app.example.com/launch?iss=https%3A%2F%2Fehr.example.com%2Fr4&launch=xyz123

Step 2: The app requests authorization

The app asks for the scopes it needs, including the create scope for DocumentReference. Parameter values are shown unencoded for readability.

GET https://ehr.example.com/auth/authorize?
    response_type=code&
    client_id=trendview-app&
    redirect_uri=https://app.example.com/redirect&
    launch=xyz123&
    aud=https://ehr.example.com/r4&
    scope=launch openid fhirUser user/DocumentReference.crs user/Patient.rs user/Encounter.rs&
    state=98wrghuwuogerg2&
    code_challenge=DJsz...&
    code_challenge_method=S256

user/DocumentReference.crs combines the create permission this guidance requires of the server for Provider Write§ with the read and search permissions the app needs for Steps 4 and 7. A category-specific scope such as user/DocumentReference.crs?category=http://hl7.org/fhir/us/core/CodeSystem/us-core-documentreference-category|clinical-note can be used in its place. See SMART Scopes.


Step 3: The EHR returns an access token with patient and encounter context

The app exchanges the authorization code at the token endpoint.

POST https://ehr.example.com/auth/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&code=5a8b...&redirect_uri=https%3A%2F%2Fapp.example.com%2Fredirect&client_id=trendview-app&code_verifier=erw3...

Response

HTTP/1.1 200 OK
Content-Type: application/json
[other headers]

Response body

{
  "access_token": "i8hweunweunweofiwweoijewiwe",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "launch openid fhirUser user/DocumentReference.crs user/Patient.rs user/Encounter.rs",
  "id_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "patient": "99feede8-2c8c-4135-92d1-083576edc1f8",
  "encounter": "enc-20260721-7"
}

The EHR launch supplies the context the app writes with, so the app does not prompt the cardiologist to select a patient or an encounter:

  • patient is the id the app uses for subject.
  • encounter is the id the app uses for context.encounter. It is a candidate value only; a document that belongs to no encounter omits the element.
  • fhirUser in the id_token resolves to Practitioner/3a7b6461-1fa6-4ba9-adff-0a7ff6668a62, the id the app uses for author.

Step 4: The app reads the patient and encounter context

The app reads both context resources to confirm the chart it was launched against and to populate the display values this guidance recommends on author and context.encounter.§ Responses are abbreviated to the elements the app uses.

GET [base]/Patient/99feede8-2c8c-4135-92d1-083576edc1f8
Authorization: Bearer i8hweunweunweofiwweoijewiwe
Accept: application/fhir+json

Response body

{
  "resourceType": "Patient",
  "id": "99feede8-2c8c-4135-92d1-083576edc1f8",
  "name": [
    {
      "family": "Reyes",
      "given": ["Vanessa"]
    }
  ],
  "gender": "female",
  "birthDate": "1962-03-14"
}
GET [base]/Encounter/enc-20260721-7
Authorization: Bearer i8hweunweunweofiwweoijewiwe
Accept: application/fhir+json

Response body

{
  "resourceType": "Encounter",
  "id": "enc-20260721-7",
  "status": "in-progress",
  "class": {
    "system": "http://terminology.hl7.org/CodeSystem/v3-ActCode",
    "code": "AMB",
    "display": "ambulatory"
  },
  "type": [
    {
      "text": "Cardiology office visit"
    }
  ],
  "subject": {
    "reference": "Patient/99feede8-2c8c-4135-92d1-083576edc1f8"
  },
  "period": {
    "start": "2026-07-21T15:00:00Z"
  }
}

Note that context.period carries the clinically relevant period of the report content, not the encounter period.§ Here that is the five-year span of the trend data, while the encounter is the visit at which the report was reviewed.


Step 5: The app writes the document

The app submits the report with FHIR RESTful create. If-None-Exist makes the write idempotent against a network retry, using the identifier the app assigns to the document.§§

POST [base]/DocumentReference
Authorization: Bearer i8hweunweunweofiwweoijewiwe
Content-Type: application/fhir+json
Accept: application/fhir+json
If-None-Exist: identifier=http://example.org/trendview/reports|rpt-202607-0042

Request body

The content.attachment.data value below is a truncated placeholder for the base64 encoded PDF.

{
  "resourceType": "DocumentReference",
  "identifier": [
    {
      "system": "http://example.org/trendview/reports",
      "value": "rpt-202607-0042"
    }
  ],
  "status": "current",
  "type": {
    "coding": [
      {
        "system": "http://loinc.org",
        "code": "70004-7",
        "display": "Diagnostic study note"
      }
    ]
  },
  "category": [
    {
      "coding": [
        {
          "system": "http://hl7.org/fhir/us/core/CodeSystem/us-core-documentreference-category",
          "code": "clinical-note",
          "display": "Clinical Note"
        }
      ]
    }
  ],
  "subject": {
    "reference": "Patient/99feede8-2c8c-4135-92d1-083576edc1f8",
    "display": "Vanessa Reyes"
  },
  "date": "2026-07-21T15:30:00Z",
  "author": [
    {
      "reference": "Practitioner/3a7b6461-1fa6-4ba9-adff-0a7ff6668a62",
      "display": "Dr. Chris Bell"
    }
  ],
  "content": [
    {
      "attachment": {
        "contentType": "application/pdf",
        "data": "JVBERi0xLjcK...",
        "title": "Cardiology trend report - Vanessa Reyes",
        "creation": "2026-07-21"
      }
    }
  ],
  "context": {
    "encounter": [
      {
        "reference": "Encounter/enc-20260721-7",
        "display": "Cardiology office visit, 2026-07-21"
      }
    ],
    "period": {
      "start": "2021-07-01",
      "end": "2026-07-21"
    }
  }
}

Every value in the submission comes from the launch context or from the report itself: subject and author from Step 3, their display values and the encounter display from Step 4, date from the moment of submission, and attachment.creation from when the app generated the PDF.


Step 6: The EHR accepts the document

A Provider Write is always solicited, so the response is 201 Created with a Location header and the document is available through read and search without further action.§§ The ETag and Last-Modified headers are not required by this page; base FHIR asks a server to return them on a create when it supports versioning.

HTTP/1.1 201 Created
Location: https://ehr.example.com/r4/DocumentReference/doc-rpt-202607-0042/_history/1
ETag: W/"1"
Last-Modified: Tue, 21 Jul 2026 15:30:04 GMT
[other headers]

The response body is the created resource. As base FHIR requires of a create, the EHR populated id, meta.versionId, and meta.lastUpdated. It also stamped meta.profile with the US Core DocumentReference profile and preserved the submitted codings as received.§

In this example the EHR also sets custodian to the organization responsible for the record. Nothing on this page requires that; see Open Questions.

The submission carries no meta.security code of PATAST: the content is provider-supplied, not patient-asserted. See Patient-asserted Signaling.


Step 7: The app searches for the document

The app confirms the write with a search that the US Core DocumentReference Profile Quick Start requires servers to support.

GET [base]/DocumentReference?patient=99feede8-2c8c-4135-92d1-083576edc1f8&category=http://hl7.org/fhir/us/core/CodeSystem/us-core-documentreference-category|clinical-note
Authorization: Bearer i8hweunweunweofiwweoijewiwe
Accept: application/fhir+json

Response

HTTP/1.1 200 OK
Content-Type: application/fhir+json
[other headers]

Response body

The new report is in the search set. Earlier notes for the patient are omitted here, and the matched resource is abbreviated.

{
  "resourceType": "Bundle",
  "type": "searchset",
  "total": 1,
  "link": [
    {
      "relation": "self",
      "url": "https://ehr.example.com/r4/DocumentReference?patient=99feede8-2c8c-4135-92d1-083576edc1f8&category=http%3A%2F%2Fhl7.org%2Ffhir%2Fus%2Fcore%2FCodeSystem%2Fus-core-documentreference-category%7Cclinical-note"
    }
  ],
  "entry": [
    {
      "fullUrl": "https://ehr.example.com/r4/DocumentReference/doc-rpt-202607-0042",
      "resource": {
        "resourceType": "DocumentReference",
        "id": "doc-rpt-202607-0042",
        "status": "current",
        "subject": {
          "reference": "Patient/99feede8-2c8c-4135-92d1-083576edc1f8"
        },
        "date": "2026-07-21T15:30:00Z",
        "content": [
          {
            "attachment": {
              "contentType": "application/pdf",
              "url": "/Binary/doc-rpt-202607-0042-pdf",
              "title": "Cardiology trend report - Vanessa Reyes"
            }
          }
        ]
      },
      "search": {
        "mode": "match"
      }
    }
  ]
}

The EHR returns the attachment it stored as a url to a Binary resource rather than inline, which is its choice on read and is not governed by this page. The report is also available to the care team in the patient's chart.


Solicited Patient Write

A patient-facing app sends a patient-authored document to the patient's provider in response to a provider's request - recorded as a ServiceRequest. The document is available through the FHIR Server that created it exposing data via its FHIR's RESTful read and search API.

Additional Rules and Guidance for Solicited Patient Write

Authorization:

  • Scopes: servers SHALL support patient/DocumentReference.c, or category-specific version(s) such as patient/DocumentReference.c?category=clinical-note.§
  • Scopes: servers SHALL support patient/ServiceRequest.rs.§

FHIR RESTful API:

  • Servers SHALL make the ServiceRequest resources with the patient as performer available through read and search.§
  • Servers SHALL make the document available through read and search without further action. The response is 201.§

ServiceRequest Elements:

  • The ServiceRequest.code provides the specific document LOINC or local type code.
  • The ServiceRequest.performer is the patient. The launch/patient parameter that an app includes in its SMART authorization request is a candidate value for this element.
  • To create a standing order such as a weekly report, set ServiceRequest.status to "active" and define the repeat with ServiceRequest.occurrenceTiming.repeat.

DocumentReference Elements:

  • Servers SHALL NOT remove meta.security = "PATAST".§
  • Servers MAY add meta.security = "PATAST" by policy (for example, based on authorization context), even if it is omitted by the client.§
  • Servers SHALL document whether to populate the active ServiceRequest in context.related, or the FHIR R5 basedOn extension.§
  • Clients SHALL include meta.security = "PATAST" (Patient asserted).§
  • Clients SHALL populate context.related or the FHIR R5 basedOn extension with the active ServiceRequest that requests it.§

  • DocumentReference.author is the patient. The launch/patient parameter that an app includes in its SMART authorization request is a candidate value for this element.

Example: A provider asks a patient to send weekly activity reports from her fitness tracker, and the patient's app submits each report in response to that request.

sequenceDiagram actor Clinician actor Patient participant Server as Provider FHIR Server participant App as Patient App Note over Clinician,Server: Clinician orders weekly
activity reports in the EHR Patient->>App: Open app App->>Server: GET ServiceRequest?patient=[id]&code=[code] Server-->>App: Active ServiceRequest App->>Server: POST DocumentReference (context.related to ServiceRequest) Server-->>App: 201 Created, Location Note over Server: Available to the requesting provider

Scenario

A cardiologist asks a patient, Lin Zhang, to send a weekly activity report from her fitness tracker. The clinician records the request in the EHR as a standing ServiceRequest with the patient as performer. Each week the patient's fitness app finds that request, submits the week's report against it, and confirms the write.

The example uses these values:

  • FHIR base URL [base]: https://provider.example.com/r4
  • Patient: Patient/512cd664-6cd2-4a56-b462-0133464ffaa0 (Lin Zhang)
  • ServiceRequest: ServiceRequest/activity-report-weekly
  • Document identifier: system http://example.org/fitshare/reports, value lin-2026-w29

Authorization

The app is patient-facing, so it uses a SMART standalone launch rather than the EHR launch in the Provider Write example, and the token response carries a patient context value but no encounter. That patient value is the id used for both subject and author, because for a patient write the patient is the author. The full launch and token exchange is shown in the Provider Write example; only the scopes differ here:

  • patient/DocumentReference.c to write the report§
  • patient/ServiceRequest.rs to find the request it responds to§
  • offline_access, so next week's report needs no new sign-in

Step 1: The app finds the request it is responding to

The server makes ServiceRequest resources with the patient as performer available through read and search.§

GET [base]/ServiceRequest?patient=512cd664-6cd2-4a56-b462-0133464ffaa0&status=active
Authorization: Bearer j4kfhw84hf8w4hf8w4hf8w4h
Accept: application/fhir+json

Response body

The search set holds one active request. The resource is abbreviated to the elements the app uses.

{
  "resourceType": "Bundle",
  "type": "searchset",
  "total": 1,
  "entry": [
    {
      "fullUrl": "https://provider.example.com/r4/ServiceRequest/activity-report-weekly",
      "resource": {
        "resourceType": "ServiceRequest",
        "id": "activity-report-weekly",
        "status": "active",
        "intent": "order",
        "code": {
          "coding": [
            {
              "system": "http://loinc.org",
              "code": "51855-5",
              "display": "Patient Note"
            }
          ],
          "text": "Weekly activity report from fitness tracker"
        },
        "subject": {
          "reference": "Patient/512cd664-6cd2-4a56-b462-0133464ffaa0"
        },
        "performer": [
          {
            "reference": "Patient/512cd664-6cd2-4a56-b462-0133464ffaa0",
            "display": "Lin Zhang"
          }
        ],
        "requester": {
          "reference": "Practitioner/3a7b6461-1fa6-4ba9-adff-0a7ff6668a62",
          "display": "Dr. Chris Bell"
        },
        "authoredOn": "2026-06-15",
        "occurrenceTiming": {
          "repeat": {
            "frequency": 1,
            "period": 1,
            "periodUnit": "wk"
          }
        }
      },
      "search": {
        "mode": "match"
      }
    }
  ]
}

The request tells the app three things: that it is still active and so still expects reports, that occurrenceTiming.repeat makes it a standing weekly order rather than a one-time request, and that code is the document type to submit.


Step 2: The app writes the report

POST [base]/DocumentReference
Authorization: Bearer j4kfhw84hf8w4hf8w4hf8w4h
Content-Type: application/fhir+json
Accept: application/fhir+json
If-None-Exist: identifier=http://example.org/fitshare/reports|lin-2026-w29

Request body

The content.attachment.data value below is a truncated placeholder for the base64 encoded PDF.

{
  "resourceType": "DocumentReference",
  "meta": {
    "security": [
      {
        "system": "http://terminology.hl7.org/CodeSystem/v3-ObservationValue",
        "code": "PATAST",
        "display": "patient asserted"
      }
    ]
  },
  "identifier": [
    {
      "system": "http://example.org/fitshare/reports",
      "value": "lin-2026-w29"
    }
  ],
  "status": "current",
  "type": {
    "coding": [
      {
        "system": "http://loinc.org",
        "code": "51855-5",
        "display": "Patient Note"
      }
    ]
  },
  "category": [
    {
      "coding": [
        {
          "system": "http://hl7.org/fhir/us/core/CodeSystem/us-core-documentreference-category",
          "code": "medical-history",
          "display": "Medical History"
        }
      ]
    }
  ],
  "subject": {
    "reference": "Patient/512cd664-6cd2-4a56-b462-0133464ffaa0",
    "display": "Lin Zhang"
  },
  "date": "2026-07-21T00:00:00Z",
  "author": [
    {
      "reference": "Patient/512cd664-6cd2-4a56-b462-0133464ffaa0",
      "display": "Lin Zhang"
    }
  ],
  "content": [
    {
      "attachment": {
        "contentType": "application/pdf",
        "data": "JVBERi0xLjcK...",
        "title": "Weekly activity report, July 14-20, 2026",
        "creation": "2026-07-21"
      }
    }
  ],
  "context": {
    "period": {
      "start": "2026-07-14",
      "end": "2026-07-20"
    },
    "related": [
      {
        "reference": "ServiceRequest/activity-report-weekly"
      }
    ]
  }
}

Three elements make this a solicited submission rather than an unsolicited one:

  • context.related points at the active ServiceRequest found in Step 1.§ The server documents whether to use this element or the FHIR R5 basedOn extension.§
  • meta.security carries PATAST, because the content is patient-supplied.§ The server does not remove it,§ so a later reader can tell where the content came from.
  • author is the patient, taken from the patient context value in the token response.

context.period is the week the activity was recorded, not the moment of submission.§ date is when the app created the DocumentReference, and attachment.creation is when it generated the PDF. The identifier carries the week number, so next week's report gets its own identifier and If-None-Exist suppresses only a retry of this one.§


Step 3: The server accepts the report

A solicited submission answers a request the provider already made, so it is accepted and filed without review. The response is 201 Created.§

HTTP/1.1 201 Created
Location: https://provider.example.com/r4/DocumentReference/doc-lin-2026-w29/_history/1
ETag: W/"1"
Last-Modified: Tue, 21 Jul 2026 00:04:12 GMT
[other headers]

The response body is the created resource, with id, meta.versionId, and meta.lastUpdated populated as base FHIR requires of a create. The server also stamped meta.profile with the US Core DocumentReference profile, preserved the submitted codings as received,§ and left meta.security in place, so the PATAST code is still on the stored resource.§


Reads and searches

The report is available through read and search immediately, with no further action by the patient or the provider.§ A confirmation search takes the same form as the one in the Provider Write example, and the returned DocumentReference keeps the context.related reference, which ties the report back to the order for the clinician who asked for it.

Next week the app repeats these steps with a new identifier and a new context.period, against the same standing ServiceRequest.


Unsolicited Patient Write

A patient-facing app sends a document to the patient's provider without a specific provider request. The document can be patient-generated, where the patient authored all or part of the content, or patient-mediated where a patient-facing app, used by the patient or an authorized representative, forwards a document to the patient's provider that someone else authored. Servers commonly treat them the same, and might hold the document for review before it becomes available through read and search.

Additional Rules and Guidance for Unsolicited Patient Write

Business Rules:

  • Availability through read and search is based on server policy.

Discovery:

  • Servers SHALL document their review policy for patient submissions.§

Authorization:

  • Scopes: servers SHALL support patient/DocumentReference.c, or category-specific version(s) such as patient/us-core-documentreference-category|clinical-note.§

FHIR RESTful API:

  • The response is 201 or 202 depending on documented server policy.

DocumentReference Elements:

  • Servers SHALL NOT remove meta.security = "PATAST".
  • Servers MAY add meta.security = "PATAST" by policy (for example, based on authorization context), even if it is omitted by the client.
  • Clients SHALL include meta.security = "PATAST" (Patient asserted).

  • DocumentReference.author is the patient. The launch/patient parameter that an app includes in its SMART authorization request is a candidate value for this element.
  • The DocumentReference Attestor R5 Extension can also be supported for specific document types like living wills.

Example 1: A patient uses an app to send her advance directive, prepared by her attorney, to her provider as a PDF.

sequenceDiagram actor Patient participant App as Patient App participant Server as Provider FHIR Server Patient->>App: Select living will PDF App->>Server: GET ValueSet/$expand (ADI document types, incoming) Server-->>App: Accepted ADI document types App->>Server: POST DocumentReference Server-->>App: 202 Accepted Note over Server: Held for staff review before filing

Scenario

A patient, Suzie Smith, has an advance healthcare directive her attorney prepared. No provider asked for it. She uses an app to check which directive types her provider accepts, then sends the signed PDF. The provider holds patient submissions for staff review before filing them, so the document is not readable or searchable on return.

The example uses these values:

  • FHIR base URL [base]: https://provider.example.com/r4
  • Patient: Patient/341912d8-207d-4e73-a3a6-17117e602227 (Suzie Smith)
  • Document identifier: system http://example.org/mydirectives/documents, value adi-202607-01

Authorization

The app is patient-facing, so it uses a SMART standalone launch rather than the EHR launch in the Provider Write example, and the token response carries a patient context value but no encounter. That patient value is the id used for both subject and author. The full launch and token exchange is shown in the Provider Write example; only the scopes differ here:

  • patient/DocumentReference.c?category=http://loinc.org|42348-3 to write the directive, and the matching .rs for the read-back. These are category-specific scopes rather than the unrestricted patient/DocumentReference.c, so the grant covers advance healthcare directives and nothing else.§ A server that supports only the unrestricted scope grants that instead. See SMART Scopes.

Step 1: The app discovers which directive types the server accepts

A patient-facing app cannot negotiate its capabilities with every provider in advance, so runtime discovery matters here in a way it does not for a provider-facing app. The app expands the type value set in the incoming direction to learn what this server accepts on write.§

GET [base]/ValueSet/$expand?context=http://hl7.org/fhir/us/core/StructureDefinition/us-core-adi-documentreference#DocumentReference.type&contextDirection=incoming
Authorization: Bearer k2mfy37dhs8dj3kfhw8s
Accept: application/fhir+json

Response body

{
  "resourceType": "ValueSet",
  "status": "active",
  "expansion": {
    "timestamp": "2026-07-21T14:02:11Z",
    "parameter": [
      {
        "name": "context",
        "valueString": "DocumentReference.type"
      },
      {
        "name": "contextDirection",
        "valueString": "incoming"
      }
    ],
    "contains": [
      {
        "system": "http://loinc.org",
        "code": "86533-7",
        "display": "Patient Living will"
      },
      {
        "system": "http://loinc.org",
        "code": "84095-9",
        "display": "Do not resuscitate"
      },
      {
        "system": "http://loinc.org",
        "code": "93037-0",
        "display": "Portable medical order form"
      }
    ]
  }
}

The living will code the patient selected, 86533-7, is in the expansion, so the app proceeds. The server's published API documentation covers the same ground for implementers who cannot call $expand, including the MIME types it accepts, its size limits, and its review policy for patient submissions.§§


Step 2: The app writes the directive

POST [base]/DocumentReference
Authorization: Bearer k2mfy37dhs8dj3kfhw8s
Content-Type: application/fhir+json
Accept: application/fhir+json
If-None-Exist: identifier=http://example.org/mydirectives/documents|adi-202607-01

Request body

The content.attachment.data value below is a truncated placeholder for the base64 encoded PDF.

{
  "resourceType": "DocumentReference",
  "meta": {
    "security": [
      {
        "system": "http://terminology.hl7.org/CodeSystem/v3-ObservationValue",
        "code": "PATAST",
        "display": "patient asserted"
      }
    ]
  },
  "extension": [
    {
      "url": "http://hl7.org/fhir/5.0/StructureDefinition/extension-DocumentReference.attester",
      "extension": [
        {
          "url": "mode",
          "valueCodeableConcept": {
            "coding": [
              {
                "system": "http://hl7.org/fhir/composition-attestation-mode",
                "code": "personal"
              }
            ]
          }
        },
        {
          "url": "time",
          "valueDateTime": "2026-07-14T10:30:00Z"
        },
        {
          "url": "party",
          "valueReference": {
            "reference": "Patient/341912d8-207d-4e73-a3a6-17117e602227",
            "display": "Suzie Smith"
          }
        }
      ]
    }
  ],
  "identifier": [
    {
      "system": "http://example.org/mydirectives/documents",
      "value": "adi-202607-01"
    }
  ],
  "status": "current",
  "type": {
    "coding": [
      {
        "system": "http://loinc.org",
        "code": "86533-7",
        "display": "Patient Living will"
      }
    ]
  },
  "category": [
    {
      "coding": [
        {
          "system": "http://loinc.org",
          "code": "42348-3",
          "display": "Advance healthcare directives"
        }
      ]
    }
  ],
  "subject": {
    "reference": "Patient/341912d8-207d-4e73-a3a6-17117e602227",
    "display": "Suzie Smith"
  },
  "date": "2026-07-21T14:05:00Z",
  "author": [
    {
      "reference": "Patient/341912d8-207d-4e73-a3a6-17117e602227",
      "display": "Suzie Smith"
    }
  ],
  "content": [
    {
      "attachment": {
        "contentType": "application/pdf",
        "data": "JVBERi0xLjcK...",
        "title": "Advance Healthcare Directive - Suzie Smith",
        "creation": "2026-07-14"
      }
    }
  ]
}

meta.security carries PATAST, because the content is patient-supplied.§ The server does not remove it,§ so a later reader can tell the directive arrived from the patient.

author is the patient even though her attorney drafted the document, because the patient is the party who asserts it. The optional DocumentReference Attestor R5 Extension records who signed it and when, which this guidance offers as a candidate for document types such as living wills. The attestation time and attachment.creation are the day she signed, a week before she sent it; date is the moment of submission.§ There is no context.encounter: the directive belongs to no visit.


Step 3: The server accepts the directive for review

The provider's documented policy is to route unsolicited patient submissions to a staff review queue, so the response is 202 Accepted rather than 201 Created.§

HTTP/1.1 202 Accepted
Content-Type: application/fhir+json
[other headers]

Response body

{
  "resourceType": "OperationOutcome",
  "issue": [
    {
      "severity": "information",
      "code": "informational",
      "diagnostics": "Document received and queued for review by health information management. It will appear in the patient's record once accepted."
    }
  ]
}

There is no Location header, because there is no resource to read yet. This page requires an OperationOutcome only on a failed write,§ so returning one here to explain the hold is this server's choice. A 202 is possible only for an unsolicited patient submission; a Provider Write and a Solicited Patient Write are both answered 201.


Step 4: A search does not find the document yet

GET [base]/DocumentReference?patient=341912d8-207d-4e73-a3a6-17117e602227&category=http://loinc.org|42348-3
Authorization: Bearer k2mfy37dhs8dj3kfhw8s
Accept: application/fhir+json

Response body

{
  "resourceType": "Bundle",
  "type": "searchset",
  "total": 0,
  "entry": []
}

Availability through read and search is server policy for an unsolicited submission, which is why the server has to document that policy.§ An app that treats a 202 as "filed" and polls for the document will keep finding nothing until review completes, so a 202 is better surfaced to the patient as submitted and pending. Once staff accept the directive the server files it, and the same search returns it.


Example 2: Before a checkup, a patient uses his provider's portal app to send a photo of his new insurance card.

sequenceDiagram actor Patient participant App as Portal App participant Server as Provider FHIR Server Patient->>App: Photograph new insurance card App->>Server: POST DocumentReference (image/png) Server-->>App: 201 Created, Location Note over Server: Filed for registration staff

Scenario

Before a checkup, a patient, Mike Jones, photographs his new insurance card in his provider's patient portal app and sends it. No provider asked for it, so the submission is unsolicited. The provider's documented policy is to file insurance documents on arrival and let registration staff work them from the chart, so the response is 201 Created rather than 202 Accepted.

The example uses these values:

  • FHIR base URL [base]: https://provider.example.com/r4
  • Patient: Patient/8da636b7-aaaa-44ab-8ed7-604039829eb6 (Mike Jones)

Authorization

The app is patient-facing, so it uses a SMART standalone launch rather than the EHR launch in the Provider Write example, and the token response carries a patient context value but no encounter. That patient value is the id used for both subject and author. The full launch and token exchange is shown in the Provider Write example; only the scopes differ here:

  • patient/DocumentReference.c to write the card, and .rs for the read-back. A server that supports a category-specific scope can restrict the grant to insurance documents instead, with patient/DocumentReference.c?category=http://hl7.org/fhir/us/core/CodeSystem/us-core-documentreference-category|insurance-document.§

The portal app is the provider's own, so the categories, types, MIME types, and size limits were settled during integration and the app needs no runtime discovery.


Step 1: The app writes the document

POST [base]/DocumentReference
Authorization: Bearer p9sdkfj39sdkfj39sdkfj
Content-Type: application/fhir+json
Accept: application/fhir+json

Request body

The content.attachment.data value below is a truncated placeholder for the base64 encoded PNG.

{
  "resourceType": "DocumentReference",
  "meta": {
    "security": [
      {
        "system": "http://terminology.hl7.org/CodeSystem/v3-ObservationValue",
        "code": "PATAST",
        "display": "patient asserted"
      }
    ]
  },
  "status": "current",
  "type": {
    "coding": [
      {
        "system": "http://loinc.org",
        "code": "64290-0",
        "display": "Health insurance card"
      }
    ]
  },
  "category": [
    {
      "coding": [
        {
          "system": "http://hl7.org/fhir/us/core/CodeSystem/us-core-documentreference-category",
          "code": "insurance-document",
          "display": "Insurance Document"
        }
      ]
    }
  ],
  "subject": {
    "reference": "Patient/8da636b7-aaaa-44ab-8ed7-604039829eb6",
    "display": "Mike Jones"
  },
  "date": "2026-07-21T00:00:00Z",
  "author": [
    {
      "reference": "Patient/8da636b7-aaaa-44ab-8ed7-604039829eb6",
      "display": "Mike Jones"
    }
  ],
  "content": [
    {
      "attachment": {
        "contentType": "image/png",
        "data": "iVBORw0KGgo...",
        "title": "Health Insurance Card - Mike Jones"
      }
    }
  ]
}

A photograph is not a narrative document, so the submission differs from the other examples in three ways:

  • contentType is image/png. A server supporting the insurance-document category accepts at least one of text/plain; charset=utf-8, application/pdf, image/jpeg, or image/png for it, and documents which.§§ A phone photograph can exceed the 5 MiB a server is required to accept inline, so an app either downscales it or uses a server that accepts content by url.§§
  • There is no context.period. The card has no clinically relevant period, and the checkup it was sent ahead of has not happened, so there is no encounter to reference either.
  • There is no identifier, so If-None-Exist is not available and a retried submission can produce a second copy. Populating one that stays stable across resubmission is the way to prevent that.§

meta.security still carries PATAST, as it does for every patient submission.§


Step 2: The server accepts the document

HTTP/1.1 201 Created
Location: https://provider.example.com/r4/DocumentReference/doc-ins-88213/_history/1
ETag: W/"1"
Last-Modified: Tue, 21 Jul 2026 00:02:38 GMT
[other headers]

The 201 reflects this server's documented policy for the insurance-document category, not a rule of this page. The same server holds clinical notes from patients for review and answers those 202. Either response is conformant for an unsolicited submission as long as the policy is documented.§§§


Reads and searches

The 201 means the card is on file before the patient arrives, so a confirmation search of the form shown in the Provider Write example returns it right away and the app can show him it was received. Registration staff work it from the chart.


Example 3 (Patient Mediated Write): A patient forwards a discharge summary from another hospital. The hospital is the author, and the document was written a month before it was sent.

sequenceDiagram actor Patient participant App as Patient App participant Server as Provider FHIR Server Patient->>App: Retrieve discharge summary from previous hospital App->>Server: POST DocumentReference (author contained Organization) Server-->>App: 202 Accepted Note over Server: Clinician reviews before adding to chart

Scenario

A patient, Suzie Smith, was discharged from another hospital a month ago. She retrieves the discharge summary from that hospital's patient portal and forwards it to her own provider through her app. The hospital, not the patient, authored the document, and it was written a month before she sent it. The provider holds it for clinician review before it joins the chart.

This is a patient-mediated write: the patient is the submitter but not the author. How the app obtained the document from the other hospital is out of scope for this page.

The example uses these values:

  • FHIR base URL [base]: https://provider.example.com/r4
  • Patient: Patient/341912d8-207d-4e73-a3a6-17117e602227 (Suzie Smith, as known to the receiving provider)
  • Document identifier: system http://riverside.example.org/documents, value DS-2026-06-30-117

Authorization

The app is patient-facing, so it uses a SMART standalone launch rather than the EHR launch in the Provider Write example, and the token response carries a patient context value but no encounter. That patient value is the id used for subject only. Unlike the other patient examples it is not used for author, because the patient did not write this document. The full launch and token exchange is shown in the Provider Write example; only the scopes differ here:

  • patient/DocumentReference.c, the unrestricted create scope, because a forwarded document can be of any category the server accepts

Step 1: The app forwards the discharge summary

POST [base]/DocumentReference
Authorization: Bearer t5hwkd93jfksl20dmfk3
Content-Type: application/fhir+json
Accept: application/fhir+json
If-None-Exist: identifier=http://riverside.example.org/documents|DS-2026-06-30-117

Request body

The content.attachment.data value below is a truncated placeholder for the base64 encoded PDF.

{
  "resourceType": "DocumentReference",
  "meta": {
    "security": [
      {
        "system": "http://terminology.hl7.org/CodeSystem/v3-ObservationValue",
        "code": "PATAST",
        "display": "patient asserted"
      }
    ]
  },
  "contained": [
    {
      "resourceType": "Organization",
      "id": "source-org",
      "name": "Riverside Community Hospital"
    },
    {
      "resourceType": "Patient",
      "id": "source-patient",
      "name": [
        {
          "family": "Smith",
          "given": ["Suzanne"]
        }
      ],
      "birthDate": "1974-03-12"
    }
  ],
  "identifier": [
    {
      "system": "http://riverside.example.org/documents",
      "value": "DS-2026-06-30-117"
    }
  ],
  "status": "current",
  "type": {
    "coding": [
      {
        "system": "http://loinc.org",
        "code": "18842-5",
        "display": "Discharge summary"
      }
    ]
  },
  "category": [
    {
      "coding": [
        {
          "system": "http://hl7.org/fhir/us/core/CodeSystem/us-core-documentreference-category",
          "code": "clinical-note",
          "display": "Clinical Note"
        }
      ]
    }
  ],
  "subject": {
    "reference": "Patient/341912d8-207d-4e73-a3a6-17117e602227",
    "display": "Suzie Smith"
  },
  "date": "2026-07-28T09:15:00Z",
  "author": [
    {
      "reference": "#source-org",
      "display": "Riverside Community Hospital"
    }
  ],
  "content": [
    {
      "attachment": {
        "contentType": "application/pdf",
        "data": "JVBERi0xLjcK...",
        "title": "Discharge Summary - Riverside Community Hospital",
        "creation": "2026-06-30"
      }
    }
  ],
  "context": {
    "period": {
      "start": "2026-06-26",
      "end": "2026-06-30"
    },
    "sourcePatientInfo": {
      "reference": "#source-patient"
    }
  }
}

What makes this submission different from a patient-generated one:

  • author is the authoring hospital, carried as a contained Organization and referenced by its local id #source-org. The receiving server has no Organization resource for Riverside, so there is no relative reference to give. A server accepts a contained reference,§ might persist its content,§ and does not reject the submission just because the reference does not resolve to one of its own resources.§
  • context.sourcePatientInfo holds the demographics the other hospital had on file, as a second contained resource. That lets a reviewer confirm the forwarded document is about this patient.
  • meta.security carries PATAST even though a hospital wrote the content.§ The code says the submission came through the patient, which is what a later reader needs to know; it does not claim the patient authored it.

Three dates carry three different meanings here, and only creation describes the document itself:§

Element Value Meaning
context.period 2026-06-26 to 2026-06-30 the hospital stay the summary covers
attachment.creation 2026-06-30 the day the hospital wrote the summary
date 2026-07-28 the moment the app submitted it, a month later

Step 2: The server accepts the document for review

HTTP/1.1 202 Accepted
Content-Type: application/fhir+json
[other headers]

Response body

{
  "resourceType": "OperationOutcome",
  "issue": [
    {
      "severity": "information",
      "code": "informational",
      "diagnostics": "Document received and routed to the care team for review before it is added to the chart."
    }
  ]
}

An outside document asserts clinical facts a clinician has not seen, so this server reviews it rather than filing it on arrival. The response carries no Location header: nothing is readable yet. Availability through read and search is server policy for an unsolicited submission, and the server documents that policy.§


Reads and searches

A clinician reviews the summary and accepts it, and the server files it. Until then a search finds nothing, as shown in Example 1 of Unsolicited Patient Write above. Once filed, two things the app submitted are still on the stored resource: the PATAST code, which the server does not remove,§ so every later reader can tell the document arrived through the patient rather than from the authoring hospital directly; and the identifier the hospital assigned, so if the patient forwards the same summary again, or the hospital later sends it directly, the server has something to match on.§



Corrections and Replacements

This section establishes client and server rules and guidance for correcting documents after they have been written to a FHIR server. A client can retract a document by changing its status to entered-in-error with the FHIR RESTful patch or update interaction, or supersede it by creating a new DocumentReference that replaces the original. Both mechanisms tell the server and later readers what happened to the document. What a server does next, such as archiving the original or notifying users, is server policy.

Client Requirements

Retraction

  • To mark a document as entered in error, clients SHALL use either a patch that changes only status to entered-in-error, or an update that sends the complete resource with only status changed.§

Replacement

  • To supersede a document, clients SHOULD create a new DocumentReference with relatesTo.code = replaces and relatesTo.target referencing the original.§
  • A replacing document SHALL contain the complete revised content, not only the changes.§
  • Clients SHOULD also populate relatesTo.target.identifier with the original document's identifier when it has one.§

Server Requirements

Retraction

  • Servers SHOULD allow the submitting client to change status to entered-in-error through patch.§
  • Servers MAY allow the submitting client to change status to entered-in-error through update.§
  • Servers SHALL continue to return an entered-in-error document through read for authorized requests.§
  • Servers MAY exclude entered-in-error documents from search results.§

Replacement

  • Servers SHALL accept relatesTo on create and return it unchanged on read and search.§
  • Servers MAY ignore the replacement relationship in their own processing.§

Provenance

Every document needs to answer a few basic questions: who wrote it, when it was created, and where it came from. This section answers them using "small-p" provenance elements in the DocumentReference itself. Although a separate Provenance resource might not be needed for a simple submission, this section does not replace it or US Core Basic Provenance.

Provenance-bearing Elements

This table maps each provenance question to the DocumentReference element that answers it. The example use cases show these elements together.

Question Element
Who authored the content? author
Who attested to the content? authenticator, R5 attester cross-version extension
Is this patient-asserted? meta.security = PATAST
When was the content created? content.attachment.creation
What period does the content cover? context.period
How does the source system identify the document? identifier
What was this submitted in response to? context.related
What does this supersede? relatesTo
Who is the patient according to the originating system? context.sourcePatientInfo

Server Requirements

  • Servers SHALL persist the submitted Provenance-bearing elements, and return them unchanged on read and search, including elements they don't otherwise process.§
  • Servers SHALL NOT reject a submission solely because a provenance element is absent or cannot be resolved.§
  • Servers SHALL NOT replace a client-supplied author with the authenticated client or user.§
  • Servers MAY populate custodian with the receiving organization when they accept a document.§
  • Servers MAY create a US Core Provenance Profile resource targeting the created DocumentReference.§

Guidance

  • Populating custodian on acceptance is one way a server can meet the existing US Core requirement that every DocumentReference have a responsible organization. See Open Question 1 below.
  • The person or app that submits a document is often not its author. A patient forwarding a discharge summary, for example, is not the hospital that wrote it. Replacing author with the submitter would erase the distinction this section exists to preserve.

Authorization (SMART on FHIR Scopes)

Apps need write permission for DocumentReference. SMART scopes allow access permissions to be delegated to a client application. Servers can grant SMART v2 create/update scopes for DocumentReference or category-specific scopes, and advertise them in /.well-known/smart-configuration.

SMART Scopes

Server Requirements

  • Servers SHALL support the patient/DocumentReference.c or category-specific scopes for Patient Write.§
  • Servers SHALL support the user/DocumentReference.c or category-specific scopes for Provider Write.§
  • Servers SHALL support the system/DocumentReference.c or category-specific scopes for backend services that write documents.§
  • Servers that allow status correction or replacement SHALL support the matching .u scopes.§
  • Servers SHALL list their supported scopes in scopes_supported in /.well-known/smart-configuration.§

Guidance

  • The .u scope covers both the patch and update interactions used for status correction. See Corrections and Replacements.
  • A category-specific scope limits write permission to one category.

    Recommended category-specific scopes

    • Clinical Note
      • <patient|user|system>/DocumentReference.c?category=http://hl7.org/fhir/us/core/CodeSystem/us-core-documentreference-category|clinical-note
      • <patient|user|system>/DocumentReference.u?category=http://hl7.org/fhir/us/core/CodeSystem/us-core-documentreference-category|clinical-note
    • Advance Healthcare Directives
      • <patient|user|system>/DocumentReference.c?category=http://loinc.org|42348-3
      • <patient|user|system>/DocumentReference.u?category=http://loinc.org|42348-3
    • Medical History
      • <patient|user|system>/DocumentReference.c?category=http://hl7.org/fhir/us/core/CodeSystem/us-core-documentreference-category|medical-history
      • <patient|user|system>/DocumentReference.u?category=http://hl7.org/fhir/us/core/CodeSystem/us-core-documentreference-category|medical-history
    • Insurance Document
      • <patient|user|system>/DocumentReference.c?category=http://hl7.org/fhir/us/core/CodeSystem/us-core-documentreference-category|insurance-document
      • <patient|user|system>/DocumentReference.u?category=http://hl7.org/fhir/us/core/CodeSystem/us-core-documentreference-category|insurance-document
    • Identity Document
      • <patient|user|system>/DocumentReference.c?category=http://hl7.org/fhir/us/core/CodeSystem/us-core-documentreference-category|identity-document
      • <patient|user|system>/DocumentReference.u?category=http://hl7.org/fhir/us/core/CodeSystem/us-core-documentreference-category|identity-document

Conformance Requirements

The two tables below list every conformance statement on this page, one table per actor. Each statement is footnoted where it is written on the page with a § marker linking to its row here.

Legend

  • Key - the requirement key, CONF-WD-NN. It is the anchor target of the § footnote marker that follows the statement where it is written on this page.
  • Mode - ALL applies to every submission mode. PROV Provider Write, SPAT Solicited Patient Write, UPAT Unsolicited Patient Write, PAT both patient modes. A statement in a general section is ALL unless it is scoped tighter.
  • Conformance - the RFC 2119 verb as written in the statement.
  • Conditional - ✔ marks a statement with a precondition in its text, for example "when it is held for review". A "-" means the statement applies whenever its mode applies.
  • † - the statement sits in an unresolved block on this page and is not settled.
Client Requirements
Key Mode Conformance Conditional Requirement Section
CONF-WD-09 ALL SHALL -

Clients SHALL populate at least one category and a type on submission.

Document Type and Category
CONF-WD-15 ALL SHALL ✔

Clients SHALL be capable of populating author and context.encounter when they are known.

References: Author and Context.encounter
CONF-WD-16 ALL SHALL ✔

When a Client populates .author or .context.encounter, .reference SHALL be either a relative reference to a resource on the Server or a reference to a contained resource or a logical reference.

References: Author and Context.encounter
CONF-WD-17 ALL SHOULD ✔

When a Client populates .author or .context.encounter, .display SHOULD be populated.

References: Author and Context.encounter
CONF-WD-23 ALL SHALL -

Clients SHALL use context.period to convey the clinically relevant time period.

Date Handling
CONF-WD-24 ALL SHOULD -

Clients SHOULD populate identifier with a value that is unique to the document and stays the same if the document is resubmitted.

Identifier
CONF-WD-29 ALL SHALL ✔

Clients SHALL populate context.related with a relative reference to the ServiceRequest when the document responds to a solicited request.

Context.related
CONF-WD-30 PAT SHALL ✔

Clients SHALL include meta.security with the code PATAST from http://terminology.hl7.org/CodeSystem/v3-ObservationValue when the content is patient-supplied.

Patient-asserted Signaling
CONF-WD-48 SPAT SHALL -

Clients SHALL include meta.security = "PATAST" (Patient asserted).

Solicited Patient Write
CONF-WD-49 SPAT SHALL -

Clients SHALL populate context.related or the FHIR R5 basedOn extension with the active ServiceRequest that requests it.

Solicited Patient Write
CONF-WD-54 UPAT SHALL -

Clients SHALL include meta.security = "PATAST" (Patient asserted).

Unsolicited Patient Write
CONF-WD-55 ALL SHALL ✔

To mark a document as entered in error, clients SHALL use either a patch that changes only status to entered-in-error, or an update that sends the complete resource with only status changed.

Corrections and Replacements
CONF-WD-56 ALL SHOULD ✔

To supersede a document, clients SHOULD create a new DocumentReference with relatesTo.code = replaces and relatesTo.target referencing the original.

Corrections and Replacements
CONF-WD-57 ALL SHALL -

A replacing document SHALL contain the complete revised content, not only the changes.

Corrections and Replacements
CONF-WD-58 ALL SHOULD ✔

Clients SHOULD also populate relatesTo.target.identifier with the original document's identifier when it has one.

Corrections and Replacements
Server Requirements
Key Mode Conformance Conditional Requirement Section
CONF-WD-01 ALL SHALL -

Servers SHALL support create for DocumentReference.

Processing Expectation
CONF-WD-02 ALL SHALL -

Servers SHALL only accept documents that the organization can and intends to process or review.

Processing Expectation
CONF-WD-03 ALL SHALL NOT -

Servers SHALL NOT document support for a DocumentReference category or type that the organization cannot or does not intend to process or review.

Processing Expectation
CONF-WD-04 ALL SHALL ✔

Servers SHALL respond 201 Created with a Location header when the document is available on return.

Processing Expectation
CONF-WD-05 ALL SHALL ✔

Servers SHALL respond 202 Accepted when it is held for review.

Processing Expectation
CONF-WD-06 ALL SHOULD -

Servers SHOULD return an OperationOutcome on failed writes.

Processing Expectation
CONF-WD-07 ALL SHALL -

Servers SHALL publish API documentation covering supported categories and types, MIME types, size limits, $submit-bundle support, and review policy.

Discovery
CONF-WD-08 ALL SHOULD -

Servers SHOULD support ValueSet/$expand with contextDirection=incoming.

Discovery
CONF-WD-10 ALL SHALL -

Servers SHALL publish API documentation covering supported categories and types.

Document Type and Category
CONF-WD-11 ALL SHALL -

Servers SHALL support at least one category.

Document Type and Category
CONF-WD-12 ALL SHALL NOT ✔

Servers SHALL NOT reject a submission with unsupported category codes if it contains at least one category code (as a repeating element) they support.

Document Type and Category
CONF-WD-13 ALL SHALL NOT ✔

Servers SHALL NOT reject a submission with unsupported type codes if it contains at least one code translation they support.

Document Type and Category
CONF-WD-14 ALL SHOULD -

Servers SHOULD preserve the submitted coding(s) as received.

Document Type and Category
CONF-WD-18 ALL SHALL -

Servers SHALL accept both relative references to resources on the server and references to contained resources for author and context.encounter.

References: Author and Context.encounter
CONF-WD-19 ALL SHALL NOT -

Servers SHALL NOT reject a submission solely because an author or context.encounter reference cannot be resolved.

References: Author and Context.encounter
CONF-WD-20 ALL SHOULD -

Servers SHOULD attempt to match author and context.encounter references to existing resources.

References: Author and Context.encounter
CONF-WD-21 ALL MAY -

Servers MAY persist the content of a contained author or Encounter resource.

References: Author and Context.encounter
CONF-WD-22 ALL MAY -

Servers MAY require context.encounter by business rule.

References: Author and Context.encounter
CONF-WD-25 ALL SHOULD -

Servers SHOULD support conditional create (If-None-Exist).

Identifier
CONF-WD-26 ALL MAY -

Servers MAY detect duplicates using identifiers, hashes, or other methods.

Identifier
CONF-WD-31 PAT SHALL NOT -

Servers SHALL NOT remove the PATAST code.

Patient-asserted Signaling
CONF-WD-32 PAT MAY -

Servers MAY add the PATAST code by policy.

Patient-asserted Signaling
CONF-WD-33 ALL SHALL -

Servers SHALL accept at least one of text/plain; charset=utf-8, application/pdf, image/jpeg, or image/png for each supported document type.

MIME Support
CONF-WD-34 ALL SHALL -

Servers SHALL document the MIME types they accept for each supported document type.

MIME Support
CONF-WD-35 ALL SHALL -

Servers SHALL accept inline content.attachment.data whose decoded content is at least 5 MiB (5,242,880 bytes).

Size Limits
CONF-WD-36 ALL SHALL -

Servers SHALL document their attachment size limits.

Size Limits
CONF-WD-37 ALL SHALL NOT -

Servers SHALL NOT expose a client-supplied content.attachment.url to later readers.

Size Limits
CONF-WD-38 ALL MAY -

Servers MAY accept content by content.attachment.url, including content larger than their inline limit.

Size Limits
CONF-WD-39 PROV SHALL -

Scopes: servers SHALL support FHIR RESTful create using <user|system>/DocumentReference.c, or category-specific version(s) such as <user|system>/DocumentReference.c?category=clinical-note.

Provider Write
CONF-WD-40 PROV SHALL -

Servers SHALL make the document available through read and search without further action. The response is always 201.

Provider Write
CONF-WD-41 SPAT SHALL -

Scopes: servers SHALL support patient/DocumentReference.c, or category-specific version(s) such as patient/DocumentReference.c?category=clinical-note.

Solicited Patient Write
CONF-WD-42 SPAT SHALL -

Scopes: servers SHALL support patient/ServiceRequest.rs.

Solicited Patient Write
CONF-WD-43 SPAT SHALL -

Servers SHALL make the ServiceRequest resources with the patient as performer available through read and search.

Solicited Patient Write
CONF-WD-44 SPAT SHALL -

Servers SHALL make the document available through read and search without further action. The response is 201.

Solicited Patient Write
CONF-WD-45 SPAT SHALL NOT -

Servers SHALL NOT remove meta.security = "PATAST".

Solicited Patient Write
CONF-WD-46 SPAT MAY ✔

Servers MAY add meta.security = "PATAST" by policy (for example, based on authorization context), even if it is omitted by the client.

Solicited Patient Write
CONF-WD-47 SPAT SHALL -

Servers SHALL document whether to populate the active ServiceRequest in context.related, or the FHIR R5 basedOn extension.

Solicited Patient Write
CONF-WD-50 UPAT SHALL -

Servers SHALL document their review policy for patient submissions.

Unsolicited Patient Write
CONF-WD-51 UPAT SHALL -

Scopes: servers SHALL support patient/DocumentReference.c, or category-specific version(s) such as patient/us-core-documentreference-category|clinical-note.

Unsolicited Patient Write
CONF-WD-52 UPAT SHALL NOT -

Servers SHALL NOT remove meta.security = "PATAST".

Unsolicited Patient Write
CONF-WD-53 UPAT MAY ✔

Servers MAY add meta.security = "PATAST" by policy (for example, based on authorization context), even if it is omitted by the client.

Unsolicited Patient Write
CONF-WD-59 ALL SHOULD -

Servers SHOULD allow the submitting client to change status to entered-in-error through patch.

Corrections and Replacements
CONF-WD-60 ALL MAY -

Servers MAY allow the submitting client to change status to entered-in-error through update.

Corrections and Replacements
CONF-WD-61 ALL SHALL -

Servers SHALL continue to return an entered-in-error document through read for authorized requests.

Corrections and Replacements
CONF-WD-62 ALL MAY -

Servers MAY exclude entered-in-error documents from search results.

Corrections and Replacements
CONF-WD-63 ALL SHALL -

Servers SHALL accept relatesTo on create and return it unchanged on read and search.

Corrections and Replacements
CONF-WD-64 ALL MAY -

Servers MAY ignore the replacement relationship in their own processing.

Corrections and Replacements
CONF-WD-65 ALL SHALL -

Servers SHALL persist the submitted Provenance-bearing elements, and return them unchanged on read and search, including elements they don't otherwise process.

Provenance-bearing Elements
CONF-WD-66 ALL SHALL NOT -

Servers SHALL NOT reject a submission solely because a provenance element is absent or cannot be resolved.

Provenance-bearing Elements
CONF-WD-67 ALL SHALL NOT -

Servers SHALL NOT replace a client-supplied author with the authenticated client or user.

Provenance-bearing Elements
CONF-WD-68 ALL MAY ✔

Servers MAY populate custodian with the receiving organization when they accept a document.

Provenance-bearing Elements
CONF-WD-69 ALL MAY -

Servers MAY create a US Core Provenance Profile resource targeting the created DocumentReference.

Provenance-bearing Elements
CONF-WD-70 ALL SHALL -

Servers SHALL support the patient/DocumentReference.c or category-specific scopes for Patient Write.

SMART Scopes
CONF-WD-71 ALL SHALL -

Servers SHALL support the user/DocumentReference.c or category-specific scopes for Provider Write.

SMART Scopes
CONF-WD-72 ALL SHALL -

Servers SHALL support the system/DocumentReference.c or category-specific scopes for backend services that write documents.

SMART Scopes
CONF-WD-73 ALL SHALL ✔

Servers that allow status correction or replacement SHALL support the matching .u scopes.

SMART Scopes
CONF-WD-74 ALL SHALL -

Servers SHALL list their supported scopes in scopes_supported in /.well-known/smart-configuration.

SMART Scopes
CONF-WD-75 ALL SHOULD -

Servers SHOULD accept logical references for author and context.encounter.

References: Author and Context.encounter

Open Questions

The following items are unresolved.

  1. How to meet US Core's DocumentReference "responsible-organization requirement"?

    The US Core DocumentReference guidance requires that every DocumentReference have a responsible Organization, present either in DocumentReference.custodian or in a Provenance resource targeting the document. For patient-generated and patient-mediated writes there is no responsible organization at the time of submission.

  2. When is discovery needed?

    If pre-coordination is required, runtime discovery adds machinery without removing the coordination step.

  3. What about per-organization discovery versus network-level requirements?

  4. What are the DocumentReference categories candidates?

  5. Is there a need for a separate DocumentReference write profile?