# Task Management

**Base URL:** `https://api.welkinhealth.com/{tenantName}/{instanceName}/tasks`

Tasks are action items assigned to care team members. They can be linked to patients, encounters, or programs.

***

## Create Task

**POST** `/tasks`

Creates a new task and assigns it to a care team member.

### Request Body

| Field       | Type                | Required | Description                                 |
| ----------- | ------------------- | -------- | ------------------------------------------- |
| title       | string              | Yes      | Short title of the task                     |
| description | string              | No       | Detailed description                        |
| assigneeId  | string              | Yes      | User ID of the assignee                     |
| patientId   | string              | No       | Associated patient ID                       |
| encounterId | string              | No       | Associated encounter ID                     |
| dueDate     | string (YYYY-MM-DD) | No       | Task due date                               |
| priority    | string              | No       | `HIGH`, `MEDIUM`, `LOW` (default: `MEDIUM`) |
| taskType    | string              | No       | `GENERAL`, `FOLLOW_UP`, `CLINICAL`          |

### Example Request

```bash
POST /acme/live/tasks
Authorization: Bearer {token}
Content-Type: application/json

{
  "title": "Follow up on lab results",
  "description": "Review CBC results and call patient",
  "assigneeId": "usr_3f8a1b2c-4d5e-6f7a-8b9c-0d1e2f3a4b5c",
  "patientId": "pt_7f3a9b2c-1d4e-4f8a-b5c6-d7e8f9a0b1c2",
  "dueDate": "2026-03-25",
  "priority": "HIGH",
  "taskType": "FOLLOW_UP"
}
```

### Example Response

```json
{
  "id": "tsk_a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "title": "Follow up on lab results",
  "description": "Review CBC results and call patient",
  "assigneeId": "usr_3f8a1b2c-4d5e-6f7a-8b9c-0d1e2f3a4b5c",
  "patientId": "pt_7f3a9b2c-1d4e-4f8a-b5c6-d7e8f9a0b1c2",
  "encounterId": null,
  "dueDate": "2026-03-25",
  "priority": "HIGH",
  "taskType": "FOLLOW_UP",
  "status": "OPEN",
  "createdAt": "2026-03-19T14:00:00Z",
  "updatedAt": "2026-03-19T14:00:00Z"
}
```

***

## Get All Tasks

**GET** `/tasks`

Returns a paginated list of tasks. Can be filtered by patient, assignee, status, and more.

### Query Parameters

| Parameter  | Type    | Description                                     |
| ---------- | ------- | ----------------------------------------------- |
| patientId  | string  | Filter by associated patient                    |
| assigneeId | string  | Filter by assignee user ID                      |
| status     | string  | `OPEN`, `IN_PROGRESS`, `COMPLETED`, `CANCELLED` |
| priority   | string  | `HIGH`, `MEDIUM`, `LOW`                         |
| dueDate    | string  | Filter tasks due on this date (YYYY-MM-DD)      |
| page       | integer | Page number (default: 0)                        |
| size       | integer | Page size (default: 20, max: 100)               |

### Example Request

```bash
GET /acme/live/tasks?patientId=pt_7f3a9b2c-1d4e-4f8a-b5c6-d7e8f9a0b1c2&status=OPEN
Authorization: Bearer {token}
```

### Example Response

```json
{
  "data": [
    {
      "id": "tsk_a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "title": "Follow up on lab results",
      "description": "Review CBC results and call patient",
      "assigneeId": "usr_3f8a1b2c-4d5e-6f7a-8b9c-0d1e2f3a4b5c",
      "patientId": "pt_7f3a9b2c-1d4e-4f8a-b5c6-d7e8f9a0b1c2",
      "dueDate": "2026-03-25",
      "priority": "HIGH",
      "taskType": "FOLLOW_UP",
      "status": "OPEN",
      "createdAt": "2026-03-19T14:00:00Z",
      "updatedAt": "2026-03-19T14:00:00Z"
    }
  ],
  "metaInfo": {
    "page": 0,
    "pageSize": 20,
    "totalElements": 1,
    "totalPages": 1
  }
}
```

***

## Get Task by ID

**GET** `/tasks/{taskId}`

Returns a single task by its ID.

### Path Parameters

| Parameter | Type   | Description        |
| --------- | ------ | ------------------ |
| taskId    | string | The unique task ID |

### Example Request

```bash
GET /acme/live/tasks/tsk_a1b2c3d4-e5f6-7890-abcd-ef1234567890
Authorization: Bearer {token}
```

### Example Response

```json
{
  "id": "tsk_a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "title": "Follow up on lab results",
  "description": "Review CBC results and call patient",
  "assigneeId": "usr_3f8a1b2c-4d5e-6f7a-8b9c-0d1e2f3a4b5c",
  "patientId": "pt_7f3a9b2c-1d4e-4f8a-b5c6-d7e8f9a0b1c2",
  "encounterId": null,
  "dueDate": "2026-03-25",
  "priority": "HIGH",
  "taskType": "FOLLOW_UP",
  "status": "OPEN",
  "createdAt": "2026-03-19T14:00:00Z",
  "updatedAt": "2026-03-19T14:00:00Z"
}
```

***

## Update Task

**PATCH** `/tasks/{taskId}`

Updates a task. Only include fields you want to change.

### Path Parameters

| Parameter | Type   | Description        |
| --------- | ------ | ------------------ |
| taskId    | string | The unique task ID |

### Request Body

| Field       | Type   | Description                                     |
| ----------- | ------ | ----------------------------------------------- |
| title       | string | Updated title                                   |
| description | string | Updated description                             |
| status      | string | `OPEN`, `IN_PROGRESS`, `COMPLETED`, `CANCELLED` |
| priority    | string | `HIGH`, `MEDIUM`, `LOW`                         |
| assigneeId  | string | Reassign to a different user                    |
| dueDate     | string | Updated due date (YYYY-MM-DD)                   |

### Example Request

```bash
PATCH /acme/live/tasks/tsk_a1b2c3d4-e5f6-7890-abcd-ef1234567890
Authorization: Bearer {token}
Content-Type: application/json

{
  "status": "COMPLETED"
}
```

### Example Response

```json
{
  "id": "tsk_a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "title": "Follow up on lab results",
  "description": "Review CBC results and call patient",
  "assigneeId": "usr_3f8a1b2c-4d5e-6f7a-8b9c-0d1e2f3a4b5c",
  "patientId": "pt_7f3a9b2c-1d4e-4f8a-b5c6-d7e8f9a0b1c2",
  "encounterId": null,
  "dueDate": "2026-03-25",
  "priority": "HIGH",
  "taskType": "FOLLOW_UP",
  "status": "COMPLETED",
  "createdAt": "2026-03-19T14:00:00Z",
  "updatedAt": "2026-03-19T15:30:00Z"
}
```

***

## Delete Task

**DELETE** `/tasks/{taskId}`

Permanently deletes a task.

### Path Parameters

| Parameter | Type   | Description        |
| --------- | ------ | ------------------ |
| taskId    | string | The unique task ID |

### Example Request

```bash
DELETE /acme/live/tasks/tsk_a1b2c3d4-e5f6-7890-abcd-ef1234567890
Authorization: Bearer {token}
```

### Example Response

```
HTTP 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/task-management.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.