> For the complete documentation index, see [llms.txt](https://docs.vida.id/identity-stack/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.vida.id/identity-stack/verify/kyc-web-sdk/integration/backend-integration/fraud-shield-api.md).

# Fraud Shield API

{% hint style="info" %}
**Purpose of This Page**

Documents `GET` `/api/v1/evaluation/{clientTransactionId}` and explains how Fraud Shield results affect `overallStatus` in the KYC status response.
{% endhint %}

### Step 4 - Fraud Shield Evaluation API

ID Fraud Shield evaluates device and session risk signals collected passively during the SDK session. If enabled, the evaluation result is included in the `GET` `/verify/status` response, and is also available as a standalone API call.

{% hint style="info" %}
**Fraud Shield is optional**

This step only applies if ID Fraud Shield is enabled for your integration (requires OSS configuration and a shieldId sent by the SDK).

If Fraud Shield is not enabled, fraudResult will be an empty object {} in the `GET` `/verify/status` response
{% endhint %}

#### Endpoint

<mark style="color:blue;">**`GET`**</mark> `/api/v1/evaluation/{clientTransactionId}`

#### When to Call

The fraud result is already included in the `GET` `/verify/status` response as the fraudResult field. Call this endpoint separately if you need the full evaluation payload and did not capture it from the status response, or if you need to re-fetch it independently.

#### Request

<table><thead><tr><th width="177.37109375">Parameter</th><th width="109.25">Location</th><th>Type</th><th width="107.93359375">Required</th><th>Description</th></tr></thead><tbody><tr><td><code>clientTransactionId</code></td><td>Path</td><td>string (uuid)</td><td>Yes</td><td>Same as <code>verificationId</code> / <code>groupId</code> from the SDK response</td></tr></tbody></table>

#### Risk Levels

<table><thead><tr><th width="162.5390625">Risk Level</th><th>Meaning</th><th>Effect on OverallStatus</th></tr></thead><tbody><tr><td><code>LOW</code></td><td>No significant fraud signals detected</td><td>No effect - operations keep their results</td></tr><tr><td><code>MEDIUM</code></td><td>Warning threshold breached - review recommended</td><td>Affected operations set to <code>REVIEW</code></td></tr><tr><td><code>HIGH</code></td><td>Error threshold breached - high fraud risk detected</td><td>Affected operations set to <code>ERROR</code>; <code>overallStatus</code> becomes <code>ERROR</code></td></tr></tbody></table>

#### How Fraud Affects the KYC Status

When fraud is detected on a My-Verify call, the operations from that specific call are marked ERROR in the KYC status. This is by design - it ensures consistency between the verify API (which returns HTTP 400 on fraud) and the status API.

| Fraud Detected On                | Operations Affected                                                                                                             | Example                                                                                |
| -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- |
| OCR + IDV call (My-Verify)       | OCR and idVerification marked ERROR                                                                                             | Risk level HIGH during document capture                                                |
| Face Match call (My-Verify)      | faceMatchVerification marked ERROR                                                                                              | Risk level HIGH during face match                                                      |
| Liveness call (Liveness Service) | Associated operations marked ERROR; liveness transaction is marked FAILURE (code 10001) and the real liveness outcome is hidden | My-Verify cannot determine if liveness actually passed — ERROR is the only safe option |

{% hint style="info" %}
**ERROR due to fraud vs. ERROR due to genuine failure**

If overallStatus is ERROR and fraudResult.result.riskLevel is HIGH or MEDIUM, the ERROR was caused by fraud detection - not a verification failure.

Always check fraudResult when handling an ERROR status to distinguish the two cases.
{% endhint %}

#### fraudResult in `GET` `/verify/status`

The fraudResult object is returned inside the GET /verify/status response. It contains:

| Field                      | Description                                                         |
| -------------------------- | ------------------------------------------------------------------- |
| configuredErrorThreshold   | The risk level at which operations are set to ERROR (e.g., HIGH)    |
| configuredWarningThreshold | The risk level at which operations are set to REVIEW (e.g., MEDIUM) |
| result.verificationId      | The KYC session ID                                                  |
| result.riskLevel           | Evaluated risk level: LOW, MEDIUM, or HIGH                          |
| result.evaluatedAt         | When the evaluation was performed                                   |
| result.deviceProfile       | Device fingerprint and characteristics                              |
| result.behaviorMetrics     | User behavior signals during the session                            |
| result.sessionContext      | Session metadata (time, location context, etc.)                     |
| result.userProfile         | User-level risk signals                                             |
| result.ipProfile           | IP address risk signals                                             |
| result.ruleEvaluations     | Individual rule evaluations that contributed to the risk level      |

#### Sample - Fraud Detected (riskLevel: HIGH)

<details>

<summary>JSON Response</summary>

{% code expandable="true" %}

```json
{
  "verificationId": "abc-123",
  "overallStatus": "ERROR",
  "operations": {
    "ocr":                   { "front": { "latestExecution": { "status": "VERIFIED" } } },
    "idVerification":        { "front": { "latestExecution": { "status": "VERIFIED" } } },
    "livenessVerification":  { "result": { "latestExecution": { "status": "VERIFIED" } } },
    "faceMatchVerification": { "result": { "latestExecution": { "status": "ERROR"    } } }
    //                                                                         ↑
    //                             Face Match is ERROR because fraud was detected during that call.
    //                             OCR and IDV remain VERIFIED because fraud was not detected there.
  },
  "fraudResult": {
    "configuredErrorThreshold":  "HIGH",
    "configuredWarningThreshold": "MEDIUM",
    "result": {
      "verificationId": "abc-123",
      "riskLevel": "HIGH",
      "evaluatedAt": "2026-04-01T10:30:00.000+07:00",
      "deviceProfile":   { "..." : "..." },
      "behaviorMetrics": { "..." : "..." },
      "sessionContext":  { "..." : "..." },
      "userProfile":     { "..." : "..." },
      "ipProfile":       { "..." : "..." },
      "ruleEvaluations": [ "..." ]
    }
  }
}


```

{% endcode %}

</details>