Prefill + KYC + Watchlist > DocV Step Up Direct API

Overview

The Direct API lifecycle allows your platform to collect identity data, submit it to RiskOS™, and progressively complete an evaluation through API calls.

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 Prefill, KYC, Fraud, Watchlist, and conditional step-up verification.

Key behaviors

End-to-end flow

1. Collect initial user data (typically phone number, date of birth, and country).
2. Generate a di_session_token using the Digital Intelligence SDK.
3. Create an evaluation (POST /api/evaluation).
4. RiskOS™ evaluates device and phone risk signals.
5. If device or phone risk fails, the evaluation is immediately rejected.
6. If additional verification is required, RiskOS™ may trigger a One-Time Passcode (OTP) challenge.
7. After OTP (if required), RiskOS™ runs Prefill.
8. Your application collects any additional required identity data.
9. Continue the evaluation (PATCH /api/evaluation/{eval_id}).
10. RiskOS™ runs KYC, Fraud, and Watchlist screening.
11. If no additional verification is required, a final decision is returned synchronously.
12. If additional verification is required, RiskOS™ triggers Document Verification (DocV), pauses the evaluation, and resumes asynchronously via webhook.
13. Route the user based on the final decision.

Your WebhookRiskOS™Your BackendYour FrontendEnd UserYour WebhookRiskOS™Your BackendYour FrontendEnd User
Run Digital Intelligence + Phone Risk
alt[High risk device or phone][Additional verification required]
Run Prefill
alt[Prefill successful][Prefill unsuccessful]
Run KYC, Fraud, Watchlist
alt[No DocV required][DocV required]
Enter initial identity data
1Generate di_session_token
2Submit data
3POST /api/evaluation
4REJECT
5Reject user
6REVIEW (ON_HOLD)
7Prompt OTP
8Enter OTP
9Submit OTP
10PATCH /evaluation/{eval_id}
11Show prefilled data
12Collect full identity data
13Submit additional PII
14PATCH /evaluation/{eval_id}
15ACCEPT or REJECT
16evaluation_paused + docvTransactionToken
17Launch DocV
18Submit document + selfie
19evaluation_completed
20Final decision
21Route user
22

Evaluation processing

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

• Digital Intelligence: Evaluates device and behavioral risk signals early in the flow.
• Phone Risk: Validates phone integrity and risk indicators.
• One-Time Passcode (OTP): Conditional verification step before Prefill.
• Prefill: Enriches identity data using authoritative sources.
• KYC: Verifies identity against trusted providers.
• Fraud: Evaluates identity and behavioral fraud signals.
• Watchlist: Screens against sanctions, PEP, and adverse media.
• Document Verification (DocV): Step-up verification when additional validation is required.

Conditional One-Time Passcode

After submitting phone number and date of birth, RiskOS™ may require OTP verification before Prefill can proceed.

OTP is conditional and triggered based on risk signals.

If triggered:

• The evaluation returns REVIEW and ON_HOLD
• Your application must collect a 6-digit code
• You must continue the evaluation with a PATCH request

If OTP fails, the system rejects the evaluation.

Conditional Document Verification (DocV)

After Prefill and downstream checks, RiskOS™ may require DocV.

DocV is triggered when additional verification is needed based on fraud, identity, or risk signals.

If triggered:

• The evaluation pauses (evaluation_paused)
• A docvTransactionToken is returned in data_enrichments
• Your application must launch the DocV SDK or redirect the user
• The evaluation completes asynchronously via webhook

Decision delivery

RiskOS™ may return decisions in two ways:

Synchronous decision

Returned immediately after API request:

• ACCEPT → continue onboarding
• REJECT → stop or route to fallback
• REVIEW → additional steps required

Asynchronous decision

Occurs when DocV is triggered:

• Evaluation pauses during verification
• Final decision is delivered via webhook (evaluation_completed)
• Outcome is in data.decision

End-to-end code walkthrough

This walkthrough shows the full Direct API sequence: create an evaluation, submit an OTP, submit identity data, and handle the final decision via webhook.

1. Create the evaluation (POST)

curl --request POST \
  --url "https://riskos.sandbox.socure.com/api/evaluation" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "id": "session_abc123",
    "timestamp": "2026-04-15T14:00:00Z",
    "workflow": "non_hosted_advanced_pre_fill",
    "data": {
      "individual": {
        "phone_number": "+14155550001",
        "date_of_birth": "1990-05-15",
        "di_session_token": "tok_device_session",
        "address": {
          "country": "US"
        }
      }
    }
  }'

Response — OTP required:

{
  "eval_id": "296652a5-0a17-4e9f-8f2c-534076fefcd7",
  "decision": "REVIEW",
  "status": "ON_HOLD",
  "sub_status": "Awaiting Customer OTP",
  "tags": ["OTP Triggered"]
}

2. Submit the OTP (PATCH)

curl --request PATCH \
  --url "https://riskos.sandbox.socure.com/api/evaluation/296652a5-0a17-4e9f-8f2c-534076fefcd7" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "id": "session_abc123",
    "timestamp": "2026-04-15T14:01:00Z",
    "workflow": "non_hosted_advanced_pre_fill",
    "data": {
      "individual": {
        "otp": {
          "code": "482901"
        }
      }
    }
  }'

Response — OTP verified, additional identity data required:

{
  "eval_id": "296652a5-0a17-4e9f-8f2c-534076fefcd7",
  "decision": "REVIEW",
  "status": "ON_HOLD",
  "sub_status": "More information needed",
  "tags": ["OTP Triggered", "OTP Approved", "Prefill Successful", "Additional PII Requested"]
}

3. Submit identity data (PATCH)

curl --request PATCH \
  --url "https://riskos.sandbox.socure.com/api/evaluation/296652a5-0a17-4e9f-8f2c-534076fefcd7" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "id": "session_abc123",
    "timestamp": "2026-04-15T14:02:00Z",
    "workflow": "non_hosted_advanced_pre_fill",
    "data": {
      "individual": {
        "given_name": "Jane",
        "family_name": "Smith",
        "date_of_birth": "1990-05-15",
        "email": "jane.smith@example.com",
        "phone_number": "+14155550001",
        "address": {
          "line_1": "123 Main St",
          "locality": "Newark",
          "major_admin_division": "NJ",
          "postal_code": "07102",
          "country": "US"
        }
      }
    }
  }'

Response — evaluation accepted:

{
  "eval_id": "296652a5-0a17-4e9f-8f2c-534076fefcd7",
  "decision": "ACCEPT",
  "status": "CLOSED",
  "tags": ["OTP Triggered", "OTP Approved", "Prefill Successful"]
}

If Document Verification (DocV) is triggered instead, the response contains eval_status: "evaluation_paused" and a docvTransactionToken in data_enrichments. Launch the DocV SDK and wait for the evaluation_completed webhook.

4. Receive the webhook (asynchronous decisions)

For evaluations that require Document Verification (DocV), the final decision arrives via webhook:

{
  "event_type": "evaluation_completed",
  "data": {
    "eval_id": "296652a5-0a17-4e9f-8f2c-534076fefcd7",
    "decision": "ACCEPT",
    "status": "CLOSED",
    "evaluation_status": "evaluation_completed"
  }
}

Route the user based on data.decision.

Next steps

• Start a new evaluation
• Handle results
• Update an evaluation
• Handle additional verification