Interpret a Decline

When RiskOS™ returns a REJECT or routes a transaction to REVIEW, the response tells you what decision it made but not, at a glance, why. This guide walks the trace path from a decision back to the enrichment scores and reason codes that drove it, so you can explain a decline to a reviewer, an auditor, or an applicant.

Reason code descriptions themselves live in the RiskOS™ Dashboard and the Reason Codes endpoint, not on this page. The steps here get you to the right codes; the last step shows you where to read what they mean.

Prerequisites

• A completed evaluation response from the Evaluation API, with a decision of REJECT or REVIEW.
• Access to the RiskOS™ Dashboard, or a RiskOS™ API key for the Reason Codes endpoint.
• Familiarity with how scores and codes relate — see Reason Codes & Score Interpretation.

Step 1: Read the decision and its tags

Start with the top-level decision fields. Together they tell you the outcome and the signals the workflow attached to it.

For the full field reference, see API Responses.

Step 2: Identify the enrichment that drove the decision

A decision is the combined result of your workflow rules acting on individual enrichment scores — not a single blended number. To find the driver, scan the data_enrichments array for the enrichment whose score crossed the threshold you set in your workflow.

Each enrichment nests its score and codes under an enrichment-specific key inside response:

{
  "decision": "REJECT",
  "decision_tags": ["High Risk"],
  "data_enrichments": [
    {
      "enrichment_name": "Sigma Identity Fraud",
      "response": {
        "fraud": {
          "reasonCodes": ["R201", "R207", "I121"],
          "scores": [
            { "name": "sigma", "version": "1.0", "score": 0.94 }
          ]
        }
      }
    }
  ]
}

Use the enrichment key to map a score back to what it measures — for example, fraud is Sigma Identity Fraud, emailRisk is Email Risk. See the enrichment-to-key table for the full mapping.

Step 3: Read the reason codes for that enrichment

Open the reasonCodes array on the driving enrichment and separate the codes by prefix.

In the previous example, R201 and R207 are the risk drivers; I121 is a corroborating positive. The R and I variants of the same check share a number within an enrichment.

Step 4: Look for clusters, not single codes

Several related R codes are a stronger signal than one in isolation. Multiple correlation failures across name, date of birth, and SSN, for example, point to a more confident decline than a single mismatch. Weigh the cluster, and note any I codes that might justify a step-up instead of an outright rejection.

Reason codes are already factored into the enrichment score — don't add a separate penalty for an R code you see. It's already reflected in the score that crossed your threshold.

Step 5: Look up what each code means

The prefix and enrichment already tell you the direction and the facet of each code. To read the exact description, look the code up in one of these sources:

• RiskOS™ Dashboard — the Reason Codes page lists every code, its description, and the enrichment that produces it. Open it in Sandbox or Production.
• Reason Codes endpoint — call GET /api/reason-codes to pull the catalog programmatically, for example to cache descriptions in your own case management UI. See List Reason Codes.

Verify your interpretation

You've traced the decline correctly when you can state:

• The decision value and the decision_tags attached to it.
• The enrichment whose score crossed your threshold.
• The R codes that drove that score, and their descriptions from the catalog.
• Any I codes that might support a step-up or override.

Record the codes alongside your accept, reject, or review outcome. Logging them creates an audit trail and feeds back into threshold tuning.

Troubleshooting

Related

• Reason Codes & Score Interpretation — how scores and reason codes work
• List Reason Codes — retrieve the catalog programmatically
• Decisions — the ACCEPT, REVIEW, and REJECT outcomes
• API Responses — the full evaluation response schema
• Fraud, Friction, and Acceptance — choosing thresholds