API documentation

Reason Codes

Reason codes are the stable explanation vocabulary attached to governed outcomes. They help humans, support workflows, and audit systems understand why Decionis allowed, blocked, escalated, or requested review.

Contract

Treat reason codes as explanation metadata. Applications should enforce the decision status or outcome, then display or store reason codes for audit context.

Stable vocabulary

Published reason codes are not repurposed. Minor releases can add new codes when new protocol behavior becomes observable.

Audit friendly

Codes are uppercase, category-backed, and safe to persist in Decision Dossiers, support tickets, and downstream logs.

Not policy logic

A code can say policy matched or review is required. It does not expose the underlying policy rule or threshold.

Catalog route

Use the catalog route to populate admin UI labels, support runbooks, and typed SDK enums.

GET/v1/protocol/reason-codesPublic

Return the current Decionis reason-code catalog with category, title, description, and stability fields.

curl https://api.decionis.com/v1/protocol/reason-codes

{
  "service": "decionis-protocol",
  "protocol_version": "1.0.0",
  "custom_reason_codes_supported": true,
  "stability": "Stable codes will not be repurposed; new codes may be added in minor releases.",
  "reason_codes": [
    {
      "code": "POLICY_MATCHED",
      "category": "policy",
      "title": "Policy matched",
      "description": "A Decionis policy rule matched the submitted execution intent.",
      "stability": "stable"
    }
  ]
}

Execution handling

Branch on the governed outcome. Use reason codes for display, audit, and escalation notes.

Outcome	Application action	Reason-code role
APPROVE	Continue execution.	Explain why the gate allowed the action.
REJECT	Stop execution.	Explain why the gate blocked the action.
ESCALATE	Hand off to a reviewer.	Explain the escalation path and context.
REVIEW	Pause for review.	Explain missing evidence or review posture.

SDK boundary

SDKs should expose reason codes, but they should not turn them into local policy engines.

Enforce the Decionis response

SDK callers should use evaluate or enforce, then store reason_codes alongside the Decision Dossier link. See https://docs.decionis.com/decision-evaluation for the response shape and https://docs.decionis.com/overrides for review and appeal trails.

On this page

evaluate.sh

Evaluate a decision

curl -X POST \
  https://api.decionis.com/v1/protocol/evaluate-decision \
  -H "Authorization: Bearer $DECIONIS_API_KEY" \
  -H "Idempotency-Key: refund-ord_84f21" \
  -d '{
    "decision_type": "ISSUE_REFUND",
    "amount": 1200,
    "mode": "ENFORCEMENT"
  }'

One call → APPROVE, ESCALATE, REJECT, or REVIEW, with a signed dossier.

Browser sandbox · deterministic · nothing leaves this page. The sample above runs against the live API with your key.

Category	Examples	Use
outcome	PROTOCOL_OUTCOME_APPROVE, PROTOCOL_OUTCOME_ESCALATE	Normalize the Decionis verdict across SDKs and native surfaces.
policy	POLICY_MATCHED, POLICY_GUARD_BLOCKED, MISSING_ORG_POLICY_BUNDLE	Explain policy resolution and provisioning posture.
risk	RISK_WITHIN_THRESHOLD, RISK_THRESHOLD_EXCEEDED	Summarize risk signal posture without exposing thresholds.
review	HUMAN_REVIEW_REQUIRED, MANUAL_VERIFICATION_REQUIRED	Drive reviewer handoff copy and queue routing.
override	OVERRIDE_APPROVED, OVERRIDE_REJECTED	Connect override outcomes to the original Decision Dossier.
system	PROTOCOL_ERROR	Route operational errors to support runbooks.