Skip to main content

DocumentReference

Overview​

The DocumentReference resource provides references to documents of any kind and metadata to enable document discovery and management. This resource supports clinical document workflows and document sharing.

Important: Always validate DocumentReference resource support and available operations by retrieving the current CapabilityStatement from /metadata before implementing integrations.

Resource Schema​

The DocumentReference resource follows the HL7 FHIR R4 DocumentReference specification.

Key elements include:

  • masterIdentifier - Master version specific identifier
  • identifier - Other identifiers for the document
  • status - Current, superseded, entered-in-error
  • docStatus - Preliminary, final, amended, entered-in-error
  • type - Kind of document (LOINC if possible)
  • category - Categorization of document
  • subject - Who/what is the subject of the document
  • date - When this document reference was created
  • author - Who and/or what authored the document
  • authenticator - Who/what authenticated the document
  • custodian - Organization which maintains the document
  • relatesTo - Relationships to other documents
  • description - Human-readable description
  • securityLabel - Document security-tags
  • content - Document referenced
  • context - Clinical context of document

Example DocumentReference Resource​

{
  "resourceType": "DocumentReference",
  "id": "12345",
  "masterIdentifier": {
    "system": "http://hospital.example.org/documents",
    "value": "DOC-2024-001"
  },
  "status": "current",
  "docStatus": "final",
  "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/12345"
  },
  "date": "2024-01-15T14:30:00Z",
  "author": [{
    "reference": "Practitioner/67890",
    "display": "Dr. John Smith"
  }],
  "authenticator": {
    "reference": "Practitioner/67890"
  },
  "custodian": {
    "reference": "Organization/hospital-123"
  },
  "description": "Discharge summary for patient admission",
  "content": [{
    "attachment": {
      "contentType": "application/pdf",
      "language": "en-US",
      "url": "Binary/document-pdf-123",
      "size": 104274,
      "hash": "SGVsbG8gV29ybGQ=",
      "title": "Discharge Summary - John Doe",
      "creation": "2024-01-15T14:30:00Z"
    },
    "format": {
      "system": "http://ihe.net/fhir/ValueSet/IHE.FormatCode.codesystem",
      "code": "urn:ihe:pcc:xphr:2007",
      "display": "Personal Health Records"
    }
  }],
  "context": {
    "encounter": [{
      "reference": "Encounter/67890"
    }],
    "period": {
      "start": "2024-01-10T08:00:00Z",
      "end": "2024-01-15T14:30:00Z"
    },
    "facilityType": {
      "coding": [{
        "system": "http://snomed.info/sct",
        "code": "22232009",
        "display": "Hospital"
      }]
    }
  }
}

Supported Profiles​

This API supports the following FHIR profiles:

Operations​

The General Purpose API DocumentReference resources supports the following standard operations. However, support varies by the targeted CareRecord or solution.

CareRecord / SolutionCreateReadUpdateSearch
GEHRIMED-Yes-Yes
myAvatar-Yes-Yes
myEvolv-Yes-Yes
myUnity-Yes-Yes
Referral ManagerYes-Yes-
info

Not all Netsmart solutions support DocumentReference search. See supported operations table above and consult your target solution's documentation for more information.

This operation retrieves a list of resources by these query parameters.

Standard Parameters​

NameTypeDescription
authenticatorreferenceWho/what authenticated the document.
authorreferenceWho and/or what authored the document.
custodianreferenceOrganization which maintains the document.
patientreferenceREQUIRED Who/what is the subject of the document. Not required when searching by _id.
perioddateThe time of service that is being documented.
typetokenKind of document (LOINC if possible).
_ididUnique identifier of the DocumentReference. Cannot be used with other search parameters.

Search Examples​

Via POST​

The POST method is recommended as it keeps health information out of the URL.

Search by Patient and Type
curl -X POST https://fhir.netsmartcloud.com/v4/DocumentReference/_search \
    -H "Authorization: {Bearer Token}" \
    -H "Accept: application/fhir+json" \
    -d "patient=Patient/123" \
    -d "type=http://loinc.org|18842-5"

Via GET​

