Overview

Description

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. You can also list all the patient_ids your organization has stored with Particle.

📘

As a general rule, best practice is to make sure you have first created your patients via the Patients API before initiating any other requests. This is because the particle_patient_id generated via the Patients API is required for many other workflows, including uploading documents, querying Healthix, initiating deltas queries, or subscribing to monitoring notifications.

Important Notes

• Ensure that each patient has a unique patient_id, as reusing patient_ids for different patients will result in errors.
• 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.

Flow of Requests

A Patients API POST request for a patient must be executed before:

1. You place a Documents POST request for the patient or place a Subscriptions POST request for a patient. This is because a patient must be registered in our system before they can be linked to documents or subscribed to monitoring notifications.
2. You can retrieve any documents back from Healthix for the patient. This is because you must provide patient consent details in the Patients API POST request, in order to be able to exchange data for the patient via Healthix. See more details on Healthix (NY HIE).
3. You initiate a Deltas query for a patient. This is because you must pass the particle_patient_id in any Deltas queries that you initiate.

Our Postman Collection should be used to get a sense of how to structure the API calls in the coding language of your choosing (e.g. cURL).

API Functions

Patient Create and Update

Required Fields

Example Request

{
  "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"
}

Response Model

{
  "address_city": "Brooklyn",
  "address_lines": [
    "999 Dev Drive"
  ],
  "address_state": "New York",
  "consent": [
    {
      "consent_data": "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"
}

Patient Consents

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).

Retrieve Posted Patient

Example Request

curl -X GET -H “Authorization: $authToken” \
https://api.particlehealth.com/api/v1/patients/{patient_id}

Response Model

{
  "address_city": "Brooklyn",
  "address_lines": [
    "999 Dev Drive"
  ],
  "address_state": "New York",
  "consent": [
    {
      "consent_data": "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"
}

Delete Patient

Example Request

curl -X DELETE -H “Authorization: $authToken” \
https://api.particlehealth.com/api/v1/patients/examplepatientid1

Response Model

“delete successful”

List Patients

Example Request

curl -X GET -H “Authorization: $authToken” \
https://api.particlehealth.com/api/v1/patients

Response Model

{
	“continuation_token”: “token” - Only populated if there are over 200 records returned
	“patients”: [
		“examplePatient1”,
		“examplePatient2”,
		“examplePatient3”
	]
}