Reason Codes

When you call the RiskOS™ Evaluation API, each enrichment in your workflow can return reason codes alongside its score. Reason codes are machine-readable flags that explain why an enrichment produced a particular score — for example, a data mismatch, a risky email domain, or a successful address correlation.

Use reason codes to:

• Route transactions to manual review based on specific risk signals
• Display context to reviewers in your case management system
• Drive conditional logic in workflow steps
• Log signals for audit and analytics

View all reason codes

For the complete catalog of reason codes and their descriptions, open the Reason Codes page in the RiskOS™ Dashboard:

Where reason codes appear in the API response

Reason codes are returned per enrichment inside the data_enrichments array of the Evaluation API response. Each enrichment nests its reasonCodes array alongside its score.

The following abbreviated example shows the response portion of a single enrichment (other fields such as enrichment_name and status_code are omitted for clarity):

{
  "referenceId": "abc-123",
  "data_enrichments": [
    {
      "response": {
        "fraud": {
          "reasonCodes": ["IXXX", "IYYY", "IZZZ"],
          "scores": [
            {
              "name": "sigma",
              "version": "1.0",
              "score": 0.196
            }
          ]
        }
      }
    }
  ]
}

The JSON path to reason codes follows the pattern:

data_enrichments[].response.<enrichmentName>.reasonCodes

Where <enrichmentName> is the enrichment-specific key (for example, fraud, emailRisk, addressRisk, or documentVerification).

How to read a reason code

Each reason code has a single-letter prefix followed by a numeric identifier:

For a given check, the I and R versions share the same number. When a particular check passes, you see the I variant; when it flags a risk, you see the R variant instead.

📘

Note:

For the complete catalog of all reason codes, their descriptions, and which enrichment produces each code, see the Reason Codes page in the RiskOS™ Dashboard.

Enrichments that return reason codes

The following enrichments include a reasonCodes array in their response:

Multi-enrichment response example

The following abbreviated response shows reason codes from two enrichments — Sigma Identity Fraud and Address Risk — returned by a single evaluation:

{
  "referenceId": "abc-123",
  "data_enrichments": [
    {
      "response": {
        "fraud": {
          "reasonCodes": ["IXXX", "IYYY", "IZZZ", "RAAA"],
          "scores": [
            {
              "name": "sigma",
              "version": "1.0",
              "score": 0.196
            }
          ]
        },
        "addressRisk": {
          "reasonCodes": ["IBBB", "ICCC"],
          "score": 0.01,
          "scores": [
            {
              "name": "address",
              "version": "10.0",
              "score": 0.01
            }
          ]
        }
      }
    }
  ]
}

In this example:

• Each enrichment returns its own reasonCodes array alongside its score. The Sigma Identity Fraud response uses the key fraud, while Address Risk uses addressRisk.
• The I-prefixed codes indicate checks that passed. The R-prefixed code flags a risk signal that contributed to the score.
• To look up what each code means, see the Reason Codes page in the RiskOS™ Dashboard.

How reason codes relate to scores and decisions

Reason codes have already been factored into the enrichment score — they describe why the model arrived at the score, not additional risks on top of it. Keep these guidelines in mind:

• Do not treat reason codes as standalone risk rules. The score already reflects their impact. For example, if an R-prefixed code appears for Document Verification, that risk signal is already factored into the DocV score — you do not need to add a separate penalty.
• Reason codes expose a subset of model signals. RiskOS™ models evaluate hundreds of predictors. Many are proprietary or not human-readable. Reason codes surface only the factors most useful for operational review.
• The codes returned depend on the data you send. For example, if you pass only name, email, and address (no phone number), you will not receive phone-related reason codes.
• Use reason codes to inform manual review. They are most valuable for transactions near your decision thresholds, where a reviewer needs to understand the risk signal behind the score.

Using reason codes in workflows

You can reference reason codes in your RiskOS™ workflow configuration:

• Condition steps can branch logic based on whether specific reason codes are present in an enrichment response.
• Reason Code steps can attach additional codes to the evaluation outcome based on workflow logic.
• Decision steps can assign reason codes alongside accept, review, or reject decisions.
• Reason Code Lists allow you to group codes into reusable sets and reference them across multiple workflows.