# CaseApp requests

> API endpoints for triggering ad-hoc case tasks, closing case instances, and listing available ad-hoc tasks through the CaseApp v3 API.

## Trigger an ad-hoc case task

Triggers one manually-triggered (ad-hoc) task, identified by its case plan name, on a running Case instance.

POST

`{AutomationCloudURL}/{organizationName}/{tenantName}/pims_/api/v3/caseapp/instances/{instanceId}/tasks/trigger`

### Request headers

| Key | Value |
| --- | --- |
| Authorization | Bearer |
| X-UIPATH-FolderKey | The folder key of the case instance |

### Request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| taskName | string | Yes | The name of the ad-hoc task to trigger, exactly as it resolves in the case plan. Matching is case-sensitive. |
| taskInput | object | No | A free-form JSON object forwarded verbatim to the triggered task as a nested payload, for example approval references or decision data. The platform doesn't interpret or schema-validate this payload, and it isn't bound to the task's declared inputs. |

```
{
  "taskName": "string",
  "taskInput": {}
}
```

### Response code

200 Success (empty body)

### Error responses

| Code | Meaning |
| --- | --- |
| 400 | The request body is missing or invalid. |
| 401 | The caller is not authenticated. |
| 403 | The caller lacks the required permission for this task. |
| 404 | The case instance doesn't exist, or no ad-hoc task with that name exists on the case plan. Only tasks with an "adhoc" entry condition are eligible — other names return 404. |
| 500 | An unexpected server error occurred. |

### Permissions

Requires the `Cases.RunAdhocTasks` permission, authorized at the scope of the stage that owns the requested task.

## Close a case instance

Closes a running Case instance.

POST

`{AutomationCloudURL}/{organizationName}/{tenantName}/pims_/api/v3/caseapp/instances/{instanceId}/close`

### Request headers

| Key | Value |
| --- | --- |
| Authorization | Bearer |
| X-UIPATH-FolderKey | The folder key of the case instance |

### Response codes

| Code | Meaning |
| --- | --- |
| 200 | The instance transitioned to `Canceling`. The worker completes the shift to `Cancelled` asynchronously. An already-terminal instance returns its current status unchanged. |
| 400 | The instance has already reached `Completed` and can't be cancelled. |
| 401 | The caller is not authenticated. |
| 403 | The caller lacks the required permission for this instance. |
| 404 | The instance ID doesn't resolve to a case instance. |

### Permissions

Requires the `Cases.Close` persona grant.

## List the ad-hoc tasks you can run on a case

Lists the ad-hoc tasks a caller is permitted to trigger on a case instance, grouped by the stage that owns each task.

GET

`{AutomationCloudURL}/{organizationName}/{tenantName}/pims_/api/v3/caseapp/instances/{instanceId}/tasks/adhoc`

### Request headers

| Key | Value |
| --- | --- |
| Authorization | Bearer |
| X-UIPATH-FolderKey | The folder key of the case instance |

### Response body

Returns the ad-hoc tasks the caller can trigger, grouped by the stage that owns them. Stages without a task the caller can trigger are omitted, so an empty `stages` list means the caller can't trigger any task on this case.

| Field | Type | Description |
| --- | --- | --- |
| stages | array | The stages that contain at least one task the caller can trigger. |
| stages[].stageId | string | The stage's case plan node ID. Can be `null`. |
| stages[].stageLabel | string | The stage's label in the case plan. |
| stages[].tasks | array | The stage's ad-hoc tasks, in case plan order. |
| stages[].tasks[].taskName | string | The task's name, to pass as `taskName` when calling [Trigger an ad-hoc case task](#trigger-an-ad-hoc-case-task). Matching is case-sensitive. |
| stages[].tasks[].taskId | string | The task's case plan node ID. Can be `null`. The trigger endpoint doesn't accept it. |

```
{
  "stages": [
    {
      "stageId": "string",
      "stageLabel": "string",
      "tasks": [
        {
          "taskName": "string",
          "taskId": "string"
        }
      ]
    }
  ]
}
```

A listed task is one the caller is authorized to trigger, but the trigger can still fail. For example, triggering a task on a completed case returns 404.

### Response codes

| Code | Meaning |
| --- | --- |
| 200 | The list was returned. It can be empty. |
| 400 | The `X-UIPATH-FolderKey` header is missing or invalid. |
| 401 | The caller is not authenticated. |
| 403 | The caller has no `Cases.RunAdhocTasks` grant related to this case. |
| 404 | The instance doesn't exist in the folder specified in `X-UIPATH-FolderKey`, or it isn't a case instance. |
| 500 | The case plan couldn't be read, or an unexpected server error occurred. |

### Permissions

Requires the `Cases.RunAdhocTasks` permission, authorized at the scope of the stage that owns each listed task.