Approval request ( approval_request )
Represents a durable human decision: who must approve, which individual decisions were made, which policy aggregates them, and which terminal outcome allowed the process to resume.
Role
A approval_request is not an email, notification, or simple user action. It is the business fact carrying the aggregated human decision. The channel used to solicit approvers may change without changing this model.
SMTP nodes may resolve contacts and send them an approval link, but the canonical decision lives in
approval_request and ses approval_assignment. A successfully sent email never means “approved”.
One request, one assignment per approver
The company defines the population in which approvers are resolved. The request creates one assignment per selected contact, then aggregates their decisions according to its `approval_mode`.
approver_company_id determines the company whose contacts may carry approval responsibility. Each selected contact receives one approval_assignment distinct assignment with its own status, optional decision, rejection reason, and notification/decision dates.
The request also preserves theid of the process instance and the node_id that created it. It therefore remains traceable to the exact orchestration responsibility that originated the decision.
Approval modes
| Mode | Intention | Observable resolution |
|---|---|---|
first | One positive approval is enough to resolve the request. | The first approval satisfying the mode may resolve the request; a received rejection resolves the request as rejected. |
first_decision | The first usable decision must decide the request. | A received decision may make the request terminal according to the policy applied by the creating node. |
all | All assignments must approve. | The request is approved only when all assignments are approved ; one rejection makes the request rejected. |
The mode does not itself select people. Contact resolution — roles, certification levels, selection strategy, and requester-conflict policy — belongs to the node creating the request.
Lifecycle
| Status | Meaning |
|---|---|
pending | The request is still waiting for a decision or satisfaction of its aggregation policy. |
approved | The approval policy is satisfied. |
rejected | A rejection made the request terminal. |
expired | The deadline expires_at was reached before resolution. |
cancelled | The request was canceled before normal resolution. |
When a request becomes terminal, resolved_at is populated. resolution_assignment points to the assignment that triggered resolution when applicable; other pending assignments are canceled so a late decision can no longer change the outcome.
Do not automatically turn expired into a business rejection. Expiration means “no valid decision before the deadline”; your process must choose whether to remind, escalate, or stop the case.
Approver access
Each assignment may be associated with a temporary capability allowing its approver to review and make a decision. This capability expires with the request and remains distinct from the persisted approval_assignment object.
- The action link is intended for the targeted approver, not to be shared as a public URL.
- A decision already made cannot be replayed to change a request that has become terminal.
- If
rejection_reason_requiredis enabled, a rejection must provide a non-empty reason.
In a process
The nodes request_approval et
request_multiple_approvals create this model after resolving approvers. The instance suspends while waiting and resumes on a route matching the terminal outcome: approval, rejection, expiration, or no eligible approver depending on the node.
L’human approval remains distinct from end-participant user actions: while waiting, the User Journey may display a processing message without asking the journey user to act.
Events
approval_request.created— the request and its assignments are created.approval_request.resolved— the request reaches a non-expired terminal decision.approval_request.expired— the deadline is reached while the request was still pending.
These events expose the public request snapshot and support monitoring or a secondary process independently from the notification channel used.