Patient Data APIs

The Patient Data APIs let you manage patients, retrieve clinical records, and power care workflows using Particle's nationwide data network. These APIs are used across multiple products and support access to clinical data in FHIR, Flat, and CCDA formats.

This guide provides a high-level overview of the core APIs and a recommended workflow for retrieving patient data.

Full schemas and parameter definitions are available in the API Reference.

Recommended Workflow

1. Register the Patient

POST /api/v2/patients

Submit demographic information to register a patient in Particle's system and create a particle_patient_id.

For more details on the Patient Registration APIs check our the guide here our the API Reference here.

2. Initiate a Query

Once the patient is registered, use the particle_patient_id to launch a search across the Particle network to collect clinical data.

POST /api/v2/patients/{particle_patient_id}/query

See Create Query → API Reference

3. Check Query Status

Queries take a short amount of time to be completed (see life of a query here). We recommend using our query status webhooks to get notified when your queries complete. You can also poll our endpoints for completion. Our Patient Query Status API defaults to checking the status of the most recent query for the patient.

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

If you have multiple queries going for a patient, you can use the query_id parameter to specify which query to check the status of.

• GET /api/v2/patients/{particle_patient_id}/query?query_id=...

See Query Status → API Reference

See Query Webhook → API Reference

4. Retrieve Patient Data

Once the query has completed, you are able to retrieve your data in the format(s) you are subscribed for. If you are unsure which format to use, reach out to your particle representative.

For detailed information on data retrieval, see Data Retrieval APIs.

Use your provisioned format(s):

• FHIR → GET /api/v2/patients/{particle_patient_id}/fhir

  📄 FHIR → API Reference

• Flat → GET /api/v2/patients/{particle_patient_id}/flat

  📄 Flat → API Reference

• CCDA → GET /api/v2/patients/{particle_patient_id}/ccda

  📄 CCDA → API Reference

Add _since or filter parameters to FHIR and Flat to limit results.

Common Gotchas

• You must register the patient before querying or subscribing.
• Requests to unprovisioned formats return 403 Forbidden with data_format_not_allowed.
• Webhook retries follow exponential backoff: 0s → 30s → 2m → 10m → 1h.