# Scoring System

Every Incode onboarding session produces a score. This score indicates how confident the Incode Platform is that the user is who they claim to be. Session scores are based on the verification modules in your Flow or Workflow. Your application uses the score to decide whether to approve the user, send the session for manual review, or reject it.

***

## Score Structure

An onboarding session score has two components: a **numeric value** and a **status**.

### Numeric Value

Scores are expressed as a decimal value out of 100, in the format `x.x/100`. For example:

- `95.2/100`: High confidence
- `79.0/100`: Moderate confidence
- `0.0/100`: Zero confidence, or a module that did not run

### Status

Statuses are category labels based on:

- The numeric value.
- The thresholds configured in your Flow or Workflow.

There are five possible statuses:

| Status    | Meaning                                                                                                                                 |
| --------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| `ok`      | The score meets the passing threshold. The user passed this check.                                                                      |
| `warn`    | The score is below the passing threshold but above the review threshold. The result warrants attention but is not a definitive failure. |
| `manual`  | The session has been flagged for manual human review in Dashboard.                                                                      |
| `fail`    | The score is below the review threshold. The check did not pass.                                                                        |
| `unknown` | The score could not be calculated. For example, a module did not run or a result is pending.                                            |

***

## Module Scores and Overall Session Score

Some modules produce their own independent score. Other don't produce their own score but can still influence the session score based on business logic in your Flow or Workflow. These **module scores** and your business logic work together to produce the overall **session score**.

### Modules with Independent Scores

Each module that contributes to scoring produces a value/status pair. The primary scoring modules are:

| Module           | Score field       | What it measures                                                           |
| ---------------- | ----------------- | -------------------------------------------------------------------------- |
| ID Validation    | `idValidation`    | Document authenticity, OCR quality, and anti-tampering checks              |
| Face Recognition | `faceRecognition` | Match confidence between the selfie and the ID document photo              |
| Liveness         | `liveness`        | Confidence that the selfie was taken from a live person and is not a spoof |

> 📘 **Note**
>
> If no `validationModuleList` is specified when creating a session, the default modules used for scoring are `id`, `faceRecognition`, and `liveness`.

**Example Module Score Response**

```json
{
  "overall":         { "value": "79.0/100", "status": "warn" },
  "faceRecognition": { "value": "0.0/100",  "status": "warn" },
  "liveness":        { "value": "95.2/100", "status": "manual" },
  "idValidation":    { "value": "79.0/100", "status": "fail" }
}
```

### Modules That Influence the Overall Session Score

Some modules collect data and don't produce their own score. These modules can still influence the overall session score when you configure business logic conditions in your Workflow. Their results may not be expressed as an `x.x/100` score.

The `extendedUserScoreJsonData` field in the score response contains the full raw JSON for all score data if you need to inspect non-primary module results.

The following non-scoring modules are common in onboarding sessions:

- [eKYC](https://developer.incode.com/docs/ekyc)
- [eKYB](https://developer.incode.com/docs/ekyb)
- [Global Watchlist](https://developer.incode.com/docs/global-watchlist)
- [Antifraud Check](https://developer.incode.com/docs/antifraud-check)
- [Deepsight](https://developer.incode.com/docs/deepsight)

### Overall Session Score

The overall session score (`overall`) is a composite score. It aggregates the module-level results and reflects the combined confidence across all scoring modules in the onboarding session. The overall score uses the same numeric value and status format as module scores.

> 📘 Note
>
> The numeric thresholds that determine whether a score is `ok`, `warn`, or `fail` are set per Flow or Workflow in Dashboard. The thresholds that make sense for your use case depend on your risk tolerance and regulatory requirements. Contact your Incode Representative for guidance on threshold configuration.

### Score Timing

Module scores are calculated as each module completes. These scores may be available before the session finishes, as shown in the following table. Incode recommends waiting for `ONBOARDING_FINISHED` before you fetch scores, because individual module scores do not reflect business rules or the overall session score.

| Session status                   | What scores are available                                     |
| -------------------------------- | ------------------------------------------------------------- |
| `ID_VALIDATION_FINISHED`         | `idValidation` score is available                             |
| `GOVERNMENT_VALIDATION_FINISHED` | Government validation result is available                     |
| `FACE_VALIDATION_FINISHED`       | `faceRecognition` and `liveness` scores are available         |
| `ONBOARDING_FINISHED`            | All scores are finalized; overall session score is calculated |

***

## Retrieve Scores

Scores are available once the session reaches `ONBOARDING_FINISHED` status. You can also view session scores in Dashboard or retrieve them via API or SDK.

### View Scores in Dashboard

Onboarding session scores are visible in **Dashboard** >**Sessions**. Each session view shows:

- The overall score and status
- Per-module details, including module scores where applicable
- The final determination: Approved, Needs Review, Rejected, or Expired
- The session event log

Additional information may be available depending on the modules in your Flow or Workflow.

Dashboard is where reviewers manually examine the session and make an approve or reject decision, which triggers the `MANUAL_REVIEW_APPROVED` or `MANUAL_REVIEW_REJECTED` webhook.

### Retrieve Scores via API

Use the `GET /omni/get/score` endpoint. This requires an admin token in the `X-Incode-Hardware-Id` header and your API key in `x-api-key`.

```http
GET /omni/get/score?id={interviewId}
Content-Type: application/json
api-version: 1.0
x-api-key: YOUR_API_KEY
X-Incode-Hardware-Id: YOUR_ADMIN_TOKEN
```

See the [Get Scores API reference](https://developer.incode.com/reference/getscores) for the full response schema.

### Retrieve Scores via SDK

In mobile integrations using the full SDK flow, the `getUserScore()` method returns the score at the end of the session. The result includes a parsed `data` object with top-level score fields and the raw `extendedUserScoreJsonData` JSON for full detail.

```javascript
// React Native example
IncodeSdk.getUserScore({ mode: 'fast' })
  .then((result) => {
    // result.data.status: 'warning' | 'unknown' | 'manual' | 'fail'
    // result.data.overallScore: "79.0/100"
    // result.extendedUserScoreJsonData: raw JSON string
    validateResultWithBusinessLogic(result);
  });
```

> 📘 **Tip**
>
> Apply approval logic, such as score thresholds and identity creation, in your back end, not in the SDK callback. The SDK result is useful for immediate UI feedback, but your server should make the final decision using the API response.

***

## Map Session Results to Business Decisions

Your Flow or Workflow configuration determines how overall session results map to business outcomes. The following table shows a typical mapping.

| Outcome           | Session Result | What it means                                                                                                                                                     |
| ----------------- | :------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Approve**       | **Pass**       | The session passed based on your configured thresholds. The user is approved. If configured in your Flow or Workflow, an Incode Identity is created for the user. |
| **Manual Review** | **Warn**       | The session is placed in a review queue based on your configured thresholds. A human reviewer then approves or rejects it in Dashboard.                           |
| **Deny**          | **Fail**       | The session failed based on your configured thresholds. The user is rejected. No Incode Identity is created.                                                      |

In a Flow, this mapping is set in the **Session Score: Pass** setting. In a Workflow, the mapping is determined in the final condition branch.

***

## Related Pages

- [Onboarding Session Lifecycle](https://developer.incode.com/docs/onboarding-session-lifecycle): Session statuses and how scoring relates to session completion
- [Flows](https://developer.incode.com/docs/flows-1): How to configure score-to-decision mapping in Flows in Dashboard
- [Conditions for Workflows](https://developer.incode.com/docs/conditions-for-workflows-20): Workflow-based score conditions and branching logic

<br />