Integration Guide

Socure Advanced Prefill API integration guide

This guide walks you through how to integrate with Socure’s /api/evaluation endpoint using the Advanced Prefill workflow. You’ll learn how to send minimal input data, parse the enriched response, and apply decision logic to support onboarding, fraud prevention, and conversion optimization workflows.

Onboarding with Advanced Prefill consists of two connected workflows:

Before you start

Make sure your RiskOS™ environment is provisioned with:

Choose your environment

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

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

Get an API key

How it works

1. Send a POST /api/evaluation request using the Advanced Prefill workflow (alt_advanced_pre_fill) with minimal identity + device data.
2. RiskOS™ decides whether it’s safe to show prefilled identity details (ACCEPT, REJECT, or ON_HOLD).
3. If ON_HOLD, complete One-Time Passcode (OTP) verification and resume the same evaluation with PATCH /api/evaluation/{eval_id}.
4. If ACCEPT, display prefill results for user confirmation (keep sensitive fields read-only); if REJECT, show a blank form.
5. After confirmation, start a new POST /api/evaluation using the Consumer Onboarding workflow (consumer_onboarding) to get the final onboarding decision.

Integration flow

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 → Phone Risk → SIM Swap → SNA / OTP → Prefill → Re-check
    SC-->>CP: Decision (APPROVE / REJECT / ON_HOLD)

    alt REJECT
        CP-->>EU: Show blank form for manual entry
    else APPROVE
        CP-->>EU: Show prefilled form (lock phone and DOB)
    else ON_HOLD
        CP-->>EU: Prompt OTP entry
        EU->>CP: Enter OTP
        CP->>SC: PATCH /api/evaluation with OTP
        SC->>SC: Validate OTP
        SC-->>CP: Updated decision
        CP-->>EU: Show prefilled if APPROVE, blank if REJECT
    end

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

Potential scenarios

Step 1 - Collect minimal user input

Configure your platform to collect the following minimal input from the user:

👍

Tip:

Adding additional personally identifiable information (PII) can improve match accuracy.

Step 2 - Start a new evaluation

Endpoint

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

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

Authentication and headers

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

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 schema

Top-level fields

individual fields

address fields

Receive a decision

You’ll receive a decision and enrichment results from the Advanced Prefill workflow. Look for the following fields:

{
  "eval_id": "126",
  "decision": "ACCEPT",
  "status": "COMPLETED",
  "data_enrichments": {
    "given_name": "Alex",
    "family_name": "Martin",
    "docv_status": "PASSED"
  }

{
  "eval_id": "af-1a2b3c",
  "workflow": "alt_advanced_pre_fill",
  "status": "ON_HOLD",
  "decision": "ON_HOLD",
  "reasonCodes": ["OTP_REQUIRED"]
}

{
  "eval_id": "af-1a2b3c",
  "workflow": "alt_advanced_pre_fill",
  "status": "COMPLETED",
  "decision": "REJECT",
}

Key fields

Prefill fields

Step 3 — Handle One-Time Passcode (if required)

If RiskOS™ can’t validate phone possession via Silent Network Authentication (SNA), the evaluation returns status: ON_HOLD and an One-Time Passcode is automatically sent to the user’s phone. Prompt the user to enter a 6-digit code to continue.

When the user submits the One-Time Passcode, resume the same evaluation with a PATCH to the /api/evaluation/{eval_id} endpoint. See One-Time Passcode Integration Guide for more information.

{
  "id": "advanced-prefill-03f1de",
  "timestamp": "2025-09-11T12:00:00Z",
  "workflow": "alt_advanced_pre_fill",
  "data": {
    "individual": {
      "otp": {
        "code": "123456"
      }
    }
  }
}

curl --location --request PATCH 'https://riskos.sandbox.socure.com/api/evaluation/{eval_id}' \
  --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": {
        "otp": {
          "code": "123456"
        }
      }
    }
  }'

Request schema

Receive a decision

You’ll receive a decision and enrichment results from the Advanced Prefill workflow.

{
  "verification": {
    "otp": {
      "response": {
        "attemptCount": 1,
        "status": "approved",
        "verificationId": "test-verification-001"
      }
    }
  }
}

Response schema

Top-level fields

decision values are workflow-specific and may differ from the examples shown in this guide.

data_enrichments fields

Resuming with missing identity data

