The first step in your integration with Particle will be the Patients API.
The Patients API is used to manage your patient data stored with Particle. Patients are represented as a set of demographic data and stored in Particle's Master Patient Index, which allows network partners to match your patients to records in their systems. Using the Patients API, patients can be created, updated, retrieved, and deleted.
The particle_patient_id generated via the Patients API response is required for many other workflows, including uploading documents, querying Healthix, initiating deltas queries, or subscribing to monitoring notifications.
- Ensure that each patient has a unique
patient_id, as reusing patient_ids for different patients will result in errors.
- For example, if we detect separate sets of patient demographics with the same
patient_id , you may receive an error: Overlay detected. Please verify the patient_id and demographics. In this scenario, we would advise to review your patient demographics to ensure that a duplicate patient_id hasn't been submitted. More information on overlay errors here.
- Use the same POST endpoint to both create and update the patient demographics record for a
patient_id. If demographics were erroneously updated, you may use the DELETE operation to remove the patient and then add them back via POST.
- Successful requests will return a
200 OK, but you can also use a GET request to retrieve a patient and verify that they were uploaded successfully.
- Particle will generate and return a
particle_patient_idfor each patient that you create via the Patients API.
| |
|---|
| Description: | Creates a new patient and stores it in Particle's Master Patient Index, or updates an existing patient. |
| Path: | api/v2/patients |
| Method: | POST |
| Field | Required | Notes |
|---|
| given_name | TRUE | i.e. First Name |
| family_name | TRUE | i.e. Last Name |
| date_of_birth | TRUE | YYYY-MM-DD |
| gender | TRUE | FEMALE or MALE |
| postal_code | TRUE | 11111 |
| particle_patient_id | FALSE | |
| patient_id | FALSE | |
| ssn | FALSE | xxx-xx-xxxx |
| email | FALSE | |
| telephone | FALSE | xxx-xxx-xxxx |
| address_lines | FALSE | |
| address_city | TRUE | Brooklyn |
| address_state | TRUE | New York |
| consents | FALSE | Includes an array of objects. |
{
"address_city": "Brooklyn",
"address_lines": [
"999 Dev Drive"
],
"address_state": "New York",
"consent": [
{
"consent_date": "2021-01-01",
"partner": "Healthix",
"permission": "permit"
}
],
"date_of_birth": "1954-12-01",
"email": "[email protected]",
"family_name": "Quark",
"gender": "MALE",
"given_name": "Kam",
"patient_id": "pati-enti-d123-4567",
"postal_code": "11111",
"ssn": "123-45-6789",
"telephone": "234-567-8910"
}
{
"address_city": "Brooklyn",
"address_lines": [
"999 Dev Drive"
],
"address_state": "New York",
"consent": [
{
"consent_date": "2021-01-01",
"partner": "Healthix",
"permission": "permit"
}
],
"date_of_birth": "1954-12-01",
"email": "[email protected]",
"family_name": "Quark",
"gender": "MALE",
"given_name": "Kam",
"particle_patient_id": "1aa50979-1a8e-416d-8c13-a529033cc898",
"patient_id": "pati-enti-d123-4567",
"postal_code": "11111",
"ssn": "123-45-6789",
"telephone": "234-567-8910"
}
The consents parameters are used to provide patient consent to exchange data via our NY state HIE partner Healthix. Patient consent is required in order to query Healthix. For more details, check out Healthix (NY HIE).
| |
|---|
| Description: | Retrieves a patient. Can be used to verify that a patient has been successfully uploaded to the Particle's Master Patient Index. |
| Path: | api/v2/patients/{patient_id} |
| Method: | GET |
curl -X GET -H “Authorization: $authToken” \
https://api.particlehealth.com/api/v2/patients/{particle_patient_id}
{
"address_city": "Brooklyn",
"address_lines": [
"999 Dev Drive"
],
"address_state": "New York",
"consent": [
{
"consent_date": "2021-01-01",
"partner": "Healthix",
"permission": "permit"
}
],
"date_of_birth": "1954-12-01",
"email": "[email protected]",
"family_name": "Quark",
"gender": "MALE",
"given_name": "Kam",
"particle_patient_id": "1aa50979-1a8e-416d-8c13-a529033cc898",
"patient_id": "pati-enti-d123-4567",
"postal_code": "11111",
"ssn": "123-45-6789",
"telephone": "234-567-8910"
}
| |
|---|
| Description: | Removes a patient. This action will also delete all documents associated with that patient. Please note that once a patient has been deleted, you will need to add them via POST in order to upload documents for that patient. |
| Path: | api/v2/patients/{particle_patient_id} |
| Method: | DELETE |
curl -X DELETE -H “Authorization: $authToken” \
https://api.particlehealth.com/api/v2/patients/{particle_patient_id}
“delete successful”
| |
|---|
| Description: | Retrieves a list of all patient_ids submitted by your organization. |
| Path: | api/v2/patients |
| Method: | GET |
curl -X GET -H “Authorization: $authToken” \
https://api.particlehealth.com/api/v2/patients
{
“continuation_token”: “token” - Only populated if there are over 200 records returned
“patients”: [
“examplePatient1”,
“examplePatient2”,
“examplePatient3”
]
}
| |
|---|
| Description: | Returns the top matching patients for a given set of patient demographics. Useful for looking up a particle_patient_id. |
| Path: | api/v2/patients/search |
| Method: | POST |
curl -X POST -H “Authorization: $authToken” \
-H “Content-Type: application/json” \
-d '{
“given_name”: “Kam”,
“family_name”: “Quark”,
“date_of_birth”: “1954-12-01”,
“gender”: “MALE”,
“postal_code”: “11111”
}' \
https://api.particlehealth.com/api/v2/patients/search
Returns an array of matching patients, or 204 No Content if no matches are found.
[
{
“given_name”: “Kam”,
“family_name”: “Quark”,
“date_of_birth”: “1954-12-01”,
“gender”: “MALE”,
“postal_code”: “11111”,
“particle_patient_id”: “1aa50979-1a8e-416d-8c13-a529033cc898”,
“patient_id”: “pati-enti-d123-4567”
}
]
