Snapshot APIs
Snapshot APIs may be leveraged by customers looking to build their own version of a UI, or integrate Particle's data to their own systems for downstream use cases.
How to use the API
The following sections will demonstrate how to initiate a patient query and use the resulting query ID to access data via the Patient History APIs.
Initializing a patient query
POST api.particlehealth.com/flat
Request Headers:
"Authorization": "Bearer {PARTICLE_AUTHORIZATION_TOKEN goes here}"
Request Body:
{
"address_city": "Brooklyn",
"address_lines": ["999 Dev Drive", "Apt 4G"],
"address_state": "NY",
"date_of_birth": "1954-12-01",
"family_name": "Quark",
"gender": "Male",
"given_name": "Kam",
"postal_code": "11111",
"purpose_of_use": "TREATMENT"
}
Expected Response:
{
"id": "f0ae93ed-8d03-457a-ae71-f679da7bbfbe",
"demographics": {
"given_name": "Kam",
"family_name": "Quark",
"date_of_birth": "1954-12-01",
"gender": "MALE",
"ssn": "",
"email": "",
"address_lines": [
"999 Dev Drive",
"Apt 4G",
],
"address_state": "NY",
"address_city": "Brooklyn",
"postal_code": "11111",
"hints": [],
"telephone": "",
"npi": "",
"purpose_of_use": "TREATMENT",
"specialties": null
},
"state": "PENDING"
}
Checking query statuses
To check the statuses of all your queries, use the following:
GET api.particlehealth.com/history/api/v1/patients
Request Headers:
"Authorization": "Bearer {PARTICLE_AUTHORIZATION_TOKEN goes here}"
Expected Response:
{
"patients": [
{
"given_name": "Kam",
"family_name": "Quark",
"date_of_birth": "1954-12-01",
"gender": "MALE",
"external_patient_id": "",
"query_id": "83c1966f-441a-4bbf-b929-9c3a530a7d87",
"query_date": "2023-10-24",
"query_status": "PENDING",
"link_id": "645173f19ce6a72303b57161"
"file_count": 5,
"request_endpoint": "BOOST_V2",
"particle_patient_id": "cmn348932nc-441a-4bbf-b929-48cn239vcjs295"
},
{
"given_name": "Kam",
"family_name": "Quark",
"date_of_birth": "1954-12-01",
"gender": "MALE",
"external_patient_id": "",
"query_id": "3e8e18ed-f515-4f3d-8ed2-808fc8a9d11a",
"query_date": "2023-10-24",
"query_status": "COMPLETE",
"link_id": "645173f19ce6a72303b57161",
"file_count": 5,
"request_endpoint": "DELTAS",
"particle_patient_id": "cmn348932nc-441a-4bbf-b929-48cn239vcjs295"
},
],
// each response is limited to 1000 queries, if there are more add the
// following to the next request under the query param "continuation_token"
"continuation_token": "fsjf0983434fg3wef"
}
Fetching patient data
Once the query_status
comes back as COMPLETE
, retrieve the query_id
from that data set.
Use that query_id
in the following requests for the Patient History data.
Authorization
To authorize your requests to the API, just add a particle auth token to the header like below:
"Authorization": "Bearer {PARTICLE_AUTHORIZATION_TOKEN goes here}
Patient History
The following are example responses you should expect from each available endpoint in the API.
GET api.particlehealth.com/history/api/v1/patients/{query_id}
{
"summary": {
"given_name": "Kam, Kam, Kam, Kam, Kam",
"family_name": "Quark, Quark, Quark, Quark, Quark",
"date_of_birth": "1954-12-01T00:00:00+00:00",
"gender": "FEMALE",
"race": "White or Caucasian, , Not Hispanic or Latino, ",
"address_line": "999 Dev Drive, 999 Dev Drive",
"address_state": "New York, New York",
"address_city": "Brooklyn, Brooklyn",
"postal_code": "11111, 11111",
"telephone": "",
"patient_id": "63051444-dc64-44a5-b0a2-1fd4e76da9f6"
},
"query_demographics": {
"given_name": "Kam",
"family_name": "Quark",
"date_of_birth": "1954-12-01",
"gender": "MALE",
"email": "",
"address_lines": [
"999 Dev Drive"
],
"address_state": "NY",
"address_city": "Brooklyn",
"postal_code": "11111",
"telephone": "",
"patient_id": ""
},
"insurance": {
"payor": ", ",
"policy_holder": "Self",
"group_number": "ec66c20f-eed8-4bb5-943e-55ecbc71b64e"
},
"allergies": [array of Allergies],
"conditions": [array of Conditions],
"medications": [array of Medications],
"sources": [array of Location Sources],
"labs": [array of Labs],
"procedures": [array of Procedures],
"vitals": [array of Vitals],
"encounters": [array of Encounters],
"practitioners": [array of Practitioners],
"med_recs": [array of MedRecs]
}
Patient data endpoints
The following endpoints all follow this pattern /history/api/v1/patients/{QUERY_ID}
. The remainder of the endpoint is indicated by the title for each dataset below.
Each endpoint returns an array of one or many of the available datasets. Use the datasets section below to reference the responses to our API endpoints.
/allergies
{
"allergies": []Allergy
}
/conditions
{
"conditions": []Condition
}
/ encounters
{
"encounters": []Encounter
}
/filtered-medications
{
[]FilteredMedication
}
/immunizations
{
"immunizations": []Immunization
}
/labs
{
"labs": []Lab
}
/medications
{
"medications": []Medication,
"alerts": []MedicationAlert
}
/medrecs
{
"med_recs": []MedRec
}
/procedures
{
"recent_procedures": []Procedure,
"duplicate_procedures": []DuplicateProcedure,
}
/providers
{
"practitioners": []Practitioner
}
/socialhistory
{
"social_history": []SocialHistory
}
/sources
{{
"locations": []Location
}
/vitals
{
"vital_signs": []VitalSign
}
Available datasets
Allergy
{
"name": "Ceftriaxone",
"code": "2193",
"code_system": "UNK",
"all_names_and_codes": [
{
"name": "Ceftriaxone",
"code": "2193",
"code_system": "UNK",
}],
"onset_start": "2010-05-11",
"onset_end": "2010-05-12",
"manifestation": "Diarrhea",
"manifestation_code": "62315008",
"manifestation_code_system": "SNOMED-CT",
"all_manifestation_names_and_codes": [
{
"name": "Diarrhea",
"code": "62315008",
"code_system": "SNOMED-CT",
},
]
}
Condition
{
"name": "Infection of amputation stump of right lower extremity",
"code": "T87.43",
"code_system": "ICD-10-CM",
"recorded_date": "2013-01-01",
"onset_date": "2013-01-01",
"status": "Active",
"all_names_and_codes": [
{
"name": "Infection of amputation stump of right lower extremity",
"code": "11996161000119100",
"code_system": "SNOMED-CT"
},
{
"name": "Infection of amputation stump of right lower extremity",
"code": "T87.43",
"code_system": "ICD-10-CM"
},
{
"name": "Infection of amputation stump of right lower extremity",
"code": "997.62",
"code_system": "ICD-9-CM"
},
{
"name": "Infection of amputation stump of right lower extremity",
"code": "1582724",
"code_system": "IMO"
}
]
}
DuplicateProcedure
{
"grouped_by": "Code",
"name": "HC BASIC METABOLIC PANEL (CA TOTAL)",
"code": "80048",
"code_system": "CPT-4",
"all_dates": [
"2009-07-01"
]
}
Encounter
{
"id": "21534a93-1da2-4978-8f12-beb39bb46817",
"name": "Ambulatory",
"code": "AMB",
"code_system": "ActCode",
"start_time": "2009-07-01",
"end_time": "2009-07-01",
"location_id": "fa5a024d-114b-4dd0-b933-a85f9412e6a1",
"location": {
"name": "Sandbox Hospital",
"city": "Brooklyn",
"state": "New York",
"zip_code": "11111",
"address": "456 Sandbox Ave",
"location_type": "Pre-Admission Testing",
"location_type_code": "unknown",
"location_type_code_system": "http://terminology.hl7.org/CodeSystem/data-absent-reason",
"location_id": "fa5a024d-114b-4dd0-b933-a85f9412e6a1",
"secondary_code_data": [
{
"type": "Pre-Admission Testing",
"code": "unknown",
"code_system": "http://terminology.hl7.org/CodeSystem/data-absent-reason"
}
]
},
"practitioner_ids": [
"b03acaf3-a6fb-4e71-b21e-1bb934a723cb"
],
"practitioners": [
{
"practitioner_id": "b03acaf3-a6fb-4e71-b21e-1bb934a723cb",
"given_name": "Meredith",
"family_name": "Gray",
"suffix": "MD",
"address": "456 Sandbox Ave",
"city": "Brooklyn",
"state": "New York",
"phone": "",
"npi": "Not Available"
}
],
"document_reference": {
"encounter_reference_id": "21534a93-1da2-4978-8f12-beb39bb46817",
"content_type": "Note",
"type_code": "34109-9",
"type_code_system": "LOINC",
"content": "PGxpc3Qgc3R5bGVDb2RlPSJ4VE9DIj4NCiAgPGl0ZW0+DQogICAgPGNhcHRpb24+UHJlLVByb2NlZHVyZSBJbnN0cnVjdGlvbnM8L2NhcHRpb24+DQogICAgPGNvbnRlbnQgSUQ9Ik5vdGUxNCI+DQogICAgICA8Y29udGVudD4NCiAgICAgICAgPGNvbnRlbnQgc3R5bGVDb2RlPSJ4TGFiZWwiPkZvcm1hdHRpbmcgb2YgdGhpcyBub3RlIG1pZ2h0IGJlIGRpZmZlcmVudCBmcm9tIHRoZSBvcmlnaW5hbC48L2NvbnRlbnQ+DQogICAgICAgIDxiciAvPlNwb2tlIHdpdGggbnVyc2UgcmVnYXJkaW5nIGFibm9ybWFsIHUvYSBTaGUgY2FsbGVkIGluIHJ4IGZvciBiYWN0cmltIGFuZCBmb2xsb3dlZCB1cCB3aXRoIHBhdGllbnQ8L2NvbnRlbnQ+DQogICAgICA8YnIgLz4NCiAgICAgIDxjb250ZW50IHN0eWxlQ29kZT0ieExhYmVsIj5NZXJlZGl0aCBHcmF5LCBNRDwvY29udGVudD4NCiAgICAgIDxiciAvPg0KICAgIDwvY29udGVudD4NCiAgPC9pdGVtPg0KICA8aXRlbT4NCiAgICA8Y2FwdGlvbj5QcmUtUHJvY2VkdXJlIEluc3RydWN0aW9uczwvY2FwdGlvbj4NCiAgICA8Y29udGVudCBJRD0iTm90ZTE1Ij4NCiAgICAgIDxjb250ZW50Pg0KICAgICAgICA8Y29udGVudCBzdHlsZUNvZGU9InhMYWJlbCI+Rm9ybWF0dGluZyBvZiB0aGlzIG5vdGUgbWlnaHQgYmUgZGlmZmVyZW50IGZyb20gdGhlIG9yaWdpbmFsLjwvY29udGVudD4NCiAgICAgICAgPGJyIC8+Tm8gUFBDIHBhdGllbnQgcGVyIG51cnNlPC9jb250ZW50Pg0KICAgICAgPGJyIC8+DQogICAgICA8Y29udGVudCBzdHlsZUNvZGU9InhMYWJlbCI+TWVyZWRpdGggR3JheSwgTUQ8L2NvbnRlbnQ+DQogICAgICA8YnIgLz4NCiAgICA8L2NvbnRlbnQ+DQogIDwvaXRlbT4NCjwvbGlzdD4="
}
}
FilteredMedication
{
"project_id": "0013ba33-109c-411b-b6f1-48f3c1c9a0bd",
"patient_id": "2bd31f48-4f59-442f-8657-e31017a56235",
"filtered_medication_id": "d485aeefae78f586b9e8c8ec9c7452e7363d8a81d4bc3aa0598c1bb196024c76",
"medication_name": "acidophilus/citrus pectin (BACID) Tab tablet",
"statement_start_date": "",
"primary_medication_code": "579247",
"ndc_code": "17856-7180-20",
"rxnorm_code": "579247",
"statement_dose_route": "Oral",
"statement_dose_value": 1,
"statement_dose_unit": "",
"statement_status": "ACTIVE\n",
"patient_instructions": "\u003cdiv xmlns=\"http://www.w3.org/1999/xhtml\"\u003eTake 1 tablet by mouth daily.\u003c/div\u003e",
"medication_group": "Oral",
"class_1_code": "",
"class_1_name": "",
"class_2_code": "",
"class_2_name": "",
"class_3_code": "",
"class_3_name": "",
"class_4_code": "",
"class_4_name": "",
"brand_name": "",
"prescriber_name": "Meredith Gray"
}
Immunization
{
"name": "Influenza, seasonal, injectable, preservative free",
"dosage_value": 0.5,
"dosage_unit": "mL",
"manufacturer_name": "pfizer",
"occurrence_time": "2020-03-31T14:17:17"
}
Lab
{
"name": "Microalbumin, Urine Random",
"value": "3.4",
"unit": "mg/dL",
"date": "2013-10-01T00:00:00+00:00",
"text": "<div xmlns=\"http://www.w3.org/1999/xhtml\"><td ID="Result.f770af6fa6dc4ae199e16fcc78a4d89f.Comp1Name">Microalbumin, Urine Random</td>\r\n<td>\r\n <content>3.4</content>\r\n</td>\r\n<td>mg/dL</td>\r\n<td />\r\n<td>10/01/2013</td>\r\n<td>Sandbox Hospital</td>\r\n<td ID="Result.f770af6fa6dc4ae199e16fcc78a4d89f.Comp1Signature" /></div>"
}
Location
{
"name": "Sandbox Hospital",
"city": "Brooklyn",
"state": "New York",
"zip_code": "11111",
"address": "456 Sandbox Ave",
"location_type": "Lab",
"location_type_code": "unknown",
"location_type_code_system": "http://terminology.hl7.org/CodeSystem/data-absent-reason",
"location_id": "2deee37e-aef2-4fae-82d9-cc00e1310e95",
"secondary_code_data": [
{
"type": "Lab",
"code": "unknown",
"code_system": "http://terminology.hl7.org/CodeSystem/data-absent-reason"
}
]
}
Medication
{
"name": "insulin glargine (LANTUS) 100 UNIT/ML injection",
"dosage": "10 U",
"route": "Subcutaneous",
"start_date": "2009-04-01",
"end_date": "",
"family": "Not Available",
"medication_id": "dc38f51b-8887-43f6-a87b-e37195328f00",
"cadence": "Not Available",
"prescriber": "Not Available",
"order_date": "Not Available",
"status": "ACTIVE",
"code": "311041",
"code_system": "RxNorm",
"all_names_and_codes": [
{
"name": "insulin glargine (LANTUS) 100 UNIT/ML injection",
"code": "311041",
"code_system": "RxNorm"
},
{
"code": "285018",
"code_system": "RxNorm"
},
{
"code": "0088-2220-33",
"code_system": "NDC"
},
{
"code": "70789",
"code_system": "UNK"
},
{
"code": "27104003002020",
"code_system": "UNK"
},
{
"code": "70789",
"code_system": "UNK"
}
]
}
Medication Alert
{
"type": "CodeSystem",
// below are medication IDs
"medications": [
"1ac225cd-67cc-488a-af60-a63948510149",
"4f404d6f-96cb-44ba-8758-ef800f5d97fa",
"6bbb04ee-0b00-4f77-9864-dc63ad33ca30"
]
}
MedRec
{
"medication_id": "683d330a-c3d1-431b-9fce-0fe0bc66afab",
"brand_name": "Ketorolac Tromethamine",
"generic_name": "KETOROLAC TROMETHAMINE",
"drug_name": "1 ML ketorolac tromethamine 30 MG/ML Injection",
"class_1_code": "M",
"class_1_name": "MUSCULO-SKELETAL SYSTEM",
"class_2_code": "M01",
"class_2_name": "ANTIINFLAMMATORY AND ANTIRHEUMATIC PRODUCTS",
"class_3_code": "M01A",
"class_3_name": "ANTIINFLAMMATORY AND ANTIRHEUMATIC PRODUCTS, NON-STEROIDS",
"class_4_code": "M01AB",
"class_4_name": "Acetic acid derivatives and related substances",
"product_ndc": "0409-3795",
"package_ndc": "0409-3795-01",
"normlaized_package_ndc": "00409379501",
"rx_norm_code": "1665461",
"text": "<div xmlns=\"http://www.w3.org/1999/xhtml\">30 mg Once, Intravenous, STAT, 12/01/2007, For 1 dose</div>",
"instructions": "300 mg at bedtime. GABAPENTIN, 300MG (Oral Capsule)",
"dosage": "30 mg",
"route": "",
"start_date": "2007-12-01",
"end_date": "2007-12-02",
"status": "COMPLETED",
}
Procedure
{
"name": "HC BASIC METABOLIC PANEL (CA TOTAL)",
"code": "80048",
"code_system": "CPT-4",
"date": "2009-07-01",
"reported_date": "Reported Date",
"provider_id": "667226d9-da5d-44e6-9c73-58dbb3fb252f",
"provider_given_name": "Jane",
"provider_family_name": "Doe",
"provider_suffix": "MD",
"provider_address": "123 Main Street",
"provider_city": "Springfield",
"provider_state": "MI",
"provider_phone": "1238675309",
//base64 encoded
"notes": "PGRpdiB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMTk5OS94aHRtbCI+Jmx0O3RkJmd0Ow0KICAmbHQ7Y29udGVudCBJRD0mcXVvdDtwcm9jZWR1cmUxMjVuYW1lJnF1b3Q7Jmd0O01JQ1JPQUxCVU1JTiwgVVJJTkUgUkFORE9NIFcvQ1JFQVRJTklORSZsdDsvY29udGVudCZndDsNCiZsdDsvdGQmZ3Q7DQombHQ7dGQmZ3Q7VG9kYXkmbHQ7L3RkJmd0Ow0KJmx0O3RkJmd0OzEwLzAxLzIwMTMmbHQ7L3RkJmd0Ow0KJmx0O3RkJmd0Ow0KICAmbHQ7cGFyYWdyYXBoJmd0O0h5cGVydGVuc2l2ZSBoZWFydCBhbmQgY2hyb25pYyBraWRuZXkgZGlzZWFzZSB3aXRoIGhlYXJ0IGZhaWx1cmUgYW5kIHN0YWdlIDEgdGhyb3VnaCBzdGFnZSA0IGNocm9uaWMga2lkbmV5IGRpc2Vhc2UsIG9yIHVuc3BlY2lmaWVkIGNocm9uaWMga2lkbmV5IGRpc2Vhc2UgKEhDQykmbHQ7L3BhcmFncmFwaCZndDsNCiAgJmx0O3BhcmFncmFwaCZndDtIZWFydCBmYWlsdXJlLCB1bnNwZWNpZmllZCAoSENDKSZsdDsvcGFyYWdyYXBoJmd0Ow0KJmx0Oy90ZCZndDsNCiZsdDt0ZCZndDsNCiAgJmx0O3BhcmFncmFwaCBzdHlsZUNvZGU9JnF1b3Q7Qm9sZCZxdW90OyZndDtSZXN1bHRzIGZvciB0aGlzIHByb2NlZHVyZSBhcmUgaW4gdGhlJmx0O2NvbnRlbnQgc3R5bGVDb2RlPSZxdW90O3hMaW5rMi1SZXN1bHQuZjc3MGFmNmZhNmRjNGFlMTk5ZTE2ZmNjNzhhNGQ4OWYmcXVvdDsmZ3Q7cmVzdWx0cyBzZWN0aW9uJmx0Oy9jb250ZW50Jmd0Oy4mbHQ7L3BhcmFncmFwaCZndDsNCiZsdDsvdGQmZ3Q7PC9kaXY+",
"all_names_and_codes": [
{
"name": "HC BASIC METABOLIC PANEL (CA TOTAL)",
"code": "80048",
"code_system": "CPT-4"
}
]
}
Practitioner
{
"practitioner_id": "b03acaf3-a6fb-4e71-b21e-1bb934a723cb",
"given_name": "Meredith",
"family_name": "Gray",
"suffix": "MD",
"address": "456 Sandbox Ave",
"city": "Brooklyn",
"state": "New York",
"phone": "",
"npi": "Not Available"
}
Social History
{
"observation_name": "Tobacco use and exposure",
"observation_code": "229819007",
"observation_code_system": "SNOMED-CT",
"observation_value":"Smokeless tobacco non-user",
"observation_value_code": "451381000124107",
"observation_value_code_system": "SNOMED-CT",
"observation_time": "2010-05-11T14:45:00+00:00",
"all_observation_names_and_codes": [
{
"name": "Tobacco use and exposure",
"code": "229819007",
"code_system": "SNOMED-CT",
},
{
"name": "Smokeless tobacco status",
"code": "88031-0",
"code_system": "LOINC",
},
],
"all_observation_value_names_and_codes": [
{
"name": "Smokeless tobacco non-user",
"code": "451381000124107",
"code_system": "SNOMED-CT",
},
],
}
VitalSign
{
"name": "Body height",
"observation_time": "2013-03-01",
"value": "162.600000",
"unit": "cm",
"text": "Height162.6 cm (5' 4\")03/01/2013",
"code": "8302-2",
"code_system": "LOINC",
"all_names_and_codes": [
{
"name": "Body height",
"code": "8302-2",
"code_system": "LOINC"
}
]
}
Updated 1 day ago