SIGNALS Documentation
API Reference

Approvals Inbox

Review approval requests, follow their stage progress, and record decisions or manage pending work.

Overview

The Approvals Inbox is the working queue for decisions raised by approval chains. It shows only requests you are allowed to see, keeps the selected request in the URL, and presents the immutable context captured when the request was created.

Route: /approvals

Open the inbox from the Approvals item in the header. Its badge counts requests in Needs you, including actionable delegated assignments. Visibility follows your permissions and relationship to each request.

Request an approval from a guarded action

When an otherwise valid action is blocked only because approval is required, its menu item remains actionable. Selecting it opens a confirmation that names the approver, explains the notification and outcome flow, and collects any action-specific context. For quote-to-order conversion, optional conversion and shortage notes are captured in that same confirmation.

Choose Submit for approval to create the request. The underlying action does not run until the approval lifecycle authorises it. The requester and assigned approver are notified through the normal approval notification preferences, and the requester can follow the status using Raised by me in the inbox.

Other denials remain non-actionable and show their refusal reason. Integrations should make the same distinction from the available-actions payload: code: approval_required is a requestable hand-off, while permission, state, shortage, and other guard codes are refusals that must be resolved first. New guarded UI actions should use the shared <x-signals.approval-required-action> trigger rather than implementing a bespoke disabled or confirmation state.

Complete a quote-to-order approval through the API

Approval and conversion are separate operations. Final approval records permission to retry; it leaves the rental as a Quote.

  1. The requester calls POST /api/v1/rentals/{rental}/convert_to_order. A 422 with code: approval_required opens the request.
  2. With approvals:read, list GET /api/v1/approval-requests and match subject.id to the rental and transition_key to rental.convert_to_order.
  3. Each assigned approver calls POST /api/v1/approval-requests/{id}/approve with their own token and approvals.act permission plus the approvals:write token ability. Wait until the request status is approved.
  4. The original requester calls POST /api/v1/rentals/{rental}/convert_to_order again with the same API token and body {"approval_request_id": 41}, replacing 41 with the approved request ID. The requester still needs rentals.edit and rentals:write.

The retry checks the original actor, rental, transition, aggregate version and confirmed quote version, then reruns the normal permission, credit, shortage and business guards. It retains the shortage notes captured by the request. Only a successful conversion consumes the approval: the rental becomes an Order and the request becomes completed in the same transaction. A failed retry leaves the approval unconsumed. A changed rental or another actor cannot use the reference. Calling without the reference still returns approval_required; do not automatically loop that request. Dry runs preview the initial guard without consuming a reference.

Work the queue

  • Needs you contains pending assignments you can action, including active delegations.
  • Waiting on others contains other visible pending work, including requests you raised. Managers with approvals.manage see other pending requests here. Active escalation recipients can see their escalated requests here, but cannot decide them unless separately authorised.
  • Done contains completed and other terminal outcomes from the last 30 days. Choose Show older for earlier results. Pages contain up to 50 requests.

Use Escalated, Expired, and Raised by me to narrow the queue. Search matches captured titles and subject labels, requester names and request IDs; search can include older resolved requests. A selected request and the current view can be shared in the URL. Older filter and q links continue to work.

The decision pane presents the reason, captured facts, requester note, evidence, chain progress and history where available. Open record appears when access to the subject permits it. Monetary amounts and financial facts require cost visibility; the inbox does not invent missing figures.

Make a decision

Choose Approve, Request changes, or Reject on an actionable assignment. Request changes and Reject require a comment in the inbox; requesting changes closes this attempt and the requester can submit a new, linked request. Workflow-originated approvals do not support Request changes. If several assignments are actionable, select the assignment first.

The More menu offers actions according to your authority and the request state: approve with an advisory note, delegate or revoke delegation, reassign, add or replace an escalation recipient, send a reminder, or mark due work as expired. Approval with a note records the note but does not enforce a condition. Reminders can be sent once per UTC day per assignment; the menu shows Reminder sent today after delivery. The server checks every decision and operation again before recording it.

For batch approval, Select low-risk selects eligible requests on the current page. Eligibility includes a single non-skipped stage, authority over all pending assignments, no escalation or due deadline, exclusions for high-risk account operations and invoice write-offs, and the optional tenant value cap. See Batch Approvals.

API and MCP

GET /api/v1/approval-requests accepts view=needs|waiting|done, flag=escalated|expired, raised_by_me, search, and older. A view returns policy-scoped meta.counts; include=counts requests counts without a view. The optional include=presentation,context,snapshot,capabilities expansions expose detail appropriate to the viewer; context and snapshot mask cost-sensitive fields without cost visibility. Responses include nullable subject.url when the subject can be opened. Without an inbox view or filters the legacy list behaviour remains available.

POST /api/v1/approval-requests/{id}/request-changes requires approvals.act, the approvals:write token ability and a non-empty comment of at most 1,000 characters. It returns 403 for an unauthorised actor, 409 for a stale or terminal request, and 422 for invalid input or changes_not_supported on workflow approvals. Rejection through REST accepts an optional reason, although the inbox requires one.

The nine curated MCP tools are list-approval-requests, get-approval-request, approve-approval-request, reject-approval-request, request-approval-changes, bulk-approve-approval-requests, delegate-approval, revoke-approval-delegation, and remind-approval-assignee. They use the same permissions and lifecycle checks as REST.

Permissions

Ability Grants
approvals.view Open the inbox and see policy-scoped requests
approvals.act Approve, request changes, reject, or delegate actionable assignments
approvals.manage Use operational controls such as reassign, escalate, remind, and expire
costs.view plus role cost visibility See cost-sensitive request and financial-impact values

External recipients continue to decide through their signed external approval link; the internal inbox does not replace or alter that portal.