Reason Codes & Score Interpretation

View reason codes and scores in the Dashboard

To look up any reason code or review the scores returned on a live transaction, use the RiskOS™ Dashboard. The Reason Codes page lists every code, its description, and the enrichment that produces it; per-transaction scores appear on each evaluation in Case Management.

To retrieve the catalog programmatically instead of using the Dashboard, see List Reason Codes.

How reason codes and scores work

When you call the RiskOS™ Evaluation API, each enrichment in your workflow returns a score alongside its reason codes. The score tells you how risky an attribute or identity is; the reason codes are machine-readable flags that explain why the model arrived at that score — for example, a data mismatch, a risky email domain, or a successful address correlation.

Use scores and 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

This page explains how to read a score, how it relates to its reason codes, and how to use both when you integrate and when you review a transaction.

What a risk score represents

Each enrichment that scores an attribute returns a probabilistic risk score — a value between 0.001 and 0.999. A higher score indicates a greater likelihood of fraud or risk for that attribute.

A few enrichments return purpose-specific scores on a 0.0–1.0 scale instead. For example, Account Intelligence returns an ownershipScore (probability the PII matches the true account holder) and an availabilityScore (likelihood the account is open and active). Check each enrichment's integration guide for the exact fields it returns.

📘
Note:
A score is a model output, not a tally you can reconstruct by hand. RiskOS™ models evaluate hundreds of predictors, and the exact predictors and their weightings are proprietary. Reason codes surface the subset of those predictors that are most useful for review — they explain the score, but they are not the complete formula behind it.

There is no single combined score by default

RiskOS™ doesn't return one overall risk number that blends every enrichment. Instead, each enrichment scores independently, and your workflow combines those scores into a single decision.

• Enrichment scores are the raw model outputs (for example, fraud.scores[].score or emailRisk.score).
• Workflow rules read those scores as signals and act on them. A Rule Scorecard can assign weighted points (-100 to 100) when a condition is met, and Decision Rules map conditions to an ACCEPT, REVIEW, or REJECT outcome.
• The decision is the combined result of those rules — not an average of the enrichment scores.

So when you see a final decision, trace it back through the workflow rules to the individual enrichment scores and their reason codes, rather than expecting one number to explain everything.

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.

Enrichments, scores, and reason codes

Each enrichment scores a different facet of the identity and returns its own reasonCodes array. Use this table to map a score and its reason codes back to what the enrichment actually measures.

How reason codes relate to scores and decisions

Reason codes are already factored into the enrichment score — they describe why the model produced the score, not additional risk to add on top of it.

• Don't double-count. If an R-prefixed code appears for an enrichment, its impact is already inside that enrichment's score. For example, an R code on Document Verification is already reflected in the DocV score — don't apply a separate penalty for it.
• Codes are a subset, not the full picture. RiskOS™ models evaluate hundreds of predictors, many of them proprietary or not human-readable. Reason codes surface only the factors most useful for operational review, so two transactions with the same score can return different codes.
• The codes you get depend on the data you send. If you don't pass a phone number, you don't receive phone-related codes — and their absence isn't itself a signal.
• Codes are most valuable near your thresholds. They help most for transactions close to a decision boundary, where a reviewer needs to understand the risk signal behind the score.

How to read a score against your thresholds

A score has meaning only relative to the thresholds you set in your workflow. Socure doesn't impose a universal accept/reject cutoff — you choose thresholds based on your risk tolerance and the cost trade-off between fraud losses and false positives (see Fraud, Friction, and Acceptance).

When you set a threshold:

• Compare like to like. A 0.90 from Email Risk and a 0.90 from Sigma Identity Fraud come from different models and aren't interchangeable. Tune thresholds per enrichment.
• Reserve manual review for the boundary. Scores far below your threshold are clear approvals and scores far above are clear declines. The transactions near your threshold are where a reviewer benefits most from reading the reason codes.
• Start from a known baseline and tune. For example, a common starting point for Sigma Synthetic Fraud is a step-up to Document Verification at 0.99. Adjust against your own performance data over time.

Worked example

The following abbreviated Sigma Identity Fraud response returns a high score and three reason codes:

{
  "fraud": {
    "reasonCodes": ["R201", "R207", "I121"],
    "scores": [
      {
        "name": "sigma",
        "version": "1.0",
        "score": 0.94
      }
    ]
  }
}

How to read it without looking up a single description:

• The score of 0.94 is high, so this transaction likely exceeds a fraud threshold and routes to review.
• R201 and R207 are R-prefixed, so they are the risk drivers behind the score. Two related risk codes from the same enrichment is a stronger signal than one in isolation.
• I121 is I-prefixed, so it is a positive or neutral signal. It does not cancel the R codes, but a reviewer might weigh it when deciding whether to request additional verification rather than reject outright.
• You do not add extra penalty for R201 or R207; their effect is already inside the 0.94.
• To learn exactly what each code reports, look it up in the Dashboard Reason Codes page — the interpretation steps that follow hold regardless of the specific code.

How to use reason codes for operational review

When a transaction lands in manual review, work the reason codes in this order:

1. Identify the enrichment that drove the decision. Find the enrichment whose score crossed your threshold, then read its reasonCodes array.
2. Separate R codes from I codes. The R codes explain the risk; the I codes are corroborating positives that may support an override.
3. Confirm the codes match the input. A code such as "address not correlated" is more actionable when you can compare it against the address the applicant submitted.
4. Look for clusters, not single codes. Several related R codes (for example, multiple correlation failures across name, DOB, and SSN) is a stronger signal than one code in isolation.
5. Record the codes with the decision. Logging the reason codes alongside your accept/reject outcome creates an audit trail and feeds back into threshold tuning.

Using reason codes in workflows

You can also act on reason codes automatically 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.

Where to look up what a code means

This page explains how to interpret scores and reason codes — it doesn't list what each individual code means. For the complete catalog of reason codes, their descriptions, and which enrichment produces each code, open the Reason Codes page in the RiskOS™ Dashboard (see View reason codes and scores in the Dashboard), or pull the catalog programmatically with the Reason Codes endpoint.

When you look up a code, anchor your interpretation on two things you can read directly from the response:

• The prefix tells you the direction. An R code is a risk driver that pushed the score higher; an I code is a positive or neutral signal. For a given check, the I and R variants share the same number within an enrichment.
• The enrichment tells you the facet. The response key the code appears under (see Enrichments, scores, and reason codes) tells you what part of the identity the code describes — fraud risk, email, address, document authenticity, and so on.

If you need codes mapped to your specific workflow configuration, contact your Socure support representative.