Fraud Shield API

Purpose of This Page

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

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.

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

Endpoint

GET /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

Parameter	Location	Type	Required	Description
clientTransactionId	Path	string (uuid)	Yes	Same as verificationId / groupId from the SDK response

Risk Levels

Risk Level	Meaning	Effect on OverallStatus
LOW	No significant fraud signals detected	No effect - operations keep their results
MEDIUM	Warning threshold breached - review recommended	Affected operations set to REVIEW
HIGH	Error threshold breached - high fraud risk detected	Affected operations set to ERROR; overallStatus becomes ERROR

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

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.

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)

JSON Response

{
  "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": [ "..." ]
    }
  }
}