Fire a case action

POST

/v2/cases/:uuid/transitions

POST

/api/v2/cases/:uuid/transitions

$ curl -X POST https://api-sandbox.payabli.com/api/v2/cases/9c2b7e14-3a5f-4d21-b8e0-1f6a4c9d2e70/transitions \
>      -H "Content-Type: application/json" \
>      -d '{
>   "trigger": "Approve",
>   "reason": "Account ownership confirmed with the merchant by phone."
> }'

1 {
2   "uuid": "9c2b7e14-3a5f-4d21-b8e0-1f6a4c9d2e70",
3   "state": "Approved",
4   "caseType": "BankAccountChange",
5   "parameters": {
6     "type": "BankAccountChange",
7     "nickname": "Main Settlement Account",
8     "bankName": "First National Bank",
9     "bankToken": "bnk_2b1c9e40f5a34c9a8f219e7c6b1a2d34",
10     "accountType": "Checking",
11     "bankAccountHolderName": "Gruzya Adventure Outfitters LLC",
12     "bankAccountHolderType": "business",
13     "bankAccountFunction": "Deposits",
14     "services": {
15       "moneyIn": [
16         "Ach"
17       ],
18       "moneyOut": [
19         "Ach"
20       ]
21     },
22     "default": true
23   },
24   "orgId": 123,
25   "paypointId": 3040,
26   "scheduleFor": null,
27   "createdAt": "2026-01-15T10:30:00Z",
28   "updatedAt": "2026-01-15T12:15:00Z",
29   "createdBy": 0,
30   "assigneeId": 4238,
31   "lastReviewedById": 4238,
32   "stateHistory": [
33     {
34       "uuid": "019f8100-1a2b-73c4-9d5e-6f7a8b9c0d1e",
35       "caseUuid": "9c2b7e14-3a5f-4d21-b8e0-1f6a4c9d2e70",
36       "fromState": "Assigned",
37       "toState": "Approved",
38       "ipAddress": "203.0.113.10",
39       "triggeredBy": 4238,
40       "reason": "Account ownership confirmed with the merchant by phone.",
41       "createdAt": "2026-01-15T12:15:00Z",
42       "triggeredByUser": {
43         "id": 4238,
44         "name": "Jordan Rivera"
45       }
46     }
47   ],
48   "attachments": [],
49   "roomId": 96370,
50   "metadata": {
51     "verification": {
52       "verificationResult": {
53         "code": 5,
54         "name": "RiskAlert",
55         "description": "The suggested action is to further investigate the bank account and/or customer data for this inquiry due to a risk alert ."
56       },
57       "accountResponseCode": {
58         "code": 12,
59         "name": "_1111",
60         "description": "Account Verified – The account was found to be an open and valid checking account."
61       },
62       "customerResponseCode": {
63         "code": 3,
64         "name": "CA21",
65         "description": "The customer or business name data did not match gAuthenticate data."
66       }
67     },
68     "reviewDecision": null
69   },
70   "org": {
71     "id": 123,
72     "name": "Example Partner Org"
73   },
74   "paypoint": {
75     "id": 3040,
76     "name": "Gruzya Adventure Outfitters"
77   },
78   "createdByUser": null,
79   "assignee": {
80     "id": 4238,
81     "name": "Jordan Rivera"
82   },
83   "lastReviewedBy": {
84     "id": 4238,
85     "name": "Jordan Rivera"
86   }
87 }

Fires a review action on a case, such as Approve, Deny, Escalate, or RequestReview. Assigning a case uses the dedicated assign endpoint, not this one. Firing an action that isn’t valid for the case’s current state returns 409.

Available to Enterprise Partners only.

Path parameters

uuidstringRequiredformat: "uuid"

The case's UUID.

Request

This endpoint expects an object.

triggerenumRequired

A transition action in the case state machine. Assign is fired through the dedicated assign endpoint, not the transitions endpoint.

reasonstringRequired<=1000 characters

The reason for the action.

declineReasonenum or nullOptional

The decline reason. Required when the trigger is Deny, and must be omitted otherwise.

Response

The updated case

uuidstringformat: "uuid"

The case's unique identifier.

stateenum

The state of a case in the bank-account-change lifecycle. Completed and Denied are terminal.

caseTypeenum

Bank account changes are currently the only supported case type.

parametersobject

The bank-account-change details stored on a case. The raw account and routing numbers are write-only and never appear here — only a vault token (bankToken) and non-sensitive details.

orgIdlong

The organization that owns the case.

paypointIdlong

The paypoint the case applies to.

scheduleFordatetime or null

When the change is scheduled to run. Null when not scheduled.

createdAtdatetime

When the case was created.

updatedAtdatetime

When the case was last updated.

createdBylong

The numeric id of the user who created the case. 0 when created by a server-side integration.

assigneeIdlong or null

The numeric id of the assigned reviewer. Null when unassigned.

lastReviewedByIdlong or null

The numeric id of the last reviewer. Null when not yet reviewed.

stateHistorylist of objects

The ordered history of state transitions.

attachmentslist of objects

Files attached to the case.

roomIdlong or null

The id of the message room for the case. Null until provisioned.

metadataobject or null

Case metadata, including the verification outcome. Null until verification completes.

orgobject or null

The resolved organization. Null when not enriched.

paypointobject or null

The resolved paypoint. Null when not enriched.

createdByUserobject or null

The resolved creator. Null when created by a server-side integration or not enriched.

assigneeobject or null

The resolved assigned reviewer. Null when unassigned.

lastReviewedByobject or null

The resolved last reviewer. Null when not yet reviewed.

Errors

400

Bad Request Error

401

Unauthorized Error

403

Forbidden Error

404

Not Found Error

409

Conflict Error

500

Internal Server Error