Overview
Upload documents to a patient record, attach them to orders, or send unassigned documents to Document Management for your team to work.
Before You Start: Get the Document Type ID
Every patient document needs a document type.
GET /v1/document-types
Optional query parameters: name, ids, includeArchived, pageIndex and pageSize.
GET /v1/document-types?name=Delivery
{
"Items": [
{ "Id": "91", "Name": "Delivery Ticket", "Archived": false, "IsReadonly": false }
]
}
GET /v1/document-types/dictionary is deprecated. Use GET /v1/document-types instead.
Option 1: Add a Document Directly to a Patient
POST /v1/patients/{patientId}/documents
Use this when you know which patient the document belongs to.
⚠️ This endpoint uses multipart/form-data, not JSON. Send the file as binary in the file field.
Form Fields
Field | Required | Notes |
| ✅ | The document, sent as binary |
| ✅ | The Document Type ID from |
|
| A free-text description |
Example
curl -X POST "https://{your-environment}/api/external/v1/patients/10000105/documents" \
-H "Authorization: Bearer {access_token}" \
-F "file=@delivery_ticket.pdf" \
-F "typeId=91" \
-F "description=Signed delivery ticket"
Response: 201 Created
{ "PatientDocumentId": "838" }
The response also returns an Id field, which is deprecated. Use PatientDocumentId.
Related Endpoints
Endpoint | Purpose |
| List a patient’s documents (filter by |
| Get one document’s details |
| Update the document type or description |
| Download the file |
Option 2: Attach Patient Documents to an Order
PUT /v1/orders/{id}/documents
Once a document is on the patient record, you can attach it to one of that patient’s orders at any time. Use the Order ID in the path and send one or more Patient Document IDs.
PUT /v1/orders/SO05adce00ef4b092b90f42f97b2ec3e36/documents
{
"Documents": [
{ "PatientDocumentId": 838 },
{ "PatientDocumentId": 839 }
]
}
Response: 200 OK
PatientDocumentId is a number in this request, even though the upload response returns it as a string.
To see the documents attached to an order, use GET /v1/orders/{id}/documents.
Option 3: Send Documents to Document Management
POST /v1/document-management/upload
If you don’t know which patient a document belongs to, upload it to Document Management instead. It goes into a shared queue where your team can review it, identify the patient, and file it to the right record in NikoHealth.
Form fields
Field | Required | Notes |
| ✅ | Binary. Allowed types: .txt, .pdf, .png, .jpg, .jpeg, .tif, .tiff |
curl -X POST "https://{your-environment}/api/external/v1/document-management/upload" \
-H "Authorization: Bearer {access_token}" \
-F "file=@unidentified_fax.pdf"
Response: 201 Created
{ "Id": "DMb7b12c001f4b865938f425f778273ea8" }
Optional: Add Notes or Tags to Help Your Team
PUT /v1/document-management/{id}{
"Name": "Unidentified fax - 11-10-2026.pdf",
"Notes": "Received from referral source, patient name unclear",
"TagIds": ["776c4600261b224ba494eab459d8ee00"]
}
Name is required, up to 250 characters. Get tag IDs from GET /v1/document-tags.
Common Errors
Code | Meaning |
400 | Invalid request, such as a missing |
401 | The token is missing, expired or invalid |
403 | You don’t have permission to access this resource |
404 | The patient, order or document wasn’t found |
413 | The file is too large (Document Management upload) |
429 | Too many requests |
