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. If you omit it when polling, you get the latest completed query, which may not be the query you just started (see Which query does polling return? below).

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.v2.query

Sample Payload

{
  "specversion":"1.0",
  "id": "f834539f-a839-490b-80f9-b441cb9e435d",
  "source": "api/notifications",
  "type":"com.particlehealth.api.v2.query",
  "subject":"DELTAS Query Complete",
  "datacontenttype":"application/json",
  "time":"2023-05-15T12:00:14.694292853Z",
  "data":{
    "external_patient_id": "ext_patient_123",
    "file_count": "2",
    "particle_patient_id": "75c771c5-600e-4c4b-a4e9-f932fa2827aa",
    "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"
  }
}

The webhook is sent only when a query reaches COMPLETE or COMPLETE_WITH_ERRORS. A query that ends in any other state, such as TIMEOUT, sends no notification, so poll the query status if you have not received a webhook. See Webhook Event Notifications for subject lines and the full list of what is and isn't notified.

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 latest completed query for a patient:

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

Without a query_id, this endpoint returns the patient's most recent query that has completed, not the most recent query submitted. See Which query does polling return? below.

Check the status of a specific query:

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

Status values:

• SCHEDULED: query accepted and queued
• RUNNING: records are being retrieved
• COMPLETE: results are available
• TIMEOUT: query completed but one or more network endpoints did not respond in time; partial results may be available

Which query does polling return?

When you call GET /api/v2/patients/{particle_patient_id}/query without query_id:

• The response is the patient's latest query in a completed state. A query that is still SCHEDULED or RUNNING is ignored.
• A 200 OK therefore does not mean the query you just submitted has finished. If an earlier query completed two days ago and you submitted a new one a minute ago, you get the two-day-old query back, with state: COMPLETE, until the new one finishes. Nothing in the response says a newer query is in progress.
• Check start_time (when the returned query began) and id (the query ID) to see which query you received. Compare them to the query_id and time of the query you submitted.
• If the patient has never had a completed query, the endpoint returns 404 Not Found.

To track a specific query, always pass the query_id returned when you submitted it:

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

Passing query_id returns that exact query in whatever state it is in (SCHEDULED, RUNNING, COMPLETE, and so on). The endpoint does not accept a _since filter. We recommend webhooks, or polling with query_id, for anything that must reflect a specific query.

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.