Process KYC + Fraud + Watchlist Screening Results via API

Handle Direct API evaluation responses and route users based on ACCEPT, REJECT, and REVIEW decisions in the KYC + Fraud + Watchlist flow.

How to interpret the response

After creating an evaluation, use the response to determine how your application should route the user and continue the verification flow.

Your integration should not rely on a single field. Always evaluate decision + status + tags together when determining next steps.

decision → High-level outcome (ACCEPT, REJECT, REVIEW)
status → Whether the evaluation is complete (CLOSED, ON_HOLD)
tags → Why the evaluation reached this decision (used for routing + UX)

For the full response schema, see the Evaluation API Reference. The examples that follow expand into the complete data_enrichments payload for each outcome — no need to piece it together from each product guide.

Evaluation flow

RiskOS™ evaluates signals in stages:

Digital Intelligence
High-risk signals (for example, bots, emulators, or risky networks) may result in an immediate REJECT.
Identity verification (Socure Verify)
Validates identity attributes (name, DOB, SSN, address).
Fraud & risk signals
Sigma Identity Fraud and Sigma Synthetic Fraud evaluate fraud and synthetic identity risk. Watchlist Screening checks against global sanctions, PEP, and adverse media lists.

If no blocking risks are found, the evaluation completes. Otherwise, it may:

Reject immediately, or
Pause for step-up verification (for example, Document Verification)

Decision outcomes

Decision	Status	Meaning	Action
`ACCEPT`	`CLOSED`	Passed all checks	Continue onboarding
`REJECT`	`CLOSED`	Failed a critical check	Stop or route to fallback
`REVIEW`	`ON_HOLD`	Additional verification required	Trigger step-up (for example, DocV)

Outcome handling

`ACCEPT`

The user passed all checks.

{
  "decision": "ACCEPT",
  "status": "CLOSED",
  "sub_status": "Accept",
  "tags": []
}

What to do:

Continue onboarding.
Grant access or create the account.

See the full response payload (all modules)

This is one complete, realistic response for this solution — every module's data_enrichments entry (Digital Intelligence, Socure Verify, Sigma Identity Fraud, Sigma Synthetic Fraud, Global Watchlist) in a single evaluation, so you don't have to piece it together from each product guide.

All values are illustrative Sandbox data. The decision your workflow returns depends on your configured thresholds — a signal appearing in data_enrichments does not by itself determine ACCEPT, REJECT, or REVIEW. The digitalIntelligence block is trimmed to its core fields for readability; see Digital Intelligence for the exhaustive schema.