If the One-Time Passcode is verified successfully but the response returns status: "ON_HOLD" with a sub_status: "More information needed", it indicates that the system has verified device possession but requires manual entry of PII to complete the prefill.

How to resume

Issue a PATCH request to the /api/evaluation/{eval_id} endpoint.

• URL: Append the eval_id from the initial response to the endpoint.
• Body: Include all mandatory top-level fields and the collected PII within the individual object.

Body: Include all mandatory top-level fields and the collected PII within the individual object.

Example Patch request to resume

{
  "id": "advanced-prefill-03f1de",
  "workflow": "alt_advanced_pre_fill",
  "timestamp": "2026-02-13T16:38:37Z",
  "data": {
    "individual": {
      "given_name": "Jane",
      "family_name": "Smith",
      "address": {
        "line_1": "123 Main St",
        "locality": "Newark",
        "major_admin_division": "NJ",
        "postal_code": "07102",
        "country": "US"
      }
    }
  }
}

curl --location --request PATCH 'https://riskos.sandbox.socure.com/api/evaluation/ap_559771af-a321-4c67-ad53-27cd17f27b60' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_API_KEY' \
--data-raw '{
  "id": "advanced-prefill-03f1de",
  "workflow": "alt_advanced_pre_fill",
  "timestamp": "2026-02-13T16:38:37Z",
  "data": {
    "individual": {
      "given_name": "Jane",
      "family_name": "Smith",
      "address": {
        "line_1": "123 Main St",
        "locality": "Newark",
        "major_admin_division": "NJ",
        "postal_code": "07102",
        "country": "US"
      }
    }
  }
}'

Step 4 — Display the Prefill results

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

• If APPROVE: Display the prefilled data returned by RiskOS™. Lock sensitive fields such as phone_number and date_of_birth so the user cannot modify them.

• If REJECT: Do not prefill any data. Present an empty form and allow the user to enter their information manually.

• If ON_HOLD: Pause until the One-Time Passcode verification process completes and Socure returns an updated response.

After the prefilled data (if any) is shown, prompt the user to review and confirm their information:

• Users may edit or confirm non-sensitive fields (e.g., name, address, email).
• The original phone_number and date_of_birth fields must remain read-only.
• If Prefill was rejected, collect all required fields manually.

When the user submits the form:

1. Capture all confirmed or manually entered fields.
2. Prepare the payload for the next workflow, consumer_onboarding.
3. Reuse the same di_session_token from the original Prefill request.

Once complete, proceed to Step 5 — Start the Consumer Onboarding workflow to initiate full KYC and fraud checks.

Step 5 — Start the Consumer Onboarding workflow

After the user reviews and confirms their information, send a new POST request to the /api/evaluation endpoint using the Consumer Onboarding workflow. This workflow performs full KYC and fraud evaluations and returns the final onboarding decision.

See Consumer Onboarding for more information.

{
  "id": "onb-12345",
  "timestamp": "2023-12-01T08:15:30.456Z",
  "workflow": "consumer_onboarding",
  "data": {
    "individual": {
      "id": "ind-9876543",
      "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"
      }
    },
    "line_of_business": "ACME Inc",
    "channel": "web",
    "ip_address": "203.0.113.10"
  }
}

curl --request POST \
     --url https://riskos.socure.com/api/evaluation \
     --header 'Authorization: Bearer YOUR_API_KEY' \
     --header 'Accept: application/json' \
     --header 'Content-Type: application/json' \
     --data '{
  "data": {
    "individual": {
      "address": {
        "line_1": "742 Evergreen Terrace",
        "line_2": "Apt 12B",
        "locality": "Springfield",
        "major_admin_division": "IL",
        "country": "US",
        "postal_code": "62704"
      },
      "id": "ind-9876543",
      "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"
    },
    "line_of_business": "ACME Inc",
    "channel": "web",
    "ip_address": "203.0.113.10"
  },
  "id": "onb-12345",
  "timestamp": "2023-12-01T08:15:30.456Z",
  "workflow": "consumer_onboarding"
}'

Request schema

Top-level fields

individualfields

addressfields

Test in Sandbox

The Sandbox environment uses mock API requests and response. You can use Sandbox to simulate various identity and fraud scenarios.

• Endpoint: POST /api/evaluation
• Base URL (Sandbox): https://riskos.sandbox.socure.com/api/evaluation
• Auth: Authorization: Bearer YOUR_SANDBOX_KEY

Sandbox personas

Validation checklist

Inputs

Routing & policy

Errors & resilience