Minctrl Docs
Cookbook

Prior authorization

Turn a prior-auth request into an approval or a clean determination with the prior-auth example — a medical director signs every denial before it transmits.

Scenario. A prior-authorization request plus the clinical chart come in. When the request meets medical-necessity criteria cleanly (or is gold-carded), it auto-approves. Otherwise a medical director must review the chart and sign the adverse determination before it is transmitted to the provider.

Example: prior-auth · Parks at gate step-id: signoff (gate:medical-director-signoff).

1. Import the example

curl -s -o prior-auth.process.json https://minctrl.com/examples/prior-auth.process.json
jq -n --slurpfile doc prior-auth.process.json '{document: $doc[0]}' \
  | curl -s -X POST "$API/process-templates/import" \
      -H "Authorization: Bearer $TOKEN" \
      -H "Content-Type: application/json" \
      --data-binary @- | jq '{slug, version, executable_violations}'

The example is now a process in your company under the slug prior-auth (see Example processes for registering first).

2. Start the run

RUN=$(curl -s -X POST "$API/process-runs" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "vertical": "prior-auth",
    "draft": true,
    "inputs": {
      "member_id": "M-10293",
      "procedure_code": "27447",
      "diagnosis": "M17.0",
      "risk": "fails criteria"
    }
  }')
RUN_ID=$(echo "$RUN" | jq -r .id)

The run pulls the chart, runs clinical and policy checks concurrently, and — when the request does not meet criteria cleanly — drafts an adverse determination and parks at the medical-director gate. risk is the routing input the resolver matches against the branch labels: "fails criteria" takes the medical-necessity path to the gate; a request that meets criteria is approved and notified without reaching this gate.

3. Read where it parked

curl -s "$API/process-runs/$RUN_ID" -H "Authorization: Bearer $TOKEN"

status is awaiting_human, parked_at is gate:medical-director-signoff, and trace.parked_step is signoff.

4. Resume — the medical director signs

curl -s -X POST "$API/process-runs/$RUN_ID/resume" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "gate": "signoff",
    "decision": "denied",
    "feedback": "Criteria not met: no conservative therapy documented."
  }'

decision is the director's call, recorded on the gate with who signed it and their role. A denial must say why: without a non-blank feedback the API answers 422, and the reason is written next to the signature in the audit trail. A denied verdict also de-authorizes the downstream irreversible transmit — no adverse determination can be sent on the strength of a denial alone.

5. Outcome

After the director's verdict clears the gate, the run takes the rework path: it requests more clinical information (X12 275) and cycles back through intake and review. The resubmitted case reaches the director again, so the run parks at the same gate — trace.parked_visit: 2 — and waits for a fresh verdict: a verdict signs one pass through a gate, never every lap of the loop. The irreversible transmit never auto-fires on a denial.

An approved verdict instead takes the transmit branch (shadowed, see below), moves to monitoring, and parks at the appeal-review gate (appeal-review, gate:appeal-specialist-review). A criteria-meeting request skips signoff but, in the simulated run, also ends up parked at appeal-review: the monitor step's only exit leads there.

Governance note

The transmit step is reversible: false — sending a determination to a provider can't be un-sent — so it stays shadowed until a connector opts in. In a governed rollout the signoff gate collects the director's verdict first; only then is the irreversible transmit authorized.

On this page