Search by Patient and Type
curl -X GET "https://fhir.netsmartcloud.com/uscore/v1/DocumentReference?patient=Patient/123&type=http://loinc.org%7C18748-4" \
    -H "Authorization: {Bearer Token}" \
    -H "Accept: application/fhir+json"

Generate an Ad-hoc CDA​

Disclaimer

This customization is expected to be replaced with an extended operation in future API versions.

This resource has been customized the search to allow for the generation of an ad-hoc CDA document similar to our CCD API.

This functionality is initiated by using one of our CCD API documentType values in type search parameter.

Supported CDA Types​

The following CDA document types are currently supported by this API.

Typetype ParameterNote
Consultation NoteConsultationNote
Continuity of Care DocumentCCD
Discharge SummaryDischargeSummary
Electronic Initial Case ReportEICR
Emergency Healthcare SurveyEmergencyHealthcareSurvey
History and Physical NoteHistoryAndPhysicalNote
Inpatient Healthcare SurveyInpatientHealthcareSurvey
Outpatient Healthcare SurveyOutpatientHealthcareSurvey
Progress NoteProgressNoteDoc
Public Health Case ReportPublicHealthCaseReport
Referral NoteReferralNote
Transfer of CareTransferOfCareReserved for future use. This document type is not available currently.
Unstructured DocumentUnstructuredDocument

Parameters​

The following search parameters are used to generate the CDA. All other search parameters passed are ignored.

NameTypeDescription
patientreferenceREQUIRED Who/what is the subject of the document.
perioddateThe time of service that is being documented.
typetokenCCD | ConsultationNote | DischargeSummary | EICR | EmergencyHealthcareSurvey | HistoryAndPhysicalNote | InpatientHealthcareSurvey | OutpatientHealthcareSurvey | ProgressNoteDoc | PublicHealthCaseReport | ReferralNote | TransferOfCare | UnstructuredDocument
REQUIRED The type of CDA.

Examples​

The following examples show how to use the search parameters to generate a CDA.

Via POST​

The POST method is recommended as it keeps health information out of the URL.

Generate a CCD by Patient, Type, and Period
curl -X POST https://fhir.netsmartcloud.com/v4/DocumentReference/_search \
    -H "Authorization: {Bearer Token}" \
    -H "Accept: application/fhir+json" \
    -H "Content-Type: application/x-form-urlencoded" \
    -d "patient=Patient/123" \
    -d "type=CCD" \
    -d "period=ge2023-07-01" \
    -d "period=le2023-07-31"

Via GET​

Search by Patient and Type
curl -X GET "https://fhir.netsmartcloud.com/uscore/v1/DocumentReference?patient=Patient/123&type=CCD&period=ge2023-07-01&period=ge2023-07-31" \
    -H "Authorization: {Bearer Token}" \
    -H "Accept: application/fhir+json"

Error Handling​

For information about error responses when working with DocumentReference resources, see Common Errors.

Common DocumentReference-related errors include:

  • Missing required patient reference
  • Invalid document type or LOINC codes
  • Malformed document dates or periods
  • Invalid author or custodian references

Integration Patterns​

Document Discovery​

Find documents for patients:

# Get all documents for patient
curl -X GET "https://fhir.netsmartcloud.com/v4/DocumentReference?patient=12345" \
    -H "Authorization: Bearer {token}" \
    -H "Accept: application/fhir+json"

Clinical Document Generation​

Generate CDA documents:

# Generate CCD document
curl -X GET "https://fhir.netsmartcloud.com/v4/DocumentReference?patient=12345&type=CCD&period=ge2024-01-01" \
    -H "Authorization: Bearer {token}" \
    -H "Accept: application/fhir+json"

Document Type Filtering​

Filter by document types:

# Get discharge summaries
curl -X GET "https://fhir.netsmartcloud.com/v4/DocumentReference?patient=12345&type=http://loinc.org|18842-5" \
    -H "Authorization: Bearer {token}" \
    -H "Accept: application/fhir+json"

Relationships to Other Resources​

The DocumentReference resource connects to many clinical and administrative resources:

Support​

For questions about DocumentReference resource implementation or clinical document workflows, contact Netsmart support through your designated support channels.