Guides
StatusPortal

Documents API

Suggest Edits

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

Description:Creates a new document and stores it in Particle Health's system, or updates an existing document.
Path:api/v1/documents
Method:POST
Content-Type Header:"Content-Type: multipart/form-data"

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

Description:Retrieves a specific document (metadata only) that your organization has uploaded to Particle Health. Can be used to verify that a document has been successfully uploaded.
Path:api/v1/documents/{document_id}
Method:GET

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

Description:Removes a document that your organization has uploaded to Particle Health.
Path:api/v1/documents/{document_id}
Method:DELETE

Example Request

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

Model Response

“delete successful”

List Patient Documents

Description:Retrieves all documents that have been uploaded for a given patient. {patient_Id} is the identifier of the patient in your system or Particle Patient ID.
Path:api/v1/documents/patient/{patient_id}
Method:GET

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:

Code TypeDescriptionResource Link
Format CodeThe code specifying the technical format of the document. There is no value to default to, so this field is required.https://build.fhir.org/ig/IHE/FormatCode/CodeSystem-formatcode.html
Practice Setting CodeThe code specifying the clinical specialty where the act that resulted in the document was performed (e.g., Family Practice, Laboratory, Radiology). If no value is specified, this field will default to “394733009”, which corresponds to “Medical specialty--OTHER--NOT LISTED”https://www.hl7.org/fhir/valueset-c80-practice-codes.html
Healthcare Facility Type CodeThe code specifying the type of organizational setting of the clinical encounter during which the documented act occurred. If no value is specified, this field will default to “394777002”, which corresponds to “Health encounter site--NOT LISTED”.https://www.hl7.org/fhir/valueset-c80-facilitycodes.html
Class CodeThe code specifying the high-level category of document (e.g. Prescription, Discharge Summary, Report, etc.). There is no value to default to, so this field is required.https://www.hl7.org/fhir/r4/valueset-document-classcodes.html
Type CodeThe code specifying the precise type of document from the user perspective (e.g. LOINC code). There is no value to default to, so this field is required.https://www.hl7.org/fhir/r4/valueset-doc-typecodes.html
Confidentiality CodeThe code specifying the security classification of the document. If no value is specified, this field will default to ‘N’ for Normal.https://terminology.hl7.org/2.1.0/CodeSystem-v3-Confidentiality.html

Updated about 2 months ago

What’s Next