Overview

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

The metadata part must be a JSON string with the following fields:

Valid confidentiality_code Values

Supported MIME Types

application/xml, application/pdf, application/json, text/xml, text/plain, text/html, text/csv, image/jpeg, image/png, image/tiff, image/gif, application/dicom, application/x-hl7, application/msword, application/vnd.ms-excel, multipart/related

Multipart File - “file” - required
Multipart Field - “metadata” (JSON string) - required
{
    “patient_id”: “examplepatientid1”,
    “document_id”: “encounter_summary123”,
    “type”: “CLINICAL”,
    “title”: “History_Of_Immunization_Testingson_20200304.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”
}

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: