Approval Requests

An approval request is created automatically when an automation rule fires the Require Approval action. It attaches to the record that triggered the rule — a purchase order, invoice, rental agreement, or any other entity — and holds it pending until a user makes a decision. Until someone approves or rejects, the status stays Pending.

Approval requests cannot be created by hand in the UI. They exist only because an automation rule fired and required one. If you need a manual review gate, wire up a rule with the Require Approval action.

What an approval request contains #

Each request carries the full context of the decision waiting to be made:

• Entity — the type of record being held (e.g. PurchaseOrder, RentalAgreement). The record is linked via a polymorphic relationship so a single queue covers every entity type.
• Rule — the automation rule that raised the request. Shows Manual if the originating rule was later deleted.
• Status — a color-coded badge: amber Pending, green Approved, red Rejected.
• Assigned to — the user nominated to decide, if the rule specified one. Unassigned requests can be acted on by any user with the right permissions.
• Requested by — the user whose action triggered the rule.
• Notes — optional context supplied when the request was raised.
• Decision fields — stamped once a decision is made: Decided by, Decided at, and Decision notes (required on rejection, optional on approval).

Finding and filtering requests #

Navigate to Automation → Approval Requests. The table shows each request's status badge, entity type, rule name, assigned user, requesting user, and the timestamp it was created. The list defaults to showing only Pending requests, keeping the queue focused on work that still needs action — use the Status filter to switch to Approved or Rejected to review past decisions.

The table sorts newest-first so freshly raised requests rise to the top. Click any row to open the detail page, which shows all fields plus the full decision record once a decision has been made.

Approving a request #

From the request's detail page, click Approve in the page header. An optional Approval notes field lets you add context before confirming. Submitting flips the status to Approved and stamps Decided by, Decided at, and the notes you provided. The decision is permanent.

Only Pending requests can be approved or rejected. Trying to decide an already-decided request — in the UI or over the API — returns a validation error.

Rejecting a request #

Click Reject from the detail page. A Reason for rejection field is required — this ensures there is always a documented explanation for any denial. The status flips to Rejected and the same decision metadata is recorded.

How approval requests relate to automation rules #

An approval request is always the child of an automation rule. The rule defines the trigger, conditions, and the Require Approval action (including which user to assign). To review all requests raised by a specific rule, filter the list by rule name, or open the rule's own detail page via Automation → Automation Builder.

When a pending approval exists for a record, that record may be blocked from further state changes until the request is resolved. The exact behavior depends on the rule configuration — check the rule's action definition to understand what happens after approval versus rejection.

Doing it from the API #

# List pending approval requests
curl "https://your-domain.com/api/v1/automation/approval-requests?status=pending" \
  -H "Authorization: Bearer $TOKEN"

# Approve a request (notes are optional)
curl -X POST "https://your-domain.com/api/v1/automation/approval-requests/{approvalRequest}/approve" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"decided_by_id": "<user-id>", "notes": "Looks good — within budget."}'

# Reject a request (notes are required)
curl -X POST "https://your-domain.com/api/v1/automation/approval-requests/{approvalRequest}/reject" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"decided_by_id": "<user-id>", "notes": "Exceeds spend limit — resubmit with revised amount."}'

The decision is recorded against the user whose API token made the request, so there is no need to say who decided. decided_by_id is optional and, if sent, must be your own user id — naming a colleague is refused rather than quietly overridden, so an integration cannot record an approval under someone else's name. Give an integration its own service account if you want its decisions attributed to it rather than to a person.

Filter the listing endpoint by status (pending, approved, rejected) or rule_id to scope results to a specific automation rule. Results are paginated at 50 per page and sorted newest-first.