Skip to main content

Resource $csv

The $csv operation exports FHIR resources as a CSV (Comma-Separated Values) file, which is useful for exporting data for analysis in spreadsheet applications, reporting tools, or data pipelines.

Use Cases​

  • Reporting: Generate reports for administrative or clinical purposes
  • Data Analysis: Export data for analysis in Excel, Google Sheets, or BI tools
  • Data Migration: Export data for import into other systems
  • Auditing: Create snapshots of data for audit purposes

Invoke the $csv operation​

[base]/[resourceType]/$csv?_fields=[field1,field2,...]&[search parameters]

For example, to export Patient data:

curl 'https://api.medplum.com/fhir/R4/Patient/$csv?_fields=name,birthDate,gender,address' \
  -H "Authorization: Bearer MY_ACCESS_TOKEN" \
  -o patients.csv

Parameters​

NameTypeDescriptionRequired
_fieldsstringComma-separated list of fields/search parameters to exportYes
anystringAny valid search parameters for the resource typeNo

Fields Parameter​

The _fields parameter accepts:

  • Search parameter names - These are resolved to their FHIRPath expressions
  • FHIRPath expressions - Direct FHIRPath expressions for custom field extraction

Example Field Configurations​

_fields=name,birthDate,gender
_fields=identifier,name,telecom,address
_fields=Patient.name.family,Patient.name.given

Output​

The operation returns a CSV file with:

  • UTF-8 encoding with BOM (Byte Order Marker) for Excel compatibility
  • Header row with column names
  • One row per resource
  • Automatic formatting for complex FHIR types

Supported Data Type Formatting​

FHIR TypeCSV Output
HumanNameFormatted full name
AddressFormatted address string
ContactPointThe value field (phone, email, etc.)
ReferenceThe display field
CodeableConceptDisplay text or first coding display/code
stringDirect value
numberDirect value
boolean"true" or "false"

Examples​

Export All Patients​

curl 'https://api.medplum.com/fhir/R4/Patient/$csv?_fields=name,birthDate,gender,address' \
  -H "Authorization: Bearer MY_ACCESS_TOKEN" \
  -o all-patients.csv

Export Filtered Results​

Export only active patients:

curl 'https://api.medplum.com/fhir/R4/Patient/$csv?_fields=name,birthDate,gender&active=true' \
  -H "Authorization: Bearer MY_ACCESS_TOKEN" \
  -o active-patients.csv

Export Observations​

Export vital signs observations:

curl 'https://api.medplum.com/fhir/R4/Observation/$csv?_fields=code,value-quantity,effective-date-time,subject&category=vital-signs' \
  -H "Authorization: Bearer MY_ACCESS_TOKEN" \
  -o vitals.csv

Export with Custom FHIRPath​

curl 'https://api.medplum.com/fhir/R4/Patient/$csv?_fields=name.family,name.given,telecom.where(system=%27phone%27).value' \
  -H "Authorization: Bearer MY_ACCESS_TOKEN" \
  -o patients-custom.csv

Response Headers​

Content-Type: text/csv
Content-Disposition: attachment; filename=export.csv

Limitations​

  • Maximum 1000 resources per export
  • For larger exports, use the Bulk FHIR operations
  • Only the first value is exported for multi-valued fields

Error Responses​

Missing Fields Parameter​

{
  "resourceType": "OperationOutcome",
  "issue": [
    {
      "severity": "error",
      "code": "invalid",
      "details": {
        "text": "Missing _fields parameter"
      }
    }
  ]
}

Invalid Resource Type​

{
  "resourceType": "OperationOutcome",
  "issue": [
    {
      "severity": "error",
      "code": "invalid",
      "details": {
        "text": "Unsupported resource type"
      }
    }
  ]
}

Security​

The operation includes CSV injection protection by escaping potentially dangerous characters (=, +, -, @) at the start of cell values.