Flexpa
Developer PortalFeedbackContact usSandbox

All docs

Schema

  • Overview

C-CDA Documents

  • Overview
  • Reading Content
  • Decoding and Parsing

API

  • GETRead
  • GETSearch

DocumentReference

DocumentReference is a FHIR resource that provides metadata about a document so it can be discovered and managed. The document can be any type, but clinical documents are particularly common, including C-CDA (Consolidated Clinical Document Architecture) documents.

C-CDA documents are structured clinical documents that contain comprehensive patient health information including problems, medications, allergies, procedures, vital signs, social history, and more. These documents are commonly exchanged between healthcare providers and are increasingly available through nationwide health information exchange networks.

While DocumentReference resources have historically been uncommon in payer APIs, they are becoming more prevalent through:

  • Nationwide Health Information Exchange - Networks enabling payers to access clinical documents from providers
  • Provider-Payer Data Exchange - Clinical documentation submitted for quality measures, prior authorization, or care coordination
  • Clinical Data Registries - Aggregated clinical information from various sources

The DocumentReference resource provides metadata about the document, including its type, author, date, and how to retrieve the actual document content. Documents are typically available in formats like:

  • C-CDA (XML) - Structured clinical documents following HL7 CDA standard
  • HTML - Human-readable clinical notes
  • PDF - Scanned or formatted clinical documents
  • Plain text - Unstructured clinical notes

This reference explains the key elements of DocumentReference resources and how to access clinical documents through the Flexpa API. Data types used in this reference are defined in the FHIR R4 Data Types specification.

FHIR API

https://api.flexpa.com/fhir/DocumentReference

New to FHIR?

Intro to FHIR

FHIR, or Fast Healthcare Interoperability Resources, is a standard for exchanging healthcare information electronically
Read introduction →

Looking for clinical data?

C-CDA documents accessed through nationwide exchange networks provide the most comprehensive clinical information available through payer APIs, including detailed provider documentation not found in claims data.

#Schema

#Overview

The FHIR R4 DocumentReference resource provides metadata about a document so it can be discovered and managed. As a FHIR resource, it follows standard FHIR patterns with common elements like resourceType, id, meta, and identifier.

DocumentReference resources are typically compliant with the US Core DocumentReference Profile, which defines specific requirements for clinical notes and documents.

The resource contains two main types of information: metadata elements that describe the document (type, author, date) and content elements that provide access to the actual document data.

Elements

metaMeta

Metadata about the resource. See also Tags defined by Flexpa.

lastUpdatedinstant

The last time the document metadata was updated

identifierIdentifier

Business identifiers assigned to the document

systemuri

The namespace for the identifier value

valuestring

The unique identifier value

statuscode

The status of the document reference

Codes
current
This is the current reference for this document
superseded
This reference has been superseded by another reference
entered-in-error
This reference was created in error
typeCodeableConcept

The type of document being referenced

Systemhttp://loinc.org
LOINC codes for document types
Example Codes
34109-9
Miscellaneous Notes
11488-4
Consultation Notes
18842-5
Discharge Summary
11506-3
Progress Notes
34133-9
Summarization of Episode Note
categoryCodeableConcept

High-level categorization of the document

Systemhttp://hl7.org/fhir/us/core/CodeSystem/us-core-documentreference-category
US Core DocumentReference Category Codes
Codes
clinical-note
Clinical notes and documentation
subjectReference(Patient)

Reference to the Patient who is the subject of the document

dateinstant

When the document reference was created or when the document was authored

authorarray

Who and/or what authored the document

identifierIdentifier

Identifier for the author (e.g., NPI number)

systemuri

The identifier system, commonly http://hl7.org/fhir/sid/us-npi for NPI numbers

valuestring

The identifier value

displaystring

Text representation of the author's name

contentarray

The document and format details

attachmentAttachment

The document content

contentTypecode

MIME type of the content - commonly text/html, text/xml, application/xml, application/pdf, or text/plain

database64Binary

Base64-encoded document data - when present, contains the actual document content

urlurl

URI where the document can be retrieved - alternative to inline data

formatCoding

Format/content standard of the document

Systemhttp://ihe.net/fhir/ValueSet/IHE.FormatCode.codesystem
IHE Format Codes
Example Codes
urn:ihe:iti:xds:2017:mimeTypeSufficient
Format specified by MIME type
Codes
cda
Clinical Document Architecture (C-CDA) - commonly used for nationwide exchange
contextBackboneElement

Clinical context of the document

encounterReference(Encounter)

Context of the document content - reference to the Encounter associated with the document

periodPeriod

Time period covered by the documentation

DocumentReference Example

