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 three 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® R4B

FHIR® R4B resources in JSON. Retrievable as a complete patient bundle, narrowed to specific resource types, or one resource at a time.

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): Return only data that Particle created or updated at or after this time. See Date-based Filtering.
Dataset Filters (optional): Include any of these parameters to filter specific datasets:
- AI_CITATIONS - Source citations for AI outputs
- AI_OUTPUTS - AI-generated clinical summaries
- ALLERGIES - Allergy and intolerance information
- 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
- MED_FILLS - Medication dispensing records
- MEDICATIONS - Current and historical medications
- ORGANIZATIONS - Healthcare organization details
- PATIENTS - Patient demographic information
- PRACTITIONERS - Healthcare provider information
- PROBLEMS - Problem lists and conditions
- PROCEDURES - Medical procedures and interventions
- RECORD_SOURCES - Links between records and source documents
- SOCIAL_HISTORIES - Social determinants and lifestyle factors
- SOURCES - Source clinical documents
- TRANSITIONS - Admission and discharge events
- 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

# Get only data created or updated since the patient's latest completed query
GET /api/v2/patients/{particle_patient_id}/flat?_since=lastQuery

Note: If no dataset parameters are specified, all datasets are returned. AI_OUTPUTS, AI_CITATIONS, and MED_FILLS appear only if they have been enabled for your organization. Contact your Particle representative to enable them.

📄 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

FHIR® R4B Data Retrieval

Returns clinical data as FHIR® R4B resources. Access is provisioned per organization — contact your Particle representative to enable FHIR® format access.

Endpoint	Returns
`GET /api/v2/patients/{particle_patient_id}/fhir`	A Bundle of all resources for the patient. Equivalent to a FHIR® `$everything` call.
`GET /api/v2/patients/{particle_patient_id}/fhir/{type}`	A Bundle of a single resource type, for example `Condition`.
`GET /api/v2/patients/{particle_patient_id}/fhir/{type}/{id}`	A single resource, by type and ID.

See Supported FHIR® Resources for the resource types these return and what each one contains.

Query Parameters:

_type (base endpoint only): comma-delimited resource types to return, e.g. _type=Condition,Observation. When omitted, all types are returned.
_count: number of resources per page. Default and maximum 1000.
_page_token: requests the next page. Take the value from the response's next link.
_since: return only data that Particle created or updated at or after this time. See Date-based Filtering.

These are the only query parameters accepted. Anything else returns a 400 on the two Bundle endpoints; the single-resource endpoint takes none and ignores them.

Usage Examples:

# All available FHIR® resources for a patient
GET /api/v2/patients/{particle_patient_id}/fhir

# Only conditions and observations
GET /api/v2/patients/{particle_patient_id}/fhir?_type=Condition,Observation

# A single resource type
GET /api/v2/patients/{particle_patient_id}/fhir/Condition

# Only resources created or updated since the patient's latest completed query
GET /api/v2/patients/{particle_patient_id}/fhir?_since=lastQuery

Paging: while more pages remain, the response's link array contains a next entry — use its url as your next request, and stop once it is absent. _page_token values are opaque, so do not construct them yourself. When you pass _type, resources come back grouped by type in alphabetical order, so a single page may contain only one type.

Requesting a type that is not a valid FHIR® resource type returns a 400; a valid type the patient has no resources for returns a 404.

📄 FHIR® Data Retrieval → API Reference · By Type · By ID

Filtering and Optimization

Date-based Filtering

Use the _since parameter on Flat and FHIR® to retrieve only data that Particle created or updated at or after a specific time, or pass lastQuery to retrieve data since the patient's latest completed query. For example:

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

Flat accepts a plain date (e.g. 2024-01-01) or a full timestamp. FHIR® requires a full timestamp with a time zone (e.g. 2024-01-01T00:00:00Z); a plain date returns a 400. For FHIR®:

A resource is returned when its meta.lastUpdated is at or after _since.
Resources stored before Particle began recording meta.lastUpdated are always returned until the patient's next query refreshes them.

The _since parameter filters based on when Particle created or updated the data, not based on clinical documentation dates. This means:

Data with older clinical dates may be returned if it was newly retrieved in a recent query
Use this for incremental updates to get only net-new data since your last retrieval

This is useful for:

Incremental data updates to sync only new data
Reducing payload size by avoiding re-downloading previously retrieved data
Building delta/change detection workflows

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
{
  "message": "unauthorized",
  "error_code": "FORBIDDEN"
}

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

Query Completion Requirement

Data retrieval requires a completed query. If the patient has no completed query, the request returns an error (404 for Flat).

If a new query is still running, Flat returns data from the patient's previous completed query. Wait for the new query to complete before retrieving, so you get its results.

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

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

Batch Processing

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

Incremental Updates

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

Next Steps

Query and Query Status APIs: Start a query and confirm it has completed before retrieving data
Life of a Query: Understand query states and how long retrieval takes
Webhook Event Notifications: Get notified when a query completes instead of polling
C-CDA vs. FHIR®: Choose the right data format for your integration
Supported FHIR® Resources: Resource types returned by the FHIR® endpoints
Flat Data for Clinical Workflows and Supported Flat Data Domains: Dataset details for Flat retrieval
Rate Limiting & Quotas: Plan request volume for bulk retrieval
Support: Contact your Particle Health representative for format provisioning or integration guidance