## Overview

The Direct API lifecycle allows your platform to collect identity data, submit it to RiskOS™, and receive decisions through API responses and webhooks.

Your application owns the onboarding experience and is responsible for:

- Collecting user identity data (PII)
- Sending API requests to RiskOS™
- Handling responses and routing the user

RiskOS™ processes identity, fraud, and compliance signals and returns decisions either:

- **Synchronously** (immediate `ACCEPT` or `REJECT`), or
- **Asynchronously** when additional verification (such as Document Verification) is required

During the evaluation, RiskOS™ orchestrates KYC, Fraud, Watchlist, and conditional step-up verification.

## Key behaviors

| Behavior | Detail |
| --- | --- |
| **Decision delivery** | Immediate decisions (`ACCEPT`, `REJECT`) are returned synchronously in the API response. When DocV step-up is required, the final decision is delivered asynchronously via `evaluation_completed` webhook. |
| **Digital Intelligence gatekeeper** | The evaluation begins by analyzing device risk signals. If Digital Intelligence fails (for example, detection of a malicious bot, known emulator, or high-risk VPN), RiskOS™ issues a `REJECT` decision immediately before proceeding to KYC or Watchlist checks. |
| **DocV step-up** | A `REVIEW` decision with `eval_status: "evaluation_paused"` indicates Document Verification is required. Extract the `docvTransactionToken` from the response to launch the [Capture App.](https://help.socure.com/riskos/docs/capture-app) |

## End-to-end flow

01. Set up your backend environment and configure API keys.
02. Generate a `di_session_token` using the Digital Intelligence SDK.
03. Collect user identity data (PII) on your custom frontend.
04. Create an evaluation (`POST /api/evaluation`) with PII and `di_session_token`.
05. RiskOS™ evaluates device and identity risk signals.
06. If device risk fails, the evaluation is immediately rejected.
07. RiskOS™ runs KYC, Fraud, and Watchlist screening.
08. If no additional verification is required, a final decision is returned synchronously.
09. If additional verification is required, RiskOS™ triggers Document Verification (DocV), pauses the evaluation, and resumes asynchronously via webhook.
10. Route the user based on the final decision.

```
SocureYour PlatformEnd UserSocureYour PlatformEnd UserExtract docvTransactionToken from responsealt[ACCEPT][REJECT][REVIEW (DocV Step-Up)]Submit PII via signup form1POST /api/evaluation with PII + di_session_token2Immediate decision (ACCEPT / REJECT / REVIEW)3Continue onboarding4Route to fallback or review flow5Launch DocV SDK (Capture App)6Submit document images and selfie7Process document verification8Webhook: evaluation_completed (ACCEPT / REJECT)9Show final onboarding result10
```

## Evaluation processing

During the Direct API flow, RiskOS™ orchestrates multiple products and verification steps:

- **Digital Intelligence**

Evaluates device integrity and behavioral risk signals as a gatekeeper.

- **KYC**

Verifies identity against trusted data providers.

- **Fraud detection**

Evaluates fraud and synthetic identity signals.

- **Watchlist screening**

Screens against global sanctions, PEP, and adverse media lists.

- **DocV step-up**

Triggers document verification when risk thresholds are met.

## Next steps

[Start a new evaluation](https://help.socure.com/riskos/docs/kyc-watchlist-screening-direct-api-start-an-evaluation)

[Handle results](https://help.socure.com/riskos/docs/kyc-watchlist-screening-direct-api-handle-results)

[Handle additional verification](https://help.socure.com/riskos/docs/kyc-watchlist-screening-direct-api-handle-additional-verification)

Updated 3 days ago