{
  "id": "fb428165-6a1c-4d36-afbc-c8a946c1287d",
  "eval_id": "8770e076-f568-48a9-8201-dca13087e592",
  "workflow": "consumer_onboarding",
  "workflow_id": "879a58be-2943-4953-be17-01a6e3191e4f",
  "workflow_version": "2.95.0",
  "eval_source": "API",
  "eval_start_time": "2026-02-17T14:22:06.628Z",
  "eval_end_time": "2026-02-17T14:22:07.114Z",
  "decision": "ACCEPT",
  "status": "CLOSED",
  "sub_status": "Accept",
  "eval_status": "evaluation_completed",
  "tags": [],
  "review_queues": [],
  "data_enrichments": [
    {
      "enrichment_name": "Socure Digital Intelligence",
      "enrichment_endpoint": "https://sandbox.socure.com/api/3.0/EmailAuthScore",
      "enrichment_provider": "Socure",
      "status_code": 200,
      "request": {
        "modules": ["digitalintelligence"],
        "deviceSessionId": "8ceed175-37ae-4eb4-9ee5-b7fc5d7c1799",
        "userId": "fb428165-6a1c-4d36-afbc-c8a946c1287d"
      },
      "response": {
        "referenceId": "8ceed175-37ae-4eb4-9ee5-b7fc5d7c1799",
        "digitalIntelligence": {
          "device": {
            "id": "234ac3ff-3ed1-42de-8f33-8f332febfa54",
            "sessionCreatedAt": "2026-02-17T14:20:52.248985937Z",
            "deviceCapturedAt": "2026-02-17T14:22:02.735992851Z",
            "computed": {
              "statisticalId": "9349d69fef75cd356744293487462f8cd912",
              "isVirtualMachine": false,
              "isTamperedAndroidBuild": false,
              "sessionAgeMinutes": 2,
              "deviceNetworkTimezoneOffsetDiffMinutes": 0
            },
            "network": {
              "connectionIp": "38.48.122.126",
              "forwardedForIps": ["78.32.11.221"],
              "webRtcPublicIp": "176.124.54.12",
              "webRtcInternalIp": "192.168.1.85",
              "realIp": "38.48.122.126",
              "isTor": false,
              "isProxy": false,
              "isVpn": false,
              "isConsumerPrivacy": false,
              "isRiskyNetwork": false,
              "isp": "verizon",
              "ispType": "home",
              "asn": 27364,
              "asnName": "verizon",
              "domainName": "verizon.net",
              "org": "verizon",
              "isMobileCarrier": false,
              "speed": "cable",
              "networkLocation": {
                "countryCode": "US",
                "region": "NY",
                "city": "Springfield",
                "postalCode": "10552",
                "latitude": 40.9982,
                "longitude": -73.7949,
                "metroCode": 501,
                "continentCode": "na",
                "timezoneName": "America/New_York",
                "gmtOffset": "-0500"
              }
            },
            "attributes": {
              "sdkVersion": "3.0.1",
              "platform": "web",
              "os": "macOS",
              "osVersion": "15",
              "deviceModel": "unknown",
              "deviceManufacturer": "unknown",
              "deviceType": "desktop",
              "viewportWidth": 1440,
              "viewportHeight": 900,
              "screenHeight": 900,
              "screenWidth": 1440,
              "devicePixelRatio": 2,
              "network": {
                "vpnStatus": false
              },
              "timeZone": "America/New_York",
              "timeZoneOffset": -300,
              "language": "en-US",
              "deviceArchitecture": "arm64",
              "applicationType": "web",
              "isEmulator": false,
              "deviceContext": "onboarding",
              "webAttributes": {
                "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/17.0 Safari/605.1.15",
                "userAgentExtractionRequired": false,
                "browser": "Safari",
                "browserVersion": "17"
              }
            },
            "history": {
              "firstSeen": "2026-02-17T14:20:52.248985937Z",
              "lastSeen": "2026-02-17T14:20:52.248985937Z",
              "ips": ["78.32.11.221"],
              "isps": ["Verizon"],
              "daysSeen": ["2026-02-17"],
              "networkLocations": ["springfield, ny"]
            }
          },
          "behavioral": {
            "sessionId": "d34304a6-a726-4dec-b1cd-9c4a3c192a0d",
            "serverCreated": "2026-02-17T14:20:58.796Z",
            "serverUpdated": "2026-02-17T14:22:02.796Z",
            "clientUpdated": "2026-02-17T14:22:01.796Z",
            "duration": 64000,
            "source": "https://example.com/onboarding",
            "aggregations": {
              "totalEventCount": 18,
              "focusCount": 4,
              "blurCount": 1,
              "inputChangeCount": 9,
              "submissionCount": 1,
              "clickCount": 5,
              "pasteCount": 0
            }
          },
          "velocityMetrics": {
            "historicalCount": {
              "firstName": { "uniqueCount": 1, "uniqueSharePercent": 100 },
              "surName": { "uniqueCount": 1, "uniqueSharePercent": 100 },
              "email": { "uniqueCount": 1, "uniqueSharePercent": 100 },
              "mobileNumber": { "uniqueCount": 1, "uniqueSharePercent": 100 }
            }
          }
        },
        "customerProfile": {
          "userId": "fb428165-6a1c-4d36-afbc-c8a946c1287d"
        }
      },
      "is_source_cache": false
    },
    {
      "enrichment_name": "Socure Verify",
      "enrichment_provider": "Socure",
      "enrichment_endpoint": "/api/3.0/EmailAuthScore",
      "status_code": 200,
      "request": {
        "modules": ["kyc"],
        "firstName": "Stanley",
        "surName": "Brown",
        "dob": "1944-03-30",
        "nationalId": "666478381",
        "physicalAddress": "6383 Brown Avenue",
        "city": "Springfield",
        "state": "NY",
        "zip": "10552",
        "country": "US",
        "mobileNumber": "+15012345677",
        "email": "[email protected]"
      },
      "response": {
        "referenceId": "b8fbeb31-a2fc-4f1e-a5d1-392c4ed06538",
        "kyc": {
          "socureId": "46fd3b11-a130-4915-8cc4-074bbd799669",
          "reasonCodes": ["I919"],
          "fieldValidations": {
            "firstName": 0.99,
            "surName": 0.99,
            "streetAddress": 0.99,
            "city": 0.99,
            "state": 0.99,
            "zip": 0.99,
            "mobileNumber": 0.99,
            "dob": 0.99,
            "ssn": 0.99
          },
          "fieldSourceAttribution": {
            "ssn": ["Social Security Administration"],
            "address": ["USPS", "Utility Records"],
            "mobileNumber": ["Telecom Carrier"]
          },
          "sourceAttribution": ["Credit", "Telco"],
          "matchCounts": { "tradelines": 3 },
          "creditFileNumber": "00512123456",
          "additionalInfo": { "tradelines": 3 },
          "transactionScope": "domestic"
        }
      },
      "is_source_cache": false
    },
    {
      "enrichment_name": "Socure Sigma Identity Fraud",
      "enrichment_provider": "Socure",
      "enrichment_endpoint": "/api/3.0/EmailAuthScore",
      "status_code": 200,
      "request": {
        "modules": ["fraud"],
        "firstName": "Stanley",
        "surName": "Brown",
        "nationalId": "666478381",
        "dob": "1944-03-30",
        "email": "[email protected]",
        "phone": "+15012345677",
        "ipAddress": "38.48.122.126",
        "country": "US"
      },
      "response": {
        "referenceId": "d7e8f901-2345-6789-abcd-ef0123456789",
        "fraud": {
          "reasonCodes": ["I301"],
          "scores": [
            { "name": "Sigma Identity Fraud (US)", "version": "5.0", "score": 0.041 }
          ]
        }
      },
      "is_source_cache": false
    },
    {
      "enrichment_name": "Socure Sigma Synthetic",
      "enrichment_provider": "Socure",
      "enrichment_endpoint": "/api/3.0/EmailAuthScore",
      "status_code": 200,
      "request": {
        "modules": ["synthetic"],
        "firstName": "Stanley",
        "surName": "Brown",
        "nationalId": "666478381",
        "dob": "1944-03-30",
        "email": "[email protected]",
        "phone": "+15012345677",
        "streetAddress": "6383 Brown Avenue",
        "city": "Springfield",
        "state": "NY",
        "zip": "10552",
        "ipAddress": "38.48.122.126",
        "country": "US"
      },
      "response": {
        "referenceId": "f9012345-6789-abcd-ef01-234567890abc",
        "synthetic": {
          "reasonCodes": ["I912"],
          "scores": [
            { "name": "synthetic", "version": "4.0", "score": 0.038 }
          ]
        }
      },
      "is_source_cache": false
    },
    {
      "enrichment_name": "Socure Global Watchlist Premier",
      "enrichment_endpoint": "https://service.socure.com/api/3.0/EmailAuthScore",
      "enrichment_provider": "Socure",
      "status_code": 200,
      "request": {
        "firstName": "Stanley",
        "surName": "Brown",
        "modules": ["watchlistpremier"],
        "parentTxnId": "8770e076-f568-48a9-8201-dca13087e592",
        "riskOSId": "fb428165-6a1c-4d36-afbc-c8a946c1287d",
        "userId": "fb428165-6a1c-4d36-afbc-c8a946c1287d",
        "workflow": "consumer_onboarding"
      },
      "response": {
        "customerProfile": {
          "userId": "fb428165-6a1c-4d36-afbc-c8a946c1287d"
        },
        "globalWatchlist": {
          "matches": {}
        }
      },
      "is_source_cache": false
    }
  ]
}

