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.

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.

How do deltas work?

APIs

1. Create a patient

Leverage the Patient’s API to create a patient and note the Patient ID returned in the POST response. This ID will be used for all initial and subsequent queries for this patient.

https://docs.particlehealth.com/reference/post_api-v1-patients

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

POST tohttps://api.particlehealth.com/deltas/ to start a query based on a patient created via the patients API. See the example request payload below.

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
}

📘

Every Delta query will trigger both FHIR and FLAT flows.

• If the particle_patient_id provided is not found, return a 4xx error

The user, upon successful query initiation, should receive:

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

3. Check the status of your Deltas query

GET https://api.particlehealth.com/deltas/{particle_patient_id} to obtain the status of a Deltas query

• If the query is in progress, the user should receive a 202
• Once complete, the user should receive a 200

Retrieve deltas via FHIR

Once a query is completed, run GET https://api.particlehealth.com/deltas/patient/{particle_patient_id}/$everything

Or fetch any other GET resource and fetch data from the persisted delta FHIR store https://api.particlehealth.com/deltas/R4/{resource_type}/{resource_id}

📘

Note that 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.

The since parameter can be used with every resource, which will return all data since the prior query. If this is your first query for the patient, do not pass the since parameter through your query.

Retrieve deltas via FLAT

Once a query is completed, run GET https://api.particlehealth.com/deltas/flat/{particle_patient_id} to get a flat patient

📘

Note that this is intentionally different from the query-based flat, where the call is GET /flat/{id}/collect-data[parameters]

Additionally, calling GET https://api.particlehealth.com/deltas/flat/{particle_patient_id}?[data_sets] allows you to return specific Flat datasets for your patient:
GET https://api.particlehealth.com/deltas/flat/{particle_patient_id}?**allergies**

• e.g. flat/{particle_patient_id}?allergies or flat/{particle_patient_id}?allergies&encounters

Retrieve deltas via FHIR with the _since parameter

📘

The SINCE parameter provides the most recent updates for all resources since the provided date.

Once a query is completed, run GET https://api.particlehealth.com/deltas/Patient/{particle_patient_id}/$everything or any other GET resource and fetch data from the persisted delta FHIR store

• If a _since="YYYY-MM-DD" parameter is passed in, Particle will only return data added since the last query.
• If no _since parameter is passed in, all of the Patient's data will be returned.

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.

Retrieve deltas via FLAT with _since parameter

📘

The SINCE parameter provides the most recent updates for all datasets since the provided date. SINCE is a hard requirement for the MVP of deltas.

Once a query is completed, optionally include a _since=YYYY-MM-DD to retrieve data since a certain date

• If a _since="YYYY-MM-DD" parameter is passed in, Particle will only return data added since the last query.
• If no _since parameter is included, all of the Patient’s data will be returned.

Relevant endpoints:

GET https://api.particlehealth.com/deltas/flat/{particle_patient_id}?_since=2023-12-31 to get a flat patient

GET https://api.particlehealth.com/deltas/flat/{particle_patient_id}?_since=2023-12-31&[data_sets] to retrieve individual data sets

Ex: GET https://api.particlehealth.com/deltas/flat/{particle_patient_id}?_since=2023-12-31&allergies&encounters