---
description: >-
  Columns for documents and diagnostic_reports, mapped from the USCDI v3.1
  Clinical Notes data class to US Core 6.1.0 FHIR.
---

> For the complete documentation index, see [llms.txt](https://www.health-samurai.io/docs/payerbox/llms.txt).
> Use it to discover all available pages before guessing URLs.

---

# Clinical Notes

## Datasets

[US Core 6.1.0](https://hl7.org/fhir/us/core/STU6.1/) maps each [USCDI](https://isp.healthit.gov/united-states-core-data-interoperability-uscdi#uscdi-v3-1) data element onto a FHIR element.

| Dataset | US Core 6.1.0 target profile(s) |
|---|---|
| [`documents`](#documents) | [US Core DocumentReference](https://hl7.org/fhir/us/core/STU6.1/StructureDefinition-us-core-documentreference.html) |
| [`diagnostic_reports`](#diagnostic-reports) | [US Core DiagnosticReport Lab](https://hl7.org/fhir/us/core/STU6.1/StructureDefinition-us-core-diagnosticreport-lab.html), [US Core DiagnosticReport Note](https://hl7.org/fhir/us/core/STU6.1/StructureDefinition-us-core-diagnosticreport-note.html) |

Notes and reports are the one part of the feed that is not only CSV: the document itself travels as a file in the delivery, and the CSV row points at it.

```
delivery-2026-08-19/
  csv/
    documents.csv
    diagnostic_reports.csv
  attachments/
    DOC-0001.pdf
    DR-0771.pdf
```

`attachment_file` holds the path relative to the delivery root. The folder name and nesting are yours to choose. Put no patient details in file or folder names.

## documents

One row per note. The note itself is the file; this row is its index card.

{% file src="../../assets/data-integration/documents.csv" %}
documents.csv Data template with example rows
{% endfile %}

| Column | Required | Format / values | Example |
|---|---|---|---|
| `patient_identifier` | Yes | patient key | `MRN-4471903` |
| `type_code` | Yes | LOINC note type, e.g. `11488-4` consult, `18842-5` discharge summary, `34117-2` history and physical, `11506-3` progress note [US Core DocumentReference Type](https://healthsamurai.github.io/fhir-valueset-viewer/#url=http://hl7.org/fhir/us/core/ValueSet/us-core-documentreference-type) | `11488-4` |
| `attachment_file` | Yes | path relative to the delivery root | `attachments/DOC-0001.pdf` |
| `record_id` | Recommended | your stable row key | `DOC-0001` |
| `document_date` | Recommended | datetime | `2026-04-18T10:00:00-04:00` |
| `author_npi` | Recommended | 10 digits | `1407006835` |
| `encounter_id` | If applicable | `encounters` key | `ENC-9912` |

- `type_code` has a required binding, so the note type must come from that value set. It is large, but the four codes above cover most of what a payer holds.
- `record_id` is the upsert key. It is optional on this dataset alone, defaulting to `attachment_file` — so send it if your filenames change between exports, or a renamed file becomes a second note.
- Payerbox sets the status to `current` and the category to `clinical-note`, and reads the attachment's content type and size from the stored file. None of those are columns.

## diagnostic_reports

One row per report. The individual results live in `labs` and `clinical_observations` and point back with `diagnostic_report_id`.

{% file src="../../assets/data-integration/diagnostic_reports.csv" %}
diagnostic_reports.csv Data template with example rows
{% endfile %}

| Column | Required | Format / values | Example |
|---|---|---|---|
| `report_id` | Yes | stable key; the key result rows reference | `DR-771` |
| `patient_identifier` | Yes | patient key | `MRN-4471903` |
| `report_kind` | Yes | `lab` or `note` | `lab` |
| `status` | Yes | `registered`, `partial`, `preliminary`, `final`, `amended`, `corrected`, `appended`, `cancelled`, `entered-in-error`, `unknown` [diagnostic-report-status](https://healthsamurai.github.io/fhir-valueset-viewer/#url=http://hl7.org/fhir/ValueSet/diagnostic-report-status%7C4.0.1) | `final` |
| `code` | Yes | LOINC, from the value set the `report_kind` profile binds, with `code_system` | `24323-8` lab, `39053-4` note |
| `category_code` | Recommended | `LAB`, `RAD` and the other v2-0074 service sections | `LAB` |
| `effective_datetime` | Recommended | datetime | `2026-04-18T08:40:00-04:00` |
| `issued` | If available | datetime | `2026-04-18T12:00:00-04:00` |
| `performer_npi` | If available | 10 digits | `1234567893` |
| `attachment_file` | If available | path relative to the delivery root | `attachments/DR-0771.pdf` |
| `encounter_id` | If applicable | `encounters` key | `ENC-9912` |

- `report_kind` picks the profile: `lab` for a laboratory report, `note` for everything else, including radiology and pathology narratives. The two bind `code` to different value sets, so a lab code on a `note` row is rejected and the reverse too. A wrong `report_kind` is not cosmetic.
- `attachment_file` carries the narrative report as a file, the same way `documents` does. A lab report with structured results and no narrative needs none.
- This dataset also serves the Laboratory and Diagnostic Imaging data classes, not only Clinical Notes.

These resources are served by [Patient Access](../../interop-apis/patient-access.md), [Provider Access](../../interop-apis/provider-access.md), [Payer-to-Payer](../../interop-apis/payer-to-payer.md), and [Prior Auth](../../prior-auth/README.md).