Requests

Decisions & approvals

Plenty of requests exist to get one thing: a yes, a no, or a 'not like that'. The decision question captures that verdict in a shape your automation can branch on directly, without guessing which field held the answer.

Why a special question

Every choice already has an option key, so a workflow can branch on any radio. What a workflow cannot do is know, across every form that has an approval, which key means “yes”: one author’s radio says sign_off, another’s approved.

The decision question fixes the names. It is a single-choice question with the field key decision, whose three options carry the option keys approve, decline and changes. Its labels stay yours to reword and translate; the keys underneath never move. When the recipient picks one, the request ends with an outcome. Any radio keyed decision whose options carry those three keys counts — the preset just sets them for you.

Add one to your form

1
Open the block menu
Press / in the editor and pick Decision — "Approve, decline, or request changes".
2
Reword the labels
You get a question titled "Do you approve?" with the choices Approve, Decline, and Request changes. Rewrite any of them to your own wording — "Sign off", "Reject", "Send back for edits". Translate them like any other content.
3
Ask why, if you need to
A verdict alone rarely explains itself. Add a long-text question after it, and show it only for decline and changes with conditional logic.
4
Publish
Requests created from this published version end with an outcome. Like every field key, decision only exists once the form is published.

Only the preset produces an outcome

The outcome is read from the question whose field key is decision, and only when the chosen option’s key is one of the three. A radio you build by hand with options labelled Approve, Decline and Changes derives exactly those keys, so it works without the preset; a radio with other labels works once you type the three keys in the Keys table.

Delete one of the three options, or retype its key, and publishing warns you: “The decision question is missing an approve, decline or changes option, so requests can complete without an outcome.” All three must be there — a decision that can only approve cannot decline.
A decision question inside a repeating group is an ordinary question and is ignored for the outcome.

The three values

Value	Default label	Means
approve	Approve	The recipient agreed. Your run continues down the happy path.
decline	Decline	They said no. The request still completes — decline is a verdict, not a failure.
changes	Request changes	They want something altered before they agree. Usually the cue to send a new request.

These three values are a public contract, like a field key: an automation, an agent, and a spreadsheet formula all read them. Add a fourth option and picking it is an ordinary answer, not a verdict — that request completes with no outcome, rather than with a value your receiver has never heard of.

Where the outcome shows up

Surface	What you get
Callback	outcome on the request block of the request.completed payload — absent when there is no verdict.
requests.get	outcome next to status, plus the answers keyed by field key.
requests.list	An outcome filter; passing one implies completed requests only.
Requests page	An Outcome filter, and Approved / Declined / Changes requested on the request itself.
Submissions	The verdict is also an ordinary answer, under the field key decision.

request.completed, trimmed

json

{
  "id": "evt_...",
  "type": "request.completed",
  "test": false,
  "data": {
    "request": {
      "id": "kd7...",
      "externalId": "run-42",
      "status": "completed",
      "outcome": "changes",
      "context": { "case_id": "CASE-9" }
    },
    "answers": {
      "decision": "changes",
      "reason": "Please split the line items per site."
    }
  }
}

Branch on data.request.outcome. status says whether the request finished; outcome says what the recipient decided. An expired or canceled request has a status and no outcome, and so does a completed request on a form without a decision question.

From an agent

The MCP tool is editor_insertDecisionQuestion, taking a title and the three labels in the form’s language. An agent that cannot host a callback endpoint polls request_get instead and reads outcome when the status leaves pending. Requests on the MCP server →

Callbacks & signingThe full payload and how to verify it.The Requests pageFilter by outcome and follow one request.Conditional logicAsk for a reason only when it is needed.Question typesEvery other question you can ask.