Approval routing
What this page is — the capability that scores a document's risk from 0 to 100 and recommends how heavy its approval should be, plus which reviewer roles that route needs and why.
What it is for — so a boilerplate NDA does not consume the same three approvers as a twelve-million-pound MSA, and the MSA gets the senior scrutiny that the NDA was absorbing.
The problem it solves — every document gets the same approval chain, so trivial NDAs queue behind senior reviewers while risky agreements get no more scrutiny than they do.
Route: /org/papers/documents/<document>/ai → Comply → Approval routing ·
Permission: Use AI drafting/extraction/Q&A for documents. ·
Utility: papers_approval_router · Cost: 450 credits estimated, 1,800 maximum.
1. What it is
It reads the document and scores it against seven risk drivers:
- Money at stake
- Liability and indemnity breadth
- Missing caps
- One-sided or unusual terms for its family
- Term length and auto-renewal
- Data and confidentiality exposure
- Regulatory sensitivity
From the score it recommends one of three routes, and names the reviewer roles that route needs.
When it is unsure, it pushes the route up, never down. So a high score is not always evidence of
a dangerous document — sometimes it means "there is something here I could not resolve, take a
closer look". Read deviation_summary before treating a 78 as an alarm.
It does not create, shorten or extend an approval chain, and it names reviewer roles, never people. Your organisation's configured approval workflow remains in force regardless of what this returns.
| Does | |
|---|---|
| Approval routing | Recommends how much scrutiny this document warrants |
| Approvals inbox | Where approvals actually happen |
| Lifecycle and transitions | Where the configured chain is defined |
| Risk analysis | Lists the risks. This converts risk into process |
2. Why you would use it
Approval workflows fail in two directions, and most organisations manage both at once: everything routes to everyone, so approval becomes rubber-stamping; or everything routes to nobody, so the one document that needed senior review did not get it.
- It rescues approver attention. A
fast_trackrecommendation on a standard NDA is the finding that frees your general counsel for the documents that need them. suggested_reviewers[]gives a reason per role. Not "send to legal" but "legal_counsel — uncapped liability, no cap". An approver who knows why they were added reviews differently.- It catches the quiet commitment. A three-year auto-renew on a modest annual value is a large total commitment that no single field on the document shows.
risk_scoreis comparable. Across a portfolio it tells you whether your approval thresholds match the risk you are actually taking on.- Roles, not names, means it survives reorganisation. The recommendation does not go stale when somebody leaves.
3. What you provide
Nothing. It is a one-press capability with no parameters.
| Input | Required | Notes |
|---|---|---|
| — | — | No parameters. It reads the open document |
The score is driven by amounts, caps and term length. An early skeleton with unfilled fields scores low because there is nothing in it to be risky — and a low score on an empty document is exactly the wrong signal to send into an approval decision.
4. What it reads automatically
| Read from the document | Used for |
|---|---|
| Document text — the full rendered body | The seven risk drivers |
| Title & family | Sets what "standard for this family" means — the baseline deviation is measured from |
| Parties — everyone named | Counterparty exposure |
| Key field values — amounts, term, dates | Money at stake, term length, auto-renewal |
The Title & family row is the one that makes the score meaningful: an uncapped liability is
unremarkable in one family and a red flag in another.
5. What you get back
| Field | Type | Values | Means |
|---|---|---|---|
risk_score | number | 0–100 | 0–30 boilerplate-standard · 31–70 notable positions · 71–100 material exposure |
deviation_summary | string, 2–4 sentences | — | Where this document departs from a standard one of its family — the drivers of the score. Says so when it is standard |
recommended_route | enum | fast_track, standard, enhanced | fast_track = a single approver suffices · standard = your normal chain · enhanced = add senior legal, finance or executive scrutiny |
rationale | string, 2–3 sentences | — | Ties the score to the route |
suggested_reviewers[] | array | — | The reviewer roles the route needs, most critical first, each with a one-sentence why. Roles only — never person names |
advisory | string | — | That this is a recommendation and the configured workflow still governs |
The three score bands are what make the number usable. A 78 is not "quite bad"; it is inside the material-exposure band, which is a different category of document.
6. Worked example
A commercial team is about to route a master services agreement for approval.
Input: none.
Result:
risk_score:
78— recommended_route:enhancedsuggested_reviewers: ·
legal_counsel— uncapped liability, no cap ·finance_controller— 3-year auto-renew commitment
What the team does with it. 78 sits in the material-exposure band, and the two reasons are specific enough to act on without re-reading the document. The team adds both roles to the approval before submitting.
The finance_controller line is the one that earns the run. The annual value on this MSA is modest
and would not, by itself, have triggered a finance review under the organisation's thresholds. The
three-year auto-renew makes the committed value three times the annual figure — a fact that
appears on no single field of the document, and which nobody had spotted.
The configured workflow still governs: adding those reviewers is an action a person takes.
7. Running it
- Open the document in Orbit Papers, before routing it for approval.
- Open the AI Assistant drawer, or go to the document's AI workspace.
- Choose Approval routing under Comply.
- The score, route and suggested reviewer roles appear in a result tab and are saved to the document.
Then act on it through the normal approval process. Use the score and route to decide whether to add
scrutiny — and remember it errs upward, so an enhanced recommendation can simply mean take a
closer look.
Available for auto-run from the type's AI Config tab. on_submit is the natural event: the score
is computed exactly when the document enters approvals, so the recommendation is waiting for whoever
routes it. See AI configuration.
8. The admin contract
| Must be true | Where | What happens if it is not |
|---|---|---|
| Your role holds Use AI drafting/extraction/Q&A for documents. | Role editor | The AI Assistant button does not appear |
The papers_approval_router utility is active | Orbit AI Flow → utilities | "This utility is currently disabled" |
| The utility is enabled for your organisation | /org/ai-utilities | Absent from Comply, with no error |
papers.ai_monthly_credit_cap not yet reached | System Config | "monthly AI credit cap reached: n of n credits used this month" |
| An approval chain is configured on the type | Lifecycle and transitions | There is no standard route for it to recommend relative to, and no chain to add reviewers to |
| Reviewer roles exist that match its vocabulary | Role editor | suggested_reviewers[] names roles nobody can map to a person |
The last row is worth checking once: the router names roles in generic terms (legal_counsel,
finance_controller). If your organisation's roles are named differently, somebody has to translate
the recommendation each time.
For a confidential document, auto-run is default-denied — a platform administrator must set
papers.ai_confidential_cloud to the literal allow, and the block appears only in the server log.
A manual press still works, and where a local model key is configured the run is forced on-prem and
audited on the timeline as ai_local_routed.
9. Don't confuse this with…
| Approvals inbox | Where approvals are actually done. This only advises on the route |
| Lifecycle and transitions | Where the real approval chain is configured. This never changes it |
| Risk analysis | Lists specific risks with redlines. This produces one score and a route |
| Fairness / balance | Judges balance between parties. This judges exposure to you |
10. Troubleshooting
| Symptom | Cause |
|---|---|
| The approval chain did not change | It never does. The router recommends; a person acts (§1) |
| A high score on a document that looks routine | It errs upward when uncertain. Read deviation_summary for the actual drivers (§1) |
| A low score on an obviously risky draft | The document is incomplete — no amounts or caps to score against (§3) |
suggested_reviewers[] names roles we do not have | It uses generic role vocabulary. Map them to your own roles (§8) |
It recommends enhanced on every document of a type | Your standard for that family genuinely deviates from market, or the family is set wrongly |
| The score changed with no edit | Field values changed — amounts and term drive the score directly |
| The capability is missing from Comply | Role lacks Use AI drafting/extraction/Q&A for documents., or the utility is off for the organisation (§8). The document type does not gate it — AI Config controls auto-run only |