- Introduction
- Getting started
- Build on any canvas
- Build with Case
- Reference
- Defining case keys (system vs. external)
- Establishing task I/O and write-back contracts
- Modeling primary and secondary stages
- Triggering a case from Data Fabric
- Implementing stage-level personas and permissions
- Setting SLAs and automated escalation rules
- Configuring a rework loop (re-entry)
- Configuring and testing the Case Manager Agent (preview)
- Build with Flow
- Build with BPMN
- Operating
- Monitoring
- Optimizing
- Reference information
CaseApp requests
API endpoints for triggering ad-hoc case tasks, closing case instances, listing available ad-hoc tasks, and reading a case instance and its status 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": {}
}
{
"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. 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"
}
]
}
]
}
{
"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.
Get a case instance
Returns a single case instance by its ID. The response has the same fields as the v3 instance list, including the case's priority, priority reason, and throttling state.
GET
{AutomationCloudURL}/{organizationName}/{tenantName}/pims_/api/v3/caseapp/instances/{instanceId}
Request headers
| Key | Value |
|---|---|
| Authorization | Bearer |
| X-UIPATH-FolderKey | The folder key of the case instance |
Response codes
| Code | Meaning |
|---|---|
| 200 | The case instance was returned. |
| 400 | The X-UIPATH-FolderKey header is missing or invalid. |
| 401 | The caller is not authenticated. |
| 403 | The caller has no Cases.View grant on this case. |
| 404 | The instance doesn't exist, or it isn't a case instance. |
| 424 | The authorization service couldn't be reached. |
| 500 | An unexpected server error occurred. |
Permissions
Requires the Cases.View permission, granted on the case process or on any of its stages. Every case that the v3 instance list shows can be opened with this request.
Get the status of a case
Returns the full current status of a case in one call: the case status and SLA, the current run of every stage and task the case has reached, failed task runs that haven't been run again, open stage selections, and open incidents that aren't attached to a task.
GET
{AutomationCloudURL}/{organizationName}/{tenantName}/pims_/api/v3/caseapp/instances/{instanceId}/case-status
Request headers
| Key | Value |
|---|---|
| Authorization | Bearer |
| X-UIPATH-FolderKey | The folder key of the case instance |
Response codes
| Code | Meaning |
|---|---|
| 200 | The case status was returned. |
| 400 | The X-UIPATH-FolderKey header is missing or invalid. |
| 401 | The caller is not authenticated. |
| 403 | The caller has no Cases.ViewSummary grant on this case (CaseRbacAccessDenied). |
| 404 | The instance doesn't exist, or it isn't a case instance. |
| 424 | The authorization service couldn't be reached (CaseRbacAuthzUnavailable). |
| 500 | The case state couldn't be read, or an unexpected server error occurred. |
Permissions
Requires the Cases.ViewSummary permission on the case process. No Orchestrator folder permission is needed.
- Trigger an ad-hoc case task
- Request headers
- Request body
- Response code
- Error responses
- Permissions
- Close a case instance
- Request headers
- Response codes
- Permissions
- List the ad-hoc tasks you can run on a case
- Request headers
- Response body
- Response codes
- Permissions
- Get a case instance
- Request headers
- Response codes
- Permissions
- Get the status of a case
- Request headers
- Response codes
- Permissions