What are “Deltas”?

Deltas is an extension of our core query flow that allows our customers to only return net-new data gathered since the prior query. For example, if you query for Patient 1 on Jan 1st, and query for them again on July 1st, the Particle Delta’s flow will (1) de-duplicate data across the 2 queries and (2) allow you to only return new data found since that initial Jan 1 query. Deltas also gives customers the ability specify the timeframe in which you'd like to retrieve data (e.g., if you want to retrieve data for a window other than the time since the last query).

The main benefit of using patient deltas or delta processing is efficiency. By only retrieving the net new or changed data, healthcare organizations can reduce the amount of data that needs to be transmitted and processed, saving time and resources. This can be particularly useful in scenarios where the patient's medical record is large or when frequent updates occur.

Delta processing can also help ensure data integrity and accuracy. By focusing on the changes made to the patient's record, it becomes easier to track and monitor modifications, reducing the risk of errors or inconsistencies.

Note that Deltas is an opt-in feature that must be enabled for your account by Particle. Please reach out to your Particle account team if interested.

Deltas Query Flow

Step-by-Step Query Flow

1. Create a patient

Leverage the Patients API to create a patient and note the Patient ID returned in the POST response. This ID will be used to initiate all queries for this patient, as well as retrieve all data returned from the queries.

2. Initiate a new Deltas query by querying the deltas endpoint

Example Request Body

REQUEST BODY EXAMPLE (with example values)
{
	"particle_patient_id": "UUID" //created in Step 1,
	"purpose_of_use": "TREATMENT",
	"specialties": ["ONCOLOGY"],
	"hints": ["10023"] //additional zip code(s), if relevant
}

📘

Data retrieved via Deltas queries will be available in FHIR or FLAT format.

If desired, customers can also optionally retrieve the data in the source CCDA (or non-CCDA) format by calling the CCDA API with the query_id. Note that Deltas are NOT supported in CCDA format, so ALL data from the query will be returned in CCDA. See more details below.

Response

If the POST request is successful, Particle will return a 200 response that includes the following information:

• the particle_patient_id
• a query_id that can be used to check the status of the query

Note that if the particle_patient_id provided is not found, Particle will return an error.

3. Check the status of your Deltas query

Customers can poll the Deltas API with the particle_patient_id to check the status of a Deltas query for that you have initiated for your patient. Alternatively, you can opt to receive a webhook notification upon completion of your Deltas query. See Event Notifications for more information on how to set up webhook notifications.

Response

• If the query is in progress, Particle will return a 202 response.
• When the query is complete, Particle will return a 200 response.

4.a Retrieve data delta in FHIR

When you receive200 response to a GET request to check the query status, or (if you are using webhooks) if you receive a Query Complete webhook notification, you can call the Deltas API to retrieve the data from your query in FHIR format.

Since Parameter

📘

To retrieve the data delta (i.e., the net new data identified since the last time data was retrieved for the patient), you must pass the since parameter in your request.

• If _since="lastQuery" (case-insensitive) is passed in, Particle will only return data added since the last time data was retrieved for the patient.

• If a _since="YYYY-MM-DD" parameter is passed in, Particle will only return new data retrieved since that date.

• If NO _since parameter is passed in, Particle will return the full patient history (i.e., all of the patient's data).

Note that if there are no updates in the deltas FHIR store, Particle will return an empty response. The empty response is returned as part of the standard API behavior. Additionally, all FHIR resources will be updated based on what Particle retrieves from the network. This includes FHIR resources that are not part of the $everything call.

Retrieving specific resources

The since parameter can be used with every resource, to return data for that resource since the prior query (or whichever date you specify).

4.b Retrieve data delta in FLAT

When you receive200 response to a GET request to check the query status, or (if you are using webhooks) if you receive a Query Complete webhook notification, you can call the Deltas API to retrieve the data from your query in FLAT format.

Since Parameter

📘

To retrieve the data delta (i.e., the net new data identified since the last time data was retrieved for the patient), you must pass the since parameter in your request.

• If _since="lastQuery" (case-insensitive) is passed in, Particle will only return data added since the last time data was retrieved for the patient.

• If a _since="YYYY-MM-DD" parameter is passed in, Particle will only return new data retrieved since that date.

• If NO _since parameter is passed in, Particle will return the full patient history (i.e., all of the patient's data).

Retrieving specific datasets

The since parameter can be used with every dataset, to return data for that dataset since the prior query (or whichever date you specify).

Examples

Retrieve all data in FLAT added for a patient since a specific date: GET https://api.particlehealth.com/deltas/flat/{particle_patient_id}?_since=2023-12-31

Retrieve individual datasets in FLAT (e.g., allergies and encounters) since a specific date: `GET https://api.particlehealth.com/deltas/flat/{particle_patient_id}?_since=2023-12-31&allergies&encounters

4.c Retrieve source CCDA (or non-CCDA) data

If desired, customers can also optionally retrieve the data in the source CCDA (or non-CCDA) format by calling the CCDA API with the query_id returned in the response to the initial Deltas query that you initiated.

Note that Deltas are NOT supported in CCDA format, so ALL data from the query will be returned in CCDA.

The main scenario where customers would want to leverage this workflow would be to retrieve raw files in non-CCDA format. This is primarily relevant for Monitoring, when Particle has flagged a new discharge summary retrieved in non-CCDA format and shared the file ID to retrieve the raw document.