## 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**.

| Environment | Reason Codes page |
| --- | --- |
| **Sandbox** | [Go to Sandbox Dashboard](https://riskos.sandbox.socure.com/reason-codes-and-lists/reason-codes) |
| **Production** | [Go to Production Dashboard](https://riskos.socure.com/reason-codes-and-lists/reason-codes) |

To retrieve the catalog programmatically instead of using the Dashboard, see [List Reason Codes](https://help.socure.com/riskos/docs/list-reason-codes).

## How reason codes and scores work

When you call the RiskOS™ [Evaluation API](https://help.socure.com/riskos/docs/integrating-with-riskos), 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](https://help.socure.com/riskos/docs/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.

| Property | Detail |
| --- | --- |
| Range | `0.001`–`0.999` |
| Direction | Higher = greater likelihood of fraud or risk |
| Type | Probabilistic value derived from a machine learning model, not a percentage or a sum of points |
| Scope | Specific to a single enrichment and the data you sent for it |

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](https://help.socure.com/riskos/docs/understanding-riskos) 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](https://help.socure.com/riskos/docs/understanding-riskos) 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):

```json
{
  "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**:

| Prefix | Meaning | Description |
| --- | --- | --- |
| `I` | **Informational** | A check passed or returned a neutral/positive signal. |
| `R` | **Risk** | A check flagged a risk or failure that contributed to a higher score. |

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.

| Enrichment | Response key | What its score measures |
| --- | --- | --- |
| Sigma Identity Fraud | `fraud` | Overall third-party / identity fraud risk for the applicant |
| Sigma Synthetic Fraud | `synthetic` | Likelihood that the identity is fabricated (synthetic) |
| Sigma First-Party Fraud | `firstPartyFraud` | Likelihood of first-party (self-committed) fraud |
| Address Risk | `addressRisk` | Risk associated with the submitted address |
| Email Risk | `emailRisk` | Risk associated with the submitted email address |
| Phone Risk | `phoneRisk` | Risk associated with the submitted phone number |
| Document Verification (DocV) | `documentVerification` | Authenticity and data correlation of the captured document |
| Global Watchlist | `globalWatchlist` | Matches against sanctions, PEP, and adverse media lists |
| Verify / Verify+ | `verify` / `verifyPlus` | Correlation of submitted PII against authoritative records |
| Account Intelligence | `accountIntelligence` | Bank account ownership and availability |

## 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](https://help.socure.com/riskos/docs/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:

```json
{
  "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](https://help.socure.com/riskos/docs/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](https://help.socure.com/riskos/docs/reason-codes#view-reason-codes-and-scores-in-the-dashboard)), or pull the catalog programmatically with the [Reason Codes endpoint](https://help.socure.com/riskos/docs/list-reason-codes).

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](https://help.socure.com/riskos/docs/reason-codes#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.