Hosted Flow

Start building

Overview

The Hosted Flow lifecycle allows your platform to initiate a verification session, redirect the user to a Socure-hosted experience, and receive a final decision via webhook.

Your application does not collect identity data directly. RiskOS™ manages the full verification experience and returns control to your redirect_uri after the user completes the flow.

During the hosted experience, RiskOS™ orchestrates Prefill, KYC, Fraud, Watchlist, and conditional step-up verification when additional verification is required.

End-to-end flow

1. Create Hosted Flow session ([POST /api/evaluation](https://help.socure.com/riskos/reference/postevaluation)).
2. Receive response with redirect URL and initial evaluation state.
3. Redirect user to Hosted Flow.
4. RiskOS™ collects initial consumer data, including phone number and date of birth.
5. If required for that consumer, RiskOS™ triggers a One-Time Passcode challenge before Prefill can be completed.
6. RiskOS™ runs Prefill.
7. RiskOS™ collects any remaining identity data needed for the hosted onboarding flow.
8. RiskOS™ runs KYC, Fraud, and Watchlist screening.
9. If no additional verification is required, the evaluation resumes and completes after the hosted flow.
10. If additional verification is required, RiskOS™ triggers Predictive Document Verification (DocV), pauses the evaluation, and delivers the final decision asynchronously via webhook (evaluation_completed, data.decision).
11. (Optional) User redirected to redirect_uri.

Evaluation processing

During the Hosted Flow, RiskOS™ orchestrates multiple products and verification steps:

Conditional One-Time Passcode

After the user provides phone number and date of birth, RiskOS™ may trigger a One-Time Passcode challenge if additional verification is required before Prefill can be completed.

One-Time Passcode is conditional. It does not occur for every consumer.

If One-Time Passcode is required, the user must complete it before Prefill continues.

Conditional Document Verification

If additional verification is required after Prefill and downstream screening, RiskOS™ triggers DocV as a step-up mechanism.

DocV is conditional. It does not occur for every consumer.

Decision delivery

RiskOS™ delivers the final decision after the hosted flow completes.

• Final decision
  • The initial API response represents a paused evaluation state and does not contain the final outcome.
  • The evaluation resumes after the user completes the hosted flow.
  • The final decision is delivered through the evaluation_completed webhook.
  • The final outcome is in data.decision.

Document Verification

If triggered, the user may be asked to:

• Capture a government-issued ID.
• Take a biometric selfie.
• Complete liveness verification.

DocV is automatically orchestrated within the hosted experience. No additional integration is required.

When DocV is triggered, the evaluation completes asynchronously and the final decision is delivered by webhook.

Lifecycle diagram

sequenceDiagram
    autonumber
    participant User as End User
    participant App as Your Platform
    participant RiskOS as RiskOS™
    participant Webhook as Your Webhook

    User->>App: Start onboarding
    App->>RiskOS: POST /api/evaluation

    activate RiskOS
    RiskOS-->>App: 201 Created + redirect URL + initial decision/state
    deactivate RiskOS

    App-->>User: Redirect to Hosted Flow
    User->>RiskOS: Enter phone number + date of birth

    activate RiskOS
    alt OTP required
        RiskOS-->>User: Prompt for OTP
        User->>RiskOS: Submit OTP
    end

    Note over RiskOS: Run Prefill
    Note over RiskOS: Collect remaining identity data
    Note over RiskOS: Run KYC, Fraud, Watchlist

    alt No DocV required
        Note over RiskOS: Complete evaluation
        RiskOS-->>Webhook: Send evaluation_completed
    else DocV required
        RiskOS-->>User: Prompt document + selfie capture
        User->>RiskOS: Submit document + selfie
        Note over RiskOS: Verify document and resume evaluation
        RiskOS-->>Webhook: Send evaluation_completed
    end

    RiskOS-->>App: Redirect to redirect_uri (optional)
    deactivate RiskOS

    Webhook-->>App: data.decision
    App-->>User: Route based on final decision

Key behaviors

• Hosted Flow URLs are session-specific and should not be reused.
• The redirect_uri indicates hosted experience completion, not final decision delivery.
• One-Time Passcode may occur conditionally before Prefill completes.
• DocV may occur conditionally after Prefill, KYC, Fraud, and Watchlist processing.
• The initial API response represents a paused evaluation and does not contain the final decision.
• The final decision is delivered via the evaluation_completed webhook.