Direct API

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.

End-to-end flow

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

sequenceDiagram
    autonumber
    participant User as End User
    participant App as Your Platform
    participant Socure as Socure

    User->>App: Submit PII via signup form
    App->>Socure: POST /api/evaluation with PII + di_session_token
    Socure-->>App: Immediate decision (ACCEPT / REJECT / REVIEW)

    alt ACCEPT
        App-->>User: Continue onboarding
    else REJECT
        App-->>User: Route to fallback or review flow
    else REVIEW (DocV Step-Up)
        Note over App: Extract docvTransactionToken from response
        App-->>User: Launch DocV SDK (Capture App)
        User->>Socure: Submit document images and selfie
        Socure->>Socure: Process document verification
        Socure-->>App: Webhook: evaluation_completed (ACCEPT / REJECT)
        App-->>User: Show final onboarding result
    end

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.

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 (e.g., 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.

Next steps

Start a new evaluation

Set up the Digital Intelligence SDK, collect PII, and create an evaluation.

Handle results

Interpret evaluation responses and route users based on the decision.

Handle additional verification

Launch the DocV Capture App and receive the final decision via webhook.

Updated about 9 hours ago