globalWatchlist.matches is an empty object when the applicant has no hits on any sanctions, PEP, or adverse media list. See Integrate Watchlist Screening for the shape of matches when a record is found.

`REVIEW`

The evaluation is paused pending additional verification.

Key signals:

decision: "REVIEW"
status: "ON_HOLD"
eval_status: "evaluation_paused"

{
  "decision": "REVIEW",
  "status": "ON_HOLD",
  "eval_status": "evaluation_paused",
  "tags": [
    "Email Risk Step Up",
    "Phone Risk Step Up",
    "Document Verification Triggered"
  ]
}

What to do:

Trigger step-up verification (for example, Document Verification).
Use data_enrichments to retrieve the DocV URL or token.
Resume the flow after the user completes the additional verification.

See Handle additional verification for the full step-up implementation flow.

See the full DocV step-up payload

Once the user completes document verification, RiskOS™ delivers the following data_enrichments entry on the evaluation_completed webhook:

{
  "event_id": "a4c92f1e-8b3d-4a17-9c5e-f2d8e7b61a03",
  "event_at": "2026-02-17T14:26:23.104744158Z",
  "event_type": "evaluation_completed",
  "data": {
    "id": "fb428165-6a1c-4d36-afbc-c8a946c1287d",
    "workflow": "consumer_onboarding",
    "eval_id": "8770e076-f568-48a9-8201-dca13087e592",
    "decision": "ACCEPT",
    "status": "CLOSED",
    "sub_status": "Approved",
    "tags": ["Document Verification Triggered", "DocV Accept"],
    "evaluation_status": "evaluation_completed",
    "review_queues": [],
    "data_enrichments": [
      {
        "enrichment_name": "Socure DocV",
        "enrichment_endpoint": "https://service.socure.com/api/5.0/documents/verify",
        "enrichment_provider": "Socure",
        "status_code": 200,
        "is_source_cache": false,
        "total_attempts": 1,
        "error_message": "",
        "request": {},
        "response": {
          "documentVerification": {
            "reasonCodes": ["<reason_code>", "<reason_code>"],
            "documentType": {
              "type": "Drivers License",
              "country": "USA",
              "state": "NY"
            },
            "decision": {
              "name": "lenient",
              "value": "accept"
            },
            "documentData": {
              "firstName": "Stanley",
              "surName": "Brown",
              "fullName": "Stanley Brown",
              "dob": "1944-03-30",
              "address": "6383 Brown Avenue, Springfield, NY 10552",
              "parsedAddress": {
                "physicalAddress": "6383 Brown Avenue",
                "city": "Springfield",
                "state": "NY",
                "country": "US",
                "zip": "10552"
              },
              "documentNumber": "00000000",
              "issueDate": "2021-01-12",
              "expirationDate": "2029-05-07"
            }
          }
        }
      }
    ]
  }
}

