Patients API

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 obtain the data you share. 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.

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

Flow of Requests

A Patients API POST request for a patient must be executed before a Documents POST request for that patient. This is because a patient must be registered in our system before they can be linked to documents.

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

Description:Creates a new patient and stores it in Particle's Master Patient Index, or updates an existing patient.
Path:api/v1/patients
Method:POST

Required Fields

{
	“given_name”: “Henrick”, - Required
	“family_name”: “Testingson”,  - Required
	“date_of_birth”: “1957-03-23”, - Required
	“gender”: “MALE”, - Required
	“postal_code”: “12345”, - Required
	“patient_id”: “examplepatientid1”, - Required
	“ssn”: “123-45-6789”,
	“email”: “[email protected]”,
	“telephone”: “123-456-7890”,
	“address_lines”: [“123 Mulberry Court”],
	“address_city”: “Roxbury”, - Required
	“address_state”: “MA” - Required
}

Example Request

curl -X POST -H “Authorization: $authToken” \
-d '{"given_name": "Henrick",
      "family_name": "Testingson",
      "date_of_birth": "1957-03-23",
      "gender": "MALE",
      "postal_code": "12345",
      "purpose_of_use": "TREATMENT", 
      "patient_id":"examplepatientid1",
      "ssn": "123-45-6789",
      "email": "[email protected]",
      "telephone": "123-456-7890",
      "address_lines": ["123 Mulberry Court"],
      "address_city": "Roxbury",
      "address_state": "MA"}' \
https://api.particlehealth.com/api/v1/patients 

Response Model

{
	“given_name”: “Henrick”, 
	“family_name”: “Testingson”,
	“date_of_birth”: “1957-03-23”,
	“gender”: “MALE”, 
	“postal_code”: “12345”, 
	“patient_id”: “examplepatientid1”, 
	“ssn”: “123-45-6789”,
	“email”: “[email protected]”,
	“telephone”: “123-456-7890”,
	“address_lines”: [“123 Mulberry Court”],
	“address_city”: “Roxbury”,
	“address_state”: “MA”
}

Retrieve Posted Patient

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/v1/patients/{patient_id}
Method:GET

Example Request

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

Response Model

{
	“given_name”: “Henrick”, 
	“family_name”: “Testingson”,
	“date_of_birth”: “1957-03-23”,
	“gender”: “MALE”, 
	“postal_code”: “12345”, 
	“patient_id”: “examplepatientid1”, 
	“ssn”: “123-45-6789”,
	“email”: “[email protected]”,
	“telephone”: “123-456-7890”,
	“address_lines”: [“123 Mulberry Court”],
	“address_city”: “Roxbury”,
	“address_state”: “MA”
}

Delete Patient

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 re-add them via POST in order to upload documents for that patient.
Path:api/v1/patients/{patient_id}
Method:DELETE

Example Request

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

Response Model

“delete successful”

List Patients

Description:Retrieves a list of all patient_ids submitted by your organization.
Path:api/v1/patients
Method:GET

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”
	]
}


What’s Next