Skip to main content

Binary Access Read Operation

Overview​

The Binary Access Read Operation downloads exported files directly without the FHIR Binary resource wrapper. This operation is used to retrieve the actual file content generated during bulk data export.

Operation: GET /Binary/{id}/$binary-access-read

Key Use Cases:

  • Download exported FHIR data files in NDJSON format
  • Retrieve export error logs for troubleshooting
  • Access attachment files referenced in exported resources
  • Support automated file processing workflows

Important: File URLs are provided in the export status manifest. Files may have expiration times and require the same authorization used for the export request.

Parameters​

NameTypeRequiredDescription
idstringYesBinary resource ID from export manifest URL

Operations​

Download File​

Retrieves the raw file content without FHIR Binary metadata wrapper.

Endpoint: GET /Binary/{id}/$binary-access-read

Examples​

Download Data File
curl -X GET "https://fhir.netsmartcloud.com/uscore/v1/bulk-data/Binary/patient-file-123/\$binary-access-read" \
    -H "Authorization: Bearer {access_token}" \
    -H "Accept: application/fhir+ndjson" \
    -o "patients.ndjson"
Download Error File
curl -X GET "https://fhir.netsmartcloud.com/uscore/v1/bulk-data/Binary/error-file-456/\$binary-access-read" \
    -H "Authorization: Bearer {access_token}" \
    -H "Accept: application/fhir+ndjson" \
    -o "export-errors.ndjson"
Download with Streaming
curl -X GET "https://fhir.netsmartcloud.com/uscore/v1/bulk-data/Binary/large-file-789/\$binary-access-read" \
    -H "Authorization: Bearer {access_token}" \
    -H "Accept: application/fhir+ndjson" \
    --output "large-dataset.ndjson" \
    --progress-bar

Response Examples​

NDJSON Data File:

Patient Data File
HTTP/2 200 OK
Content-Type: application/fhir+ndjson
Content-Length: 2048576
Content-Disposition: attachment; filename="Patient.ndjson"

{"resourceType":"Patient","id":"123","name":[{"family":"Doe","given":["John"]}]}
{"resourceType":"Patient","id":"456","name":[{"family":"Smith","given":["Jane"]}]}
{"resourceType":"Patient","id":"789","name":[{"family":"Johnson","given":["Bob"]}]}

Error File:

Export Error File
HTTP/2 200 OK
Content-Type: application/fhir+ndjson
Content-Length: 1024
Content-Disposition: attachment; filename="errors.ndjson"

{"resourceType":"OperationOutcome","issue":[{"severity":"warning","code":"processing","diagnostics":"Patient/999 not found"}]}
{"resourceType":"OperationOutcome","issue":[{"severity":"error","code":"security","diagnostics":"Access denied to Observation/888"}]}

Integration Patterns​

Batch File Download​

# Download all files from export manifest
export_manifest="export_status.json"
token="your_access_token"

# Extract and download data files
jq -r '.output[] | "\(.url) \(.type)"' "$export_manifest" | while read url type; do
  filename="${type,,}.ndjson"  # Convert to lowercase
  echo "Downloading $type resources to $filename"
  curl -X GET "$url" \
    -H "Authorization: Bearer $token" \
    -H "Accept: application/fhir+ndjson" \
    -o "$filename"
done

# Extract and download error files
jq -r '.error[]?.url' "$export_manifest" | while read url; do
  if [ "$url" != "null" ] && [ -n "$url" ]; then
    echo "Downloading error file"
    curl -X GET "$url" \
      -H "Authorization: Bearer $token" \
      -H "Accept: application/fhir+ndjson" \
      -o "errors.ndjson"
  fi
done

File Processing Workflow​

# Process downloaded NDJSON files
process_ndjson_file() {
  local file="$1"
  local resource_type="$2"
  
  echo "Processing $resource_type resources from $file"
  
  # Count resources
  resource_count=$(wc -l < "$file")
  echo "Found $resource_count $resource_type resources"
  
  # Process each line (resource)
  while IFS= read -r line; do
    # Parse JSON and extract relevant fields
    id=$(echo "$line" | jq -r '.id')
    echo "Processing $resource_type/$id"
    
    # Add your processing logic here
    # Example: validate, transform, load into database
    
  done < "$file"
}

# Process all downloaded files
for file in *.ndjson; do
  if [ "$file" = "errors.ndjson" ]; then
    echo "Processing error file: $file"
    # Handle errors appropriately
  else
    resource_type=$(basename "$file" .ndjson)
    process_ndjson_file "$file" "$resource_type"
  fi
done

Parallel Downloads​

# Download multiple files in parallel
export_manifest="export_status.json"
token="your_access_token"
max_parallel=4

# Function to download a single file
download_file() {
  local url="$1"
  local filename="$2"
  
  curl -X GET "$url" \
    -H "Authorization: Bearer $token" \
    -H "Accept: application/fhir+ndjson" \
    -o "$filename" \
    --progress-bar
}

# Export function for parallel execution
export -f download_file
export token

# Download files in parallel
jq -r '.output[] | "\(.url) \(.type,,).ndjson"' "$export_manifest" | \
  xargs -n 2 -P "$max_parallel" bash -c 'download_file "$@"' _

File Types and Formats​

Data Files​

  • Format: NDJSON (Newline Delimited JSON)
  • Content-Type: application/fhir+ndjson
  • Structure: One FHIR resource per line
  • Encoding: UTF-8

Error Files​

  • Format: NDJSON with OperationOutcome resources
  • Content-Type: application/fhir+ndjson
  • Purpose: Export processing errors and warnings

Attachment Files​

  • Format: Original format (PDF, images, etc.)
  • Content-Type: Varies by file type
  • Purpose: Referenced by DocumentReference resources

Error Handling​

Common Error Scenarios​

File Not Found
HTTP/2 404 Not Found

{
  "resourceType": "OperationOutcome",
  "issue": [{
    "severity": "error",
    "code": "processing",
    "details": {
      "text": "Could not locate this Binary."
    }
  }]
}

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

Relationships to Other Operations​

  • Export Poll Status: Provides file URLs in export completion manifest
  • Group Export: Initiates the process that generates downloadable files
  • CapabilityStatement: Documents supported file formats and operations