Skip to main content

Preview Approval Routing

POST 
/api/approval-policies/:documentType/preview

Route an amount through a policy without creating anything — answers "who would have to approve this, and could the requester approve it themselves?". Uses the saved policy, or an unsaved draft sent under policy so an edit can be checked before it is saved.

Required scope: purchase-orders:write

Grant this scope to your token under Settings → Developer → Personal Access Tokens.

Authentication: Requires Bearer token with the purchase-orders scope (read for GET, write for POST/PUT/DELETE).

Requires permission: approval_policies.view

Body fields:

  • amount (number, required, min 0) — in base currency
  • requester_user_id (integer, optional, nullable) — evaluate separation of duties and requester_can_approve_directly for this user
  • policy (object, optional, nullable) — an unsaved policy with the same fields as Update Approval Policy (all optional here; tiers must be present for the draft to be used)

Response fields:

  • policy_enabled, requires_approval (false when the amount falls in an auto-approve tier)
  • amount_base, base_currency, tier_name, tier_up_to_amount
  • steps[] — order, name, required_approvals, eligible_users[] (user_id, name, via — step (listed), higher_tier (listed on a higher tier's final step), role:<id> (member of a listed role) or delegate_of:<user id>; on_behalf_of_user_id / on_behalf_of_name for a delegate; self_approval)
  • warnings[] — e.g. a step nobody can approve (it would escalate to administrators)
  • requester_can_approve_directly — the requester could approve every step in one call
  • blocked_reason — why the requester cannot, when they cannot

Request​

Responses​

OK

Response Headers
    Content-Type