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
}

/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="
    }
}

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\">&lt;td ID=&quot;Result.f770af6fa6dc4ae199e16fcc78a4d89f.Comp1Name&quot;&gt;Microalbumin, Urine Random&lt;/td&gt;\r\n&lt;td&gt;\r\n  &lt;content&gt;3.4&lt;/content&gt;\r\n&lt;/td&gt;\r\n&lt;td&gt;mg/dL&lt;/td&gt;\r\n&lt;td /&gt;\r\n&lt;td&gt;10/01/2013&lt;/td&gt;\r\n&lt;td&gt;Sandbox Hospital&lt;/td&gt;\r\n&lt;td ID=&quot;Result.f770af6fa6dc4ae199e16fcc78a4d89f.Comp1Signature&quot; /&gt;</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"
        }
    ]
}