Overview

Description

The Documents API is used to manage documents that are linked to patients within Particle Health's Master Patient Index. Documents can be created, updated, retrieved, and deleted. All documents can also be listed for a given patient. The networks ask for C-CDA documents, but the actual format of the document is typically flexible (typically in XML, which is the format that most EMRs use, but PDFs/scans are also acceptable).

Important Notes

• Each document requires a patient_id, and this patient_id must already exist in Particle's Master Patient Index before a document can be successfully uploaded. See Patients API for more information.
• Details on acceptable document types can be found in the FAQs.
• Successful requests will return a 200 OK, but you can also use a GET request to retrieve a document and verify that it was uploaded successfully.

API Functions

Document Create and Update

Required Fields

Multipart File - “file” - required
Multipart Field - “metadata”
{
    “patient_id”: “examplepatientid1”, - Required
    “document_id”: “encounter_summary123”,  - Required
    “type”: “CLINICAL”,  - Required
    “title”: “History_Of_Immunization_Testingson_20200304.xml”,  - Required
    “mime_type”: “application/xml”, - Required
    “creation_time”: “2020-01-01T12:30:00Z:”, - RFC3339 Formatted, Required
    “format_code”: “urn:ihe:pcc:xphr:2007”, - Required
    “confidentiality_code”: “N”,
    “class_code”: “11369-6”, - Required
    “type_code”: “11369-6”, - Required
    “healthcare_facility_type_code”: “394777002”, 
    “practice_setting_code”: “394733009”, 
    “service_start_time”: “2020-01-01T00:00:00+05:00”, - RFC3339 Formatted
    “service_stop_time”: “2020-01-04T00:00:00-07:00” - RFC3339 Formatted
}

Example Request

curl -X POST “https://api.particlehealth.com/api/v1/documents” \
-H "Authorization: $AuthToken" \
-F "metadata={
    \"patient_id\": \"{patient_id}\",
    \"document_id\": \"encounter_summary123\", 
    \"type\": \"CLINICAL\", 
    \"title\":\"Encounter_Summary_Test.xml\", 
    \"mime_type\":\"application/xml\", 
    \"creation_time\": \"2020-01-01T12:30:00Z\", 
    \"format_code\": \"urn:ihe:pcc:xphr:2007\", 
    \"confidentiality_code\": \"N\", 
    \"class_code\": \"11369-6\", 
    \"type_code\": \"11369-6\", 
    \"healthcare_facility_type_code\": \"394777002\", 
    \"practice_setting_code\": \"394733009\", 
    \"service_start_time\": \"2020-01-01T00:00:00+05:00\", 
    \"service_stop_time\": \"2020-01-04T00:00:00-07:00\"
}" \
-F "file=@$PathToFile"   

Model Response

{
    "patient_id": "examplepatientid1", 
    "document_id": "encounter_summary123", 
    "type": "CLINICAL", 
    "title":"Encounter_Summary_Test.xml", 
    "mime_type":"application/xml", 
    "creation_time": "2020-01-01T12:30:00Z", 
    "format_code": "urn:ihe:pcc:xphr:2007", 
    "confidentiality_code": "N", 
    "class_code": "11369-6", 
    "type_code": "11369-6", 
    "healthcare_facility_type_code": "394777002", 
    "practice_setting_code": "394733009", 
    "service_start_time": "2020-01-01T00:00:00+05:00", 
    "service_stop_time": "2020-01-04T00:00:00-07:00"
}

📘

Note: Learn more about code sets in the response here.

Retrieve Posted Document

Example Request

curl -H “Authorization: $authToken” \
https://api.particlehealth.com/api/v1/documents/encounter_summary123

Response Model

{
	"patient_id": "examplepatientid1", 
	"document_id": "encounter_summary123", 
	"type": "CLINICAL", 
	"title":"Encounter_Summary_Test.xml", 
	"mime_type":"application/xml", 
	"creation_time": "2020-01-01T12:30:00Z", 
	"format_code": "urn:ihe:pcc:xphr:2007", 
	"confidentiality_code": "N", 
	"class_code": "11369-6", 
	"type_code": "11369-6", 
	"healthcare_facility_type_code": "394777002", 
	"practice_setting_code": "394733009", 
	"service_start_time": "2020-01-01T00:00:00+05:00", 
	"service_stop_time": "2020-01-04T00:00:00-07:00"
}

Delete Document

Example Request

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

Model Response

“delete successful”

List Patient Documents

Example Request

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

Model Response

 [ 
	{ Documents Model },
	{ Documents Model },
	{ Documents Model }
]

Code Value Sets

To enable systems to parse and handle documents successfully, all document metadata must include codes to identify the type, format, and content of the data that the document contains. The following value sets should be used wherever possible: