Documents

Base URL: https://api.welkinhealth.com/{tenantName}/{instanceName}/patients/{patientId}/documents

The Documents API allows uploading, retrieving, and managing patient documents.

---

Upload Document

POST /patients/{patientId}/documents

Uploads a document file for a patient. Use multipart/form-data encoding.

Path Parameters

Parameter	Type	Required	Description
patientId	string	Yes	ID of the patient

Request Body (multipart/form-data)

Field	Type	Required	Description
file	file	Yes	The document file
documentTypeName	string	Yes	Document type programmatic name
title	string	Yes	Document title
description	string	No	Optional description
expirationDate	string (YYYY-MM-DD)	No	Expiration date

Example Request

curl -X POST "https://api.welkinhealth.com/acme/live/patients/pt_7f3a9b2c-1d4e-4f8a-b5c6-d7e8f9a0b1c2/documents" \
  -H "Authorization: Bearer {access_token}" \
  -F "file=@lab_results.pdf" \
  -F "documentTypeName=lab_results" \
  -F "title=March 2026 Lab Results" \
  -F "description=CBC and metabolic panel"

Example Response

{
  "id": "doc_a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "patientId": "pt_7f3a9b2c-1d4e-4f8a-b5c6-d7e8f9a0b1c2",
  "documentTypeName": "lab_results",
  "title": "March 2026 Lab Results",
  "description": "CBC and metabolic panel",
  "fileName": "lab_results.pdf",
  "fileSize": 204800,
  "mimeType": "application/pdf",
  "uploadedBy": "usr_1a2b3c4d-5e6f-7890-abcd-ef1234567890",
  "uploadedAt": "2026-03-19T10:00:00Z",
  "expirationDate": null
}

---

Get All Documents for Patient

GET /patients/{patientId}/documents

Returns a paginated list of documents for a patient.

Path Parameters

Parameter	Type	Required	Description
patientId	string	Yes	ID of the patient

Query Parameters

Parameter	Type	Required	Description
documentTypeName	string	No	Filter by document type
uploadedBy	string	No	Filter by uploader user ID
startDate	string (ISO 8601)	No	Filter from upload date
endDate	string (ISO 8601)	No	Filter to upload date
page	integer	No	Page number (default: 0)
size	integer	No	Page size (default: 20)

Example Request

curl -X GET "https://api.welkinhealth.com/acme/live/patients/pt_7f3a9b2c-1d4e-4f8a-b5c6-d7e8f9a0b1c2/documents?documentTypeName=lab_results" \
  -H "Authorization: Bearer {access_token}"

Example Response

{
  "content": [
    {
      "id": "doc_a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "patientId": "pt_7f3a9b2c-1d4e-4f8a-b5c6-d7e8f9a0b1c2",
      "documentTypeName": "lab_results",
      "title": "March 2026 Lab Results",
      "fileName": "lab_results.pdf",
      "fileSize": 204800,
      "uploadedAt": "2026-03-19T10:00:00Z"
    }
  ],
  "totalElements": 1,
  "totalPages": 1,
  "page": 0,
  "size": 20
}

---

Get Document by ID

GET /patients/{patientId}/documents/{documentId}

Returns metadata for a specific document.

Path Parameters

Parameter	Type	Required	Description
patientId	string	Yes	ID of the patient
documentId	string	Yes	ID of the document

Example Request

curl -X GET "https://api.welkinhealth.com/acme/live/patients/pt_7f3a9b2c-1d4e-4f8a-b5c6-d7e8f9a0b1c2/documents/doc_a1b2c3d4-e5f6-7890-abcd-ef1234567890" \
  -H "Authorization: Bearer {access_token}"

Example Response

{
  "id": "doc_a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "patientId": "pt_7f3a9b2c-1d4e-4f8a-b5c6-d7e8f9a0b1c2",
  "documentTypeName": "lab_results",
  "title": "March 2026 Lab Results",
  "description": "CBC and metabolic panel",
  "fileName": "lab_results.pdf",
  "fileSize": 204800,
  "mimeType": "application/pdf",
  "uploadedBy": "usr_1a2b3c4d-5e6f-7890-abcd-ef1234567890",
  "uploadedAt": "2026-03-19T10:00:00Z",
  "expirationDate": null
}

---

Download Document

GET /patients/{patientId}/documents/{documentId}/file

Returns the binary file content of the document.

Example Request

curl -X GET "https://api.welkinhealth.com/acme/live/patients/pt_7f3a9b2c-1d4e-4f8a-b5c6-d7e8f9a0b1c2/documents/doc_a1b2c3d4-e5f6-7890-abcd-ef1234567890/file" \
  -H "Authorization: Bearer {access_token}" \
  --output lab_results.pdf

Returns binary file data with appropriate Content-Type header.

---

Delete Document

DELETE /patients/{patientId}/documents/{documentId}

Permanently deletes a document.

Path Parameters

Parameter	Type	Required	Description
patientId	string	Yes	ID of the patient
documentId	string	Yes	ID of the document

Example Request

curl -X DELETE "https://api.welkinhealth.com/acme/live/patients/pt_7f3a9b2c-1d4e-4f8a-b5c6-d7e8f9a0b1c2/documents/doc_a1b2c3d4-e5f6-7890-abcd-ef1234567890" \
  -H "Authorization: Bearer {access_token}"

Example Response

204 No Content