Data Retrieval APIs

After you've registered a patient and completed a query, you can retrieve the clinical data using Particle's Data Retrieval APIs.

This page covers how to:

• Access clinical data in different formats (FHIR, Flat, CCDA)
• Use filtering parameters to optimize data retrieval
• Handle data format requirements and permissions

Supported Data Formats

Particle supports clinical data retrieval in two formats for v2 APIs. Your organization's subscription determines which formats are available to you.

Flat Data

Tabular format optimized for analytics and reporting. Each resource type (medications, conditions, etc.) is available as structured tables with extensive filtering capabilities.

C-CDA

Clinical Document Architecture format providing comprehensive clinical summaries in standardized XML documents. Supports both bulk download and individual file access.

FHIR R4 (Currently Disabled)

⚠️

Note: The FHIR endpoint is currently disabled for v2 APIs due to implementation requirements. FHIR queries require a FHIR patient resource that is not automatically created when patients are registered or queries are initiated via v2 endpoints.

Data Retrieval Endpoints

Flat Data Retrieval

GET /api/v2/patients/{particle_patient_id}/flat

Retrieves clinical data in tabular format, organized by resource type. Supports extensive filtering by individual dataset types.

Query Parameters:

• _since (optional): Filter resources updated after this time (ISO 8601 format)
• Dataset Filters (optional): Include any of these parameters to filter specific datasets:
  • ALLERGIES - Allergy and intolerance information
  • COMPOSITIONS - Clinical documents and summaries
  • COVERAGES - Insurance and coverage information
  • DOCUMENT_REFERENCES - References to clinical documents
  • ENCOUNTERS - Healthcare encounters and visits
  • FAMILY_MEMBER_HISTORIES - Family medical history
  • IMMUNIZATIONS - Vaccination records
  • LABS - Laboratory results and tests
  • LOCATIONS - Healthcare facility information
  • MEDICATIONS - Current and historical medications
  • MED_FILLS - Medication dispensing records
  • MEDRECS - Medication reconciliation data
  • ORGANIZATIONS - Healthcare organization details
  • PRACTITIONERS - Healthcare provider information
  • PATIENTS - Patient demographic information
  • PROBLEMS - Problem lists and conditions
  • PROCEDURES - Medical procedures and interventions
  • PROVENANCES - Data source and provenance information
  • RELATED_PERSONS - Emergency contacts and related individuals
  • SOCIAL_HISTORIES - Social determinants and lifestyle factors
  • VITAL_SIGNS - Vital signs and measurements

Usage Examples:

# Get all available datasets
GET /api/v2/patients/{particle_patient_id}/flat

# Get only medications and labs since January 1, 2024
GET /api/v2/patients/{particle_patient_id}/flat?MEDICATIONS&LABS&_since=2024-01-01T00:00:00Z

# Get only patient demographics and encounters
GET /api/v2/patients/{particle_patient_id}/flat?PATIENTS&ENCOUNTERS

Note: If no dataset parameters are specified, all available datasets except PROVENANCES are returned by default. Query parameter filtering requires contacting [email protected] for access.

📄 Flat Data Retrieval → API Reference

C-CDA Data Retrieval

GET /api/v2/patients/{particle_patient_id}/ccda

Retrieves clinical data as C-CDA documents. Can return either a ZIP file containing all documents or a single specific file.

Query Parameters:

• query_id (optional): Specific query ID to retrieve documents from. If not provided, uses the most recent query.
• file_id (optional): Specific file ID to download a single C-CDA document instead of a ZIP file containing all documents.

Usage Examples:

# Download ZIP file of all C-CDA documents from most recent query
GET /api/v2/patients/{particle_patient_id}/ccda

# Download ZIP file from a specific query
GET /api/v2/patients/{particle_patient_id}/ccda?query_id=abc123

# Download a single specific C-CDA file
GET /api/v2/patients/{particle_patient_id}/ccda?file_id=file456

# Download a single file from a specific query
GET /api/v2/patients/{particle_patient_id}/ccda?query_id=abc123&file_id=file456

📄 C-CDA Data Retrieval → API Reference

Filtering and Optimization

Date-based Filtering

Use the _since parameter to retrieve only data modified after a specific date:

GET /api/v2/patients/{particle_patient_id}/flat?_since=2024-01-01T00:00:00Z

This is useful for:

• Incremental data updates
• Reducing payload size
• Focusing on recent clinical activity

Dataset-specific Filtering

For Flat data, you can filter by specific dataset types by including them as query parameters:

# Get only critical datasets
GET /api/v2/patients/{particle_patient_id}/flat?MEDICATIONS&LABS&PROBLEMS&ENCOUNTERS

# Combine with date filtering
GET /api/v2/patients/{particle_patient_id}/flat?MEDICATIONS&LABS&_since=2024-01-01T00:00:00Z

Data Format Requirements

Format Permissions

Your organization must be provisioned for specific data formats. Requests to unprovisioned formats will return:

403 Forbidden
{
  "error": "data_format_not_allowed" 
}

Query Parameter Access

Advanced query parameter filtering for Flat data requires special access. Contact [email protected] to enable filtering capabilities.

Contact your Particle Health representative to update format permissions or enable additional features.

Query Completion Requirement

Data retrieval is only available after a query reaches COMPLETE status. Attempting to retrieve data before query completion will result in an error.

Response Handling

Successful Responses

• Flat: Returns JSON with dataset types as keys and arrays of records as values
• C-CDA: Returns either a ZIP file containing all C-CDA documents or a single C-CDA file (depending on parameters)

Empty Results

If no clinical data is found for a patient, APIs will return empty collections rather than error responses.

Large Datasets

For patients with extensive clinical histories, consider:

• Using date filters to retrieve data incrementally
• Implementing pagination where supported
• Processing data in chunks to avoid memory issues

Integration Patterns

Real-time Workflow

1. Register patient → Complete query → Retrieve data immediately
2. Best for interactive applications requiring immediate data access

Batch Processing

1. Register multiple patients → Queue queries → Retrieve data when complete
2. Best for analytics, reporting, or bulk data processing

Incremental Updates

1. Initial full data retrieval → Periodic incremental updates using _since
2. Best for maintaining synchronized datasets

Next Steps

• Implementation Guides: See format-specific implementation guides for detailed integration patterns
• API Reference: Explore full schemas and examples in the API Reference documentation
• Support: Contact your Particle Health representative for format provisioning or integration guidance