{
  "resourceType": "DocumentReference",
  "id": "73747034db32edf9ab1bfbdbe0b05f764ec8c1c51874b159cd8e82e286c0becf",
  "meta": {
    "versionId": "43",
    "lastUpdated": "2021-06-23T08:30:07.826+00:00",
    "source": "https://fhir.example.com/documentation/glossary/DataSource",
    "tag": [
      {
        "system": "https://www.hl7.org/fhir/patient.html",
        "code": "Patient/example-patient-id"
      },
      {
        "system": "https://fhir.example.com/documentation/glossary/lastRefreshedOn",
        "code": "2021-06-23T08:30:07.629Z"
      }
    ]
  },
  "status": "current",
  "type": {
    "coding": [
      {
        "system": "http://loinc.org",
        "code": "34109-9",
        "display": "Misc Notes"
      },
      {
        "system": "http://loinc.org",
        "code": "11506-3",
        "display": "Progress Notes"
      }
    ]
  },
  "category": [
    {
      "coding": [
        {
          "system": "http://hl7.org/fhir/us/core/CodeSystem/us-core-documentreference-category",
          "code": "clinical-note"
        }
      ],
      "text": "Clinical Note"
    }
  ],
  "subject": {
    "reference": "Patient/example-patient-id"
  },
  "date": "2021-01-18T00:54:34.949+00:00",
  "author": [
    {
      "identifier": {
        "system": "http://hl7.org/fhir/sid/us-npi",
        "value": "1720081417"
      },
      "display": "RICHARD YOUNG, DPM"
    }
  ],
  "content": [
    {
      "attachment": {
        "contentType": "text/xml",
        "data": "PENsaW5pY2FsRG9jdW1lbnQgeG1sbnM9InVybjpobDctb3JnOnYzIj4KICA8dGl0bGU+UHJvZ3Jlc3MgTm90ZTwvdGl0bGU+CiAgPCEtLSBDLUNEQSBjb250ZW50IGhlcmUgLS0+CjwvQ2xpbmljYWxEb2N1bWVudD4="
      },
      "format": {
        "system": "http://ihe.net/fhir/ValueSet/IHE.FormatCode.codesystem",
        "code": "urn:hl7-org:sdwg:ccda-structuredBody:2.1",
        "display": "C-CDA Structured Body"
      }
    }
  ],
  "context": {
    "period": {
      "start": "2021-01-18",
      "end": "2021-01-18"
    }
  }
}

#C-CDA Documents

#Overview

C-CDA (Consolidated Clinical Document Architecture) is an XML-based standard for clinical document exchange. When accessed through nationwide health information exchange networks, C-CDA documents provide comprehensive clinical information that is not available in traditional claims data.

C-CDA documents typically include structured sections for:

  • Problems/Diagnoses - Active and historical conditions with onset dates and status
  • Medications - Current and historical medications with dosing, frequency, and duration
  • Allergies and Intolerances - Documented allergies with severity and reactions
  • Procedures - Surgical and diagnostic procedures with dates and providers
  • Vital Signs - Blood pressure, heart rate, temperature, weight, height
  • Laboratory Results - Test results with reference ranges and interpretations
  • Immunizations - Vaccination history with dates and vaccine information
  • Social History - Smoking status, alcohol use, and other social determinants
  • Clinical Notes - Unstructured provider documentation and assessments

#Reading Content

The actual document content is provided in the content[].attachment element. Documents can be delivered in two ways:

  1. Inline Data - Base64-encoded content in the data element
  2. URL Reference - A URL in the url element where the document can be fetched

For C-CDA documents, the contentType is typically text/xml or application/xml, and the format element indicates the C-CDA version and profile.

#Decoding and Parsing

When document data is base64-encoded:

// Decode base64 document data
const documentData = atob(resource.content[0].attachment.data);

// For C-CDA XML documents, parse with XML parser
const parser = new DOMParser();
const xmlDoc = parser.parseFromString(documentData, "text/xml");

// Extract structured data from C-CDA sections
const medications = xmlDoc.getElementsByTagName("medication");
const problems = xmlDoc.getElementsByTagName("problem");

C-CDA Document Example