For the full field-by-field reference for this object — including reasonCodes, supported document types, and the secondaryDocument and Socure Pass variants — see the DocV Webhook Payload Reference.

Common REVIEW tags

These indicate why the evaluation triggered step-up:

Identity mismatch:

DOB Does Not Match Step Up, SSN Verification Step Up, First or Last Name Does Not Match Step Up, First and Last Name Possibly Reversed Step Up
Data risk:

Email Risk Step Up, Phone Risk Step Up, Address Risk Step Up, Input Address State or Zip Does Not Match Address On File Step Up
Fraud signals:

Sigma Synthetic Step Up, Sigma Identity Fraud Step Up, Graph Intel Step Up
Other:

Digital Intel Step Up, Watchlist Review

📘
Note:
REVIEW isn't a terminal outcome. It indicates the evaluation is paused and requires additional verification before RiskOS™ returns a final decision.

`REJECT`

The user failed a critical check.

{
  "decision": "REJECT",
  "status": "CLOSED",
  "sub_status": "Reject",
  "tags": [
    "Sigma Identity Fraud Reject"
  ]
}

What to do:

Stop onboarding.
Route to a fallback, manual review, or decline flow.

Common REJECT tags

High Risk Individual
Sigma Identity Fraud Reject
Verify Reject
SSN Does Not Match - Reject
Address is Invalid or Commercial or PO box or Prison - Reject
Watchlist Review

📘
Note:
Watchlist Review may appear in either a REVIEW or REJECT response depending on how the workflow resolves.

Route the user

Use decision as the primary routing field, then use status and tags to refine the user experience.

ACCEPT → Continue onboarding
REJECT → Route to fallback or decline flow
REVIEW → Handle additional verification

switch (data.decision) {
  case "ACCEPT":
    router.push("/success");
    break;

  case "REJECT":
    router.push("/review");
    break;

  case "REVIEW":
    router.push("/additional-verification");
    break;
}

Updated about 1 month ago

Did this page help you?