Direct API

Start building

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.

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 One-Time Passcode (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.

Evaluation processing

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

Conditional One-Time Passcode

After submitting phone number and date of birth, RiskOS™ may require One-Time Passcode verification before Prefill can proceed.

One-Time Passcode 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 One-Time Passcode fails, the evaluation is rejected.

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

Lifecycle diagram

sequenceDiagram
    autonumber
    participant User as End User
    participant Frontend as Your Frontend
    participant Backend as Your Backend
    participant RiskOS as RiskOS™
    participant Webhook as Your Webhook

    User->>Frontend: Enter initial identity data
    Frontend->>Frontend: Generate di_session_token
    Frontend->>Backend: Submit data
    Backend->>RiskOS: POST /api/evaluation

    activate RiskOS
    Note over RiskOS: Run Digital Intelligence + Phone Risk

    alt High risk device or phone
        RiskOS-->>Backend: REJECT
        Backend-->>Frontend: Reject user
    else Additional verification required
        RiskOS-->>Backend: REVIEW (ON_HOLD)
        Backend-->>Frontend: Prompt OTP
        User->>Frontend: Enter OTP
        Frontend->>Backend: Submit OTP
        Backend->>RiskOS: PATCH /evaluation/{eval_id}
    end

    Note over RiskOS: Run Prefill

    alt Prefill successful
        Backend-->>Frontend: Show prefilled data
    else Prefill unsuccessful
        Backend-->>Frontend: Collect full identity data
    end

    Frontend->>Backend: Submit additional PII
    Backend->>RiskOS: PATCH /evaluation/{eval_id}

    activate RiskOS
    Note over RiskOS: Run KYC, Fraud, Watchlist

    alt No DocV required
        RiskOS-->>Backend: ACCEPT or REJECT
    else DocV required
        RiskOS-->>Backend: evaluation_paused + docvTransactionToken
        Backend-->>Frontend: Launch DocV
        User->>RiskOS: Submit document + selfie
        RiskOS-->>Webhook: evaluation_completed
    end

    Webhook-->>Backend: Final decision
    Backend-->>Frontend: Route user

End-to-end code walkthrough

This walkthrough shows the full Direct API sequence: create an evaluation, submit a One-Time Passcode, 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 — One-Time Passcode required:

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

2. Submit the One-Time Passcode (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 — One-Time Passcode 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": "[email protected]",
        "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",
    "eval_status": "evaluation_completed"
  }
}

Route the user based on data.decision.

Key behaviors

• Your application is responsible for collecting and validating all identity data.
• All API requests must be made server-to-server using your API key.
• The evaluation is stateful and progresses using eval_id.
• One-Time Passcode may occur conditionally before Prefill completes.
• Prefill may succeed or fail and impacts UI behavior.
• DocV may occur conditionally after downstream checks.
• Synchronous decisions are returned immediately when no step-up is required.
• Asynchronous decisions are delivered via webhook when DocV is triggered.