# 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

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

```json
{
  "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

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

```json
{
  "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

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

```json
{
  "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

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

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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.welkinhealth.com/developer-and-integration-guide/api-reference/documents.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.