Query & Query Status APIs

Once you've registered a patient using the Patient Registration APIs, you can initiate a query to retrieve that patient's clinical history from the Particle network.

This page walks through how to:

• Launch a query for a patient
• Monitor the status of that query
• Get notified when results are available

A successful query enables downstream access to clinical data in FHIR, Flat, and/or CCDA format.

Create a Query

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

A query is how you request Particle to search for a patient's clinical records across its data network. Each query is scoped to one patient and results in a single clinical dataset (accessible through Data Retrieval APIs).

⚠️

You must register the patient first using POST /api/v2/patients

How It Works

• You initiate a query for a patient using their particle_patient_id
• Particle performs a Record Locator Service (RLS) search and gathers matching records from connected data sources
• Query results become available once the query reaches COMPLETE status

For more details, see Life of a Query

Request Body

Example

{
  "purpose_of_use": "TREATMENT",
  "specialties": ["CARDIOLOGY"],
  "hints": {
    "zip": "10001"
  }
}

View full schema → Create Query – API Reference

Response

The response will contain a query_id that you can use to track query progress or retrieve status explicitly.

{
  "external_patient_id": "123456",
  "hints": [
    "11111"
  ],
  "particle_patient_id": "ac82d365-97f9-4111-92fa-3a2b92744b12",
  "purpose_of_use": "TREATMENT",
  "query_id": "5f3ddefa-30b1-412d-a011-9386b48608cc",
  "specialties": [
    "ONCOLOGY"
  ]
}

You only need to track this ID if you want to check a specific query's status. Otherwise, the latest query is always available via polling.

Monitor Query Status

You can monitor query completion using either:

• Webhooks (recommended): receive a real-time notification when results are ready
• Polling: check the query status manually via the API

Once a query is complete, you'll be able to access the results using the Data Retrieval APIs.

Webhook: Real-Time Notification

We recommend configuring a webhook so your system is notified when a query completes. This avoids polling delays and enables faster downstream processing.

You can configure a webhook via the management API or by contacting your Particle Health Representative.

Webhook Event: com.particlehealth.api.v1.query

Sample Payload

{
  "specversion":"1.0",
  "id": "f834539f-a839-490b-80f9-b441cb9e435d",
  "source": "api/notifications",
  "type":"com.particlehealth.api.v1.query",
  "datacontenttype":"application/json",
  "time":"2023-05-15T12:00:14.694292853Z",
  "data":{
    "file_count": "2",
    "patient_id": "9557a65e-55b7-4a3b-b0a1-f4dd2df5a2f8",
    "person_id": "75c771c5-600e-4c4b-a4e9-f932fa2827aa",
    "purpose": "TREATMENT",
    "query_id": "50ee4bd4-bd87-4e66-bab1-7e0309a9a656",
    "status": "COMPLETE"
  }
}

Polling: Manual Status Check

If you don't want to use webhooks, you can poll for status using the following endpoints.

Check the status of the most recent query for a patient:

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

Check the status of a specific query:

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

Status values:

• PENDING: query accepted but not started
• RUNNING: records are being retrieved
• COMPLETE: results are available
• FAILED: query failed

View polling endpoint → API Reference

What's Next?

Once the query is complete, you can retrieve the clinical data in FHIR, Flat, or CCDA formats using the Data Retrieval APIs.