<?xml version="1.0" encoding="UTF-8"?>
<ClinicalDocument xmlns="urn:hl7-org:v3">
  <realmCode code="US"/>
  <typeId root="2.16.840.1.113883.1.3" extension="POCD_HD000040"/>
  <templateId root="2.16.840.1.113883.10.20.22.1.1" extension="2015-08-01"/>
  <id root="2.16.840.1.113883.19.5.99999.1"/>
  <code code="34133-9" codeSystem="2.16.840.1.113883.6.1"
        displayName="Summarization of Episode Note"/>
  <title>Continuity of Care Document</title>
  <effectiveTime value="20210118005434"/>

  <recordTarget>
    <patientRole>
      <id extension="12345" root="2.16.840.1.113883.19.5.99999.2"/>
      <patient>
        <name>
          <given>John</given>
          <family>Doe</family>
        </name>
        <birthTime value="19800101"/>
      </patient>
    </patientRole>
  </recordTarget>

  <component>
    <structuredBody>
      <!-- Problems Section -->
      <component>
        <section>
          <templateId root="2.16.840.1.113883.10.20.22.2.5.1"/>
          <code code="11450-4" codeSystem="2.16.840.1.113883.6.1"
                displayName="Problem List"/>
          <title>Problems</title>
          <text>
            <list>
              <item>Type 2 Diabetes Mellitus</item>
              <item>Hypertension</item>
            </list>
          </text>
          <entry>
            <observation classCode="OBS" moodCode="EVN">
              <code code="55607006" codeSystem="2.16.840.1.113883.6.96"
                    displayName="Problem"/>
              <value xsi:type="CD" code="44054006"
                     codeSystem="2.16.840.1.113883.6.96"
                     displayName="Type 2 Diabetes Mellitus"/>
            </observation>
          </entry>
        </section>
      </component>

      <!-- Medications Section -->
      <component>
        <section>
          <templateId root="2.16.840.1.113883.10.20.22.2.1.1"/>
          <code code="10160-0" codeSystem="2.16.840.1.113883.6.1"
                displayName="Medication List"/>
          <title>Medications</title>
          <text>
            <list>
              <item>Metformin 500mg twice daily</item>
              <item>Lisinopril 10mg once daily</item>
            </list>
          </text>
        </section>
      </component>
    </structuredBody>
  </component>
</ClinicalDocument>

#API

GEThttps://api.flexpa.com/fhir/DocumentReference/:id

#Read

A read is the most basic operation in FHIR. It allows you to retrieve the current version of a single resource by its ID.

For a full list of available Resources, please refer to the FHIR Resources documentation.

Request headers

AuthorizationstringRequired

An Authorization: Bearer header value must presented with a Patient Access Token or an Application Access Token

Request path parameters

identifierstring

The identifier of the resource to be retrieved - used in the last part of the URL path segment

Error codes

transient429 status code

The API is expected to return a 429 status code until the data is ready to be retrieved. This error is returned by the API while in the initial sync period, which typically lasts less than 1 minute.

You will need to implement retry logic to handle this error. If you are using the Node SDK which we demonstrate in our Quickstart guide, retry logic is already built in and you don't need to implement it yourself.

processing422 status code
The API is expected to return a 422 when Flexpa fails to synchronize any resources from the payer for the requested Patient. Please re-authorize or reach out to support.

Request

GET
/fhir/DocumentReference/:id
ACCESS_TOKEN=flexpa-link-access-token

curl https://api.flexpa.com/fhir/DocumentReference/73747034db32edf9ab1bfbdbe0b05f764ec8c1c51874b159cd8e82e286c0becf \
  -H "Authorization: Bearer $ACCESS_TOKEN"
GEThttps://api.flexpa.com/fhir/DocumentReference

#Search

Searches on Flexpa API follow the RESTful style of the FHIR specification by submitting a GET HTTP request to the base URL of the resource with parameters to define the exact search criteria to filter the response.

Request headers

AuthorizationstringRequired

An Authorization: Bearer header value must presented with a Patient Access Token or an Application Access Token

Search parameters

Flexpa supports all DocumentReference SearchParameter values defined in the FHIR R4 specification

patientreference

The patient the document is about - recommended to use with the $PATIENT_ID wildcard

typetoken

Kind of document (LOINC code for document type)

categorytoken

Categorization of document (e.g., clinical-note)

datedate

When the document reference was created

perioddate

Time period covered by the documentation

authorreference

Who and/or what authored the document

statustoken

Current status of the document reference (current, superseded, entered-in-error)

contenttypetoken

MIME type of the document content

Error codes

transient429 status code

The API is expected to return a 429 status code until the data is ready to be retrieved. This error is returned by the API while in the initial sync period, which typically lasts less than 1 minute.

You will need to implement retry logic to handle this error. If you are using the Node SDK which we demonstrate in our Quickstart guide, retry logic is already built in and you don't need to implement it yourself.

processing422 status code
The API is expected to return a 422 when Flexpa fails to synchronize any resources from the payer for the requested Patient. Please re-authorize or reach out to support.

Request

GET
/fhir/DocumentReference
ACCESS_TOKEN=flexpa-link-access-token

curl "https://api.flexpa.com/fhir/DocumentReference?patient=$PATIENT_ID" \
  -H "Authorization: Bearer $ACCESS_TOKEN"
Status TwitterGitHub

© 2025 Flexpa. All rights reserved.