Skip to main content

Group Export Operation

Overview​

The Group Export Operation initiates bulk data export for all patients within a specified Group. This operation follows the FHIR Bulk Data Access IG specification for asynchronous export processing.

Operation: GET /Group/{id}/$export

Key Use Cases:

  • Export patient data for population health analytics
  • Generate datasets for research and quality improvement
  • Support regulatory reporting requirements
  • Enable data migration and backup operations

Important: Always verify supported parameters by checking the CapabilityStatement before implementation.

Parameters​

Note: Available parameters are defined in the CapabilityStatement. Always verify current parameters and their support before implementation.

NameTypeRequiredDescription
_outputFormatstringNoFormat for exported files. Default: application/fhir+ndjson
_sinceinstantNoOnly include resources modified after this timestamp
_typestringNoComma-separated list of resource types to export

Parameter Details​

_outputFormat​

  • Default: application/fhir+ndjson
  • Supported formats: Verify in CapabilityStatement
  • Common values: application/fhir+ndjson, application/ndjson, ndjson

_since​

  • Format: FHIR instant (ISO 8601)
  • Example: 2024-01-01T00:00:00Z
  • Behavior: Includes resources modified after specified time

_type​

  • Format: Comma-separated resource type names
  • Example: Patient,Observation,Condition
  • Default: All supported resources within authorization scope

Examples​

Basic Export​

Initiate Group Export
curl -X GET "https://fhir.netsmartcloud.com/uscore/v1/bulk-data/Group/example-group/\$export" \
    -H "Authorization: Bearer {access_token}" \
    -H "Accept: application/fhir+json" \
    -H "Prefer: respond-async"

Export with Parameters​

Export Specific Resource Types
curl -X GET "https://fhir.netsmartcloud.com/uscore/v1/bulk-data/Group/example-group/\$export?_type=Patient,Observation,Condition" \
    -H "Authorization: Bearer {access_token}" \
    -H "Accept: application/fhir+json" \
    -H "Prefer: respond-async"
Export Since Date
curl -X GET "https://fhir.netsmartcloud.com/uscore/v1/bulk-data/Group/example-group/\$export?_since=2024-01-01T00:00:00Z" \
    -H "Authorization: Bearer {access_token}" \
    -H "Accept: application/fhir+json" \
    -H "Prefer: respond-async"
Export with Multiple Parameters
curl -X GET "https://fhir.netsmartcloud.com/uscore/v1/bulk-data/Group/example-group/\$export?_type=Patient,Observation&_since=2024-01-01T00:00:00Z&_outputFormat=application/fhir+ndjson" \
    -H "Authorization: Bearer {access_token}" \
    -H "Accept: application/fhir+json" \
    -H "Prefer: respond-async"

Response Examples​

Successful Export Request​

Export Accepted
HTTP/2 202 Accepted
Content-Location: https://fhir.netsmartcloud.com/uscore/v1/bulk-data/$export-poll-status?_id=abc123
Content-Type: application/fhir+json

{
  "resourceType": "OperationOutcome",
  "issue": [{
    "severity": "information",
    "code": "informational",
    "diagnostics": "Export request accepted. Use Content-Location header to check status."
  }]
}

Error Responses​

Invalid Group ID
HTTP/2 404 Not Found
Content-Type: application/fhir+json

{
  "resourceType": "OperationOutcome",
  "issue": [{
    "severity": "error",
    "code": "not-found",
    "diagnostics": "Group resource not found or not accessible"
  }]
}
Invalid Parameters
HTTP/2 400 Bad Request
Content-Type: application/fhir+json

{
  "resourceType": "OperationOutcome",
  "issue": [{
    "severity": "error",
    "code": "processing",
    "diagnostics": "Unsupported resource type in _type parameter"
  }]
}

Integration Patterns​

Complete Export Workflow​

# Step 1: Initiate export
GET /Group/{id}/$export
# Response: 202 Accepted with Content-Location header

# Step 2: Extract status URL from Content-Location header
# Example: https://fhir.netsmartcloud.com/uscore/v1/bulk-data/$export-poll-status?_id=abc123

# Step 3: Poll for completion
GET /$export-poll-status?_id=abc123
# Response: 202 (in progress) or 200 (complete with file manifest)

# Step 4: Download files when complete
GET /Binary/{file-id}/$binary-access-read

Common Export Patterns​

Population Health Export:

# Export all available data for a patient population
GET /Group/diabetes-patients/$export

Incremental Export:

# Export only data modified since last export
GET /Group/care-program/$export?_since=2024-01-01T00:00:00Z

Filtered Export:

# Export specific resource types only
GET /Group/research-cohort/$export?_type=Patient,Observation,DiagnosticReport

Error Handling​

For comprehensive error scenarios and troubleshooting guidance, see Common Errors.

Relationships to Other Operations​

  • Export Poll Status: Use returned Content-Location URL to check export progress
  • Binary Access Read: Download files listed in completed export manifest
  • CapabilityStatement: Verify supported parameters and resource types