Approval by link
Destructive tools (delete, cancel, reach the debtor, report to a credit bureau, protest, accept an agreement, decide a dispute, change a webhook) run only with your confirmation. A client on revision 2026-07-28 that declares form elicitation asks in the chat itself — see Resources and prompts. Many clients do not declare it (the Claude app on a phone, for example). For them, the confirmation happens by link.
How it works
- The assistant calls the destructive tool. The server checks everything it would check to run it: arguments, workspace, the token scopes and your permission. A call that would be refused is refused right away, with no link.
- Instead of running it, the server records the operation as pending and answers the assistant with an approval link. Nothing is executed at that moment.
- The assistant shows the link. You open it signed in to Dunning (if you are not, you sign in and come back to the link).
- The screen shows what will happen ("Cancel charges in bulk", "Send a message to the debtor"), the amount highlighted right below when the operation has one, Requested by (the connected app's identifier, verified through the token; the name the app declares about itself shows separately, marked as not verified), when, the organization and workspace, and the affected records as they are now, with the fields that matter (name, debtor, status, amounts, due date). Everything that will run lists every argument, expanded, and every item of a batch. Data sent that Dunning has no description for shows under Other data sent, with its raw name beside it — and, when it sits inside a described argument (a key of
custom_data, for example), it leaves that argument and shows there by its full path (custom_data.origem) — and a warning says how many there are — check them before continuing. The raw arguments are under Technical details. - Continue runs the operation right away and shows the result. Cancel closes it without running anything. After the decision, the screen shows what was approved or declined, as it was when you decided — a charge deleted or paid afterwards does not change what shows there. If the operation fails, the screen says why in your language, with the code beside it.
Link rules
- It is valid for 15 minutes and decides only once: two clicks on Continue run it once. After the deadline the link shows it expired and nothing is executed; ask the assistant again.
- It opens only for you, signed in to the organization where you asked. For anyone else, including someone in the same organization, the link answers as if it did not exist. If you belong to more than one organization, switch to the right one and open the link again.
- On Continue your permission is checked again: if it was removed, or your access to the workspace, the run fails and nothing is changed. Plan and business rules apply as on any call.
- If the record changed between opening the screen and clicking Continue (the charge was paid, the amount changed), nothing runs: the screen says the data changed. Ask the assistant for the operation again, open the new link and review it.
- The assistant should not call the tool again after getting the link: each call creates a new approval.
What the assistant receives
An ordinary result (not an error), with a single text content holding JSON:
{
"status": "approval_required",
"approval": {
"id": "9a8b7c6d-…",
"url": "https://<Dunning app>/approvals/<token>",
"expires_at": "2026-10-31T12:15:00.000Z"
},
"message": "This operation was NOT executed. It needs the user's approval: show this URL to the user…"
}
The message asks the assistant to show the link, not to repeat the call and, after you say you decided, to read the outcome once with dunning_operation_approvals_get and the approval.id — without polling it in a loop.
Reading the outcome from the assistant
Two read-only tools tell the assistant what happened after the link:
| Tool | Input | Returns |
|---|---|---|
dunning_operation_approvals_get | id (the approval.id) | one approval |
dunning_operation_approvals_list | status, created_after, created_before, page, per_page (all optional) | your approvals, most recent first, with pagination meta |
Each approval carries id, status (pending, approved = in progress, executed, failed, declined = cancelled, expired — a lapsed pending one already reads as expired), action (the tool asked for), title (the screen title, in the request language), resource, operation, amount (when there is one), requested_at, expires_at, decided_at, executed_at, error ({ code, message } when it failed) and result (what the executed operation returned, with secrets masked: a new secret shows only once, on the screen). They never carry the link or its token.
- Only your approvals, in the token's organization and the call's workspace. Another person's or another organization's answers as nonexistent (
NOT_FOUND), the same as an unknown id. - Any connection of yours reaches them, with no role permission nor resource scope of their own: read level is enough. The outcome (
result,errorand the amount read from the record) comes only when the connection can read the operation's resource and you still have permission to read it; otherwise it is null, withresult_hidden: true. - No tool approves, cancels or reopens an approval: deciding happens on the link screen only.
- In the API, the same reads are
GET /v1/operation-approvalsandGET /v1/operation-approvals/{id}.
History
Account → Approvals lists the operations you asked an assistant to run, in the current workspace, with tabs by status (pending, executed, failed, cancelled and expired), the amount of each, who asked and when. You can sort by the columns, filter by resource and by request period (today, last 7, 30 or 90 days), choose the columns and refresh the list; the list comes 20 at a time, with Previous and Next. On a phone each approval is a card. Clicking an approval opens what was decided.
When there is no link
If the token has no person behind it, there is nobody to open the link: the destructive tool is still refused with confirmation_required. If the server cannot record the approval at that moment, the answer is confirmation_unavailable; try again later. See Errors.