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, when called without a query_id, returns the patient's latest completed query, which may be older than the query you just submitted. Pass the query_id from your submission to track that specific query, and check start_time in the response to see which query you received.

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 Webhook Event Notifications

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

Flat and FHIR® both support _since to return only data created or updated since a given time. To narrow results further, Flat takes dataset filter parameters, and FHIR® takes _type or a single resource type with GET /api/v2/patients/{particle_patient_id}/fhir/{type}.

Common Gotchas

• You must register the patient before querying or subscribing.
• Requests to unprovisioned formats return 403 Forbidden with error_code: FORBIDDEN.
• If your webhook endpoint doesn't return a 2xx response, Particle retries with exponential backoff between 10 seconds and 10 minutes, for up to 5 delivery attempts in total. After that, the notification isn't retried.