Skip to main content

Patient Documents via API

Upload documents to a patient record, attach them to orders, or send unassigned documents to Document Management.

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

file

✅

The document, sent as binary

typeId

✅

The Document Type ID from GET /v1/document-types

description

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

GET /v1/patients/{patientId}/documents

List a patient’s documents (filter by typeId)

GET /v1/patients/documents/{id}

Get one document’s details

PUT /v1/patients/documents/{id}

Update the document type or description

GET /v1/patients/documents/{id}/download

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

file

✅

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 file or typeId, or an unsupported file type

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

Did this answer your question?