Integration Guide

Overview

This integration has two stages:

1. Advanced Prefill

   • Collect phone_number, date_of_birth, and di_session_token.
   • Send POST /api/evaluation with the Advanced Prefill workflow.
   • If the response returns status: ON_HOLD, collect a One-Time Passcode and resume the same evaluation with PATCH /api/evaluation/{eval_id}.
   • If the final Prefill decision is ACCEPT, display prefilled identity data.
   • If the final Prefill decision is REJECT, display a blank onboarding form.

2. Consumer Onboarding

   • Create a new evaluation.
   • Send POST /api/evaluation with the Consumer Onboarding workflow.
   • Reuse the confirmed phone_number, date_of_birth, and original di_session_token.
   • Submit the full onboarding payload and use the final onboarding decision for routing.

Before you start

Make sure you have:

Advanced Prefill quickstart

Endpoint

Start with Sandbox for development and testing, then move to Production for live applications.

https://riskos.sandbox.socure.com/api/evaluation

Authentication

Include your API key in the Authorization header as a Bearer token, along with standard JSON headers:

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
Accept: application/json
X-API-Version: 2025-01-01.orion   # optional – pins a specific API version

Minimum example request

{
  "id": "a86580cc-1733-4188-86b5-717166e1db8c",
  "timestamp": "2026-04-02T12:00:00Z",
  "workflow": "alt_advanced_pre_fill",
  "data": {
    "individual": {
      "phone_number": "+16673681976",
      "date_of_birth": "1992-03-11",
      "di_session_token": "YOUR_DI_SESSION_TOKEN"
    }
  }
}

curl --request POST \
  --url https://riskos.sandbox.socure.com/api/evaluation \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --data '{
    "id": "a86580cc-1733-4188-86b5-717166e1db8c",
    "timestamp": "2026-04-02T12:00:00Z",
    "workflow": "alt_advanced_pre_fill",
    "data": {
      "individual": {
        "phone_number": "+16673681976",
        "date_of_birth": "1992-03-11",
        "di_session_token": "YOUR_DI_SESSION_TOKEN"
      }
    }
  }'

Decision handling (Advanced Prefill)

Note: ON_HOLD is a temporary state triggered when additional verification (One-Time Passcode) is required.

Common outcomes

What matters for your integration (Advanced Prefill)

📘

Key differences from Consumer Onboarding:

• Prefill uses minimal inputs only (no full PII).
• Prefill decisions are data disclosure decisions, not final KYC.
• Prefill may enter ON_HOLD (One-Time Passcode step-up) — onboarding does not use this pattern.
• A new evaluation must be created for the Consumer Onboarding workflow.

Advanced Prefill integration contract

endpoint: POST /api/evaluation
workflow: alt_advanced_pre_fill

authentication:
  type: Bearer token
  header: Authorization

content_type: application/json

required_top_level_fields:
  - id
  - timestamp
  - workflow
  - data

required_identity_fields:
  - phone_number
  - date_of_birth

required_device_field:
  - di_session_token

primary_decision_field: decision

important_response_fields:
  - decision
  - eval_id
  - status
  - tags

traceability_fields:
  - id
  - eval_id

do_not_use_for_primary_decision:
  - sub_status

How the workflow evaluates a user

After you submit an Advanced Prefill evaluation request, RiskOS™ determines whether it is safe to return prefilled identity data. This workflow performs risk-based gating using device, phone, and network signals before allowing any data disclosure.

Typical stages include:

1. Device and network risk
   Review Digital Intelligence signals such as device integrity, network risk, velocity, and behavioral patterns.

2. Deny list screening
   Check the user’s email, phone, device, and IP against configured deny lists.

3. Phone risk and SIM swap detection
   Evaluate phone number risk and indicators of SIM swap or ineligible phone activity.

4. Silent Network Authentication (SNA)
   Attempt to verify phone possession using carrier-based authentication. If SNA fails, the workflow may require step-up verification.

5. One-Time Passcode step-up verification (conditional)
   If additional verification is required, the evaluation enters an ON_HOLD state and requires a one-time passcode to continue.

6. Prefill enrichment
   Retrieve prefilled identity data from Socure. If required identity attributes are not returned, the evaluation is rejected.

7. Final decision
   Return a data disclosure decision indicating whether prefilled identity data can be shown to the user.

sequenceDiagram
    participant EU as End User
    participant CP as Your Platform
    participant SC as Socure

    EU->>CP: Enter phone and DOB
    CP->>SC: POST /api/evaluation alt_advanced_pre_fill

    SC->>SC: Run DI → Deny Lists → Phone Risk / SIM Swap

    alt High risk or deny list match
        SC-->>CP: Decision (REJECT)
        CP-->>EU: Show blank form for manual entry
    else Pass initial checks
        SC->>SC: Attempt SNA

        alt SNA success
            SC->>SC: Run Prefill
            SC-->>CP: Decision (ACCEPT or REJECT)
        else SNA fail
            SC-->>CP: status = ON_HOLD (OTP required)
            CP-->>EU: Prompt OTP entry
            EU->>CP: Enter OTP
            CP->>SC: PATCH /api/evaluation with OTP
            SC->>SC: Resume → Run Prefill
            SC-->>CP: Decision (ACCEPT or REJECT)
        end

        alt ACCEPT
            CP-->>EU: Show prefilled form (lock phone and DOB)
        else REJECT
            CP-->>EU: Show blank form for manual entry
        end
    end

    EU->>CP: Review and submit
    CP->>SC: POST /api/evaluation consumer_onboarding (new evaluation)
    SC->>SC: Run KYC and fraud checks
    SC-->>CP: Final decision (ACCEPT / REVIEW / REJECT)
    CP-->>EU: Show onboarding result

Request schema

The example below shows a typical Advanced Prefill request using minimal inputs, including phone number, date of birth, and device data (di_session_token) to evaluate whether prefilled identity data can be returned.

Example request

{
  "id": "advanced-prefill-03f1de",
  "timestamp": "2025-09-11T12:00:00Z",
  "workflow": "alt_advanced_pre_fill",
  "data": {
    "individual": {
      "phone_number": "+14155550001",
      "date_of_birth": "1990-05-15",
      "di_session_token": "sess_123",
      "address": {
        "country": "US"
      }
    }
  }
}

curl --location --request POST 'https://riskos.sandbox.socure.com/api/evaluation' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --data-raw '{
    "id": "advanced-prefill-03f1de",
    "timestamp": "2025-09-11T12:00:00Z",
    "workflow": "alt_advanced_pre_fill",
    "data": {
      "individual": {
        "phone_number": "+14155550001",
        "date_of_birth": "1990-05-15",
        "di_session_token": "sess_123",
        "address": {
          "country": "US"
        }
      }
    }
  }'

Request structure overview

id
timestamp
workflow
data
└─ individual
  ├─ phone_number
  ├─ date_of_birth
  └─ di_session_token

Common identity and device fields

The table below lists the typical identity and device inputs that can be provided to the Advanced Prefill workflow.

Only a minimal subset is required to perform the Prefill lookup. Additional fields may be included to improve match accuracy and enable additional checks.

Field reference

Top-level fields

individual fields

👍

Tip:

Adding additional PII can improve match accuracy.

address fields

Interpret the response

Use the Advanced Prefill response to decide whether to:

• show prefilled identity data,
• collect a One-Time Passcode, or
• fall back to a blank onboarding form.

Response handling rules

Example response

{
  "id": "advanced-prefill-03f1de",
  "workflow": "alt_advanced_pre_fill",
  "eval_id": "7bc4b7c8-eb67-429b-919a-cdc9ab3c590f",
  "decision": "ACCEPT",
  "status": "CLOSED",
  "data_enrichments": [
    {
      "enrichment_name": "Socure Prefill",
      "response": {
        "prefill": {
          "firstName": "Alex",
          "surName": "Martin"
        }
      }
    }
  ]
}

{
  "workflow": "alt_advanced_pre_fill",
  "status": "ON_HOLD",
  "sub_status": "Awaiting Customer OTP"
}

{
  "workflow": "alt_advanced_pre_fill",
  "decision": "REJECT"
}

Note: These examples are illustrative. Actual response payloads may include additional evaluation metadata such as id, eval_id, status, and sub_status.

Key fields

Prefill fields

The Prefill data is returned in the Socure Prefill enrichment response.

Note: Additional identity attributes (such as address or other profile data) may be returned depending on data availability and configuration.

Handle One-Time Passcode (if required)

If the Advanced Prefill evaluation returns status: ON_HOLD (with sub_status = Awaiting Customer OTP), collect a One-Time Passcode and resume the same evaluation. See One-Time Passcode Integration Guide for more information.

Resume request

Use the eval_id returned from the initial Advanced Prefill response.

Send a PATCH request to:

/api/evaluation/{eval_id}

Required fields

Outcome handling

After the PATCH request, RiskOS™ resumes the same evaluation and returns an updated response.

Display the Prefill results

Once the Advanced Prefill evaluation completes, use the returned outcome to determine how to display the form and collect user confirmation.

• If ACCEPT: Display the prefilled data returned by RiskOS™.
• If REJECT: Do not prefill any data. Present an empty form and allow the user to enter their information manually.

After prefilled data is shown, prompt the user to review and confirm their information.

• Users may edit or confirm non-sensitive fields such as name, address, or email.
• The original phone_number and date_of_birth values should remain read-only.
• If Prefill is rejected, collect the required onboarding fields manually.

When the user submits the form:

1. Capture all confirmed or manually entered fields.
2. Prepare the payload for the Consumer Onboarding workflow.
3. Reuse the original di_session_token from the Advanced Prefill request.

Then create a new evaluation using the Consumer Onboarding workflow.

Start the Consumer Onboarding workflow

After the user reviews and confirms their information, create a new evaluation and send a new POST /api/evaluation request using workflow: consumer_onboarding.

What to carry forward from Advanced Prefill

• Create a new top-level id
• Reuse the confirmed phone_number
• Reuse the confirmed date_of_birth
• Reuse the original di_session_token
• Include any prefilled or user-confirmed identity fields required by your Consumer Onboarding workflow
• Do not reuse the Advanced Prefill eval_id

See Consumer Onboarding for complete request and response details.

{
  "id": "onb-12345",
  "timestamp": "2023-12-01T08:15:30.456Z",
  "workflow": "consumer_onboarding",
  "data": {
    "individual": {
      "given_name": "Jane",
      "family_name": "Smith",
      "national_id": "123456789",
      "date_of_birth": "1990-05-15",
      "email": "[email protected]",
      "phone_number": "+1-312-555-1234",
      "di_session_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzUxMiJ...PiUsws9D6O3DjSjNDCbIJKciX44s",
      "address": {
        "line_1": "742 Evergreen Terrace",
        "line_2": "Apt 12B",
        "locality": "Springfield",
        "major_admin_division": "IL",
        "country": "US",
        "postal_code": "62704"
      },
      "additional_context": {
        "disclosure_purpose": "GLBA_502(e)"
      }
    }
  }
}

curl --request POST \
  --url https://riskos.sandbox.socure.com/api/evaluation \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{
    "id": "onb-12345",
    "timestamp": "2023-12-01T08:15:30.456Z",
    "workflow": "consumer_onboarding",
    "data": {
      "individual": {
        "given_name": "Jane",
        "family_name": "Smith",
        "email": "[email protected]",
        "phone_number": "+1-312-555-1234",
        "date_of_birth": "1990-05-15",
        "national_id": "123456789",
        "di_session_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzUxMiJ...PiUsws9D6O3DjSjNDCbIJKciX44s",
        "address": {
          "line_1": "742 Evergreen Terrace",
          "line_2": "Apt 12B",
          "locality": "Springfield",
          "major_admin_division": "IL",
          "country": "US",
          "postal_code": "62704"
        },
        "additional_context": {
          "disclosure_purpose": "GLBA_502(e)"
        }
      }
    }
  }'

Validation checklist

Inputs

Routing & policy

Errors & resilience