Integrate with Consumer Onboarding

Overview

This guide covers the system integration for Consumer Onboarding: connecting your frontend and backend to the Evaluation API, submitting requests, and acting on decisions.

For workflow configuration and enrichment setup, see Configure the Workflow. For routing logic, DocV step-ups, and review flows, see Handle Review & Step-Up Flows.

System architecture

RiskOS™Your BackendDigital Intelligence SDKClient AppRiskOS™Your BackendDigital Intelligence SDKClient Appalt[ACCEPT][REJECT][REVIEW / Step-Up]Initialize SDKdi_session_tokenSubmit PII + di_session_tokenPOST /api/evaluationDecision responseContinue onboardingDeny or fallbackTrigger DocV or manual reviewFinal decision (webhook)

Integration flow

  1. Collect the Digital Intelligence session token on the client. This solution uses the Digital Intelligence SDK for device collection.
  2. Gather identity data from the consumer (name, date of birth, SSN, address, phone, email).
  3. Submit a POST /api/evaluation request from your backend with the collected data.
  4. Act on the decision field in the response to route the consumer.
  5. Handle verification and review outcomes if the workflow triggers a step-up such as OTP, Predictive DocV, or manual review. See Handle Review & Step-Up Flows.

Required components

A configured Consumer Onboarding workflow.

Integration with the Digital Intelligence SDK to collect the di_session_token.

Integration with the Predictive DocV SDK if your workflow uses document verification step-ups.

A RiskOS™ API key from Developer Workbench > API Keys in the Dashboard.

A webhook endpoint to receive results from asynchronous verification and review flows such as Predictive DocV.

Endpoint

HTTP

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

HTTP

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

Include your API key in the Authorization header:

HTTP

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
Accept: application/json

Example request

JSON

{
  "id": "a86580cc-1733-4188-86b5-717166e1db8c",
  "timestamp": "2025-05-02T12:44:22.059Z",
  "workflow": "consumer_onboarding",
  "data": {
    "individual": {
      "id": "username",
      "given_name": "Franky",
      "family_name": "Valley",
      "national_id": "555667772",
      "date_of_birth": "1992-03-11",
      "email": "frankeyV@test.com",
      "phone_number": "16673681976",
      "address": {
        "line_1": "742 Evergreen Terrace",
        "line_2": "Apt 2B",
        "locality": "Springfield",
        "major_admin_division": "IL",
        "country": "US",
        "postal_code": "62704"
      },
      "additional_context": {
        "disclosure_purpose": "GLBA_502(e)"
      },
      "di_session_token": "eyJraWQiOi_di_token",
      "docv": {
        "config": {
          "send_message": true
        }
      }
    },
    "ip_address": "203.0.113.10"
  }
}

Request fields

Top-level fields

Field Type Required Description Example
id String Required Required, customer-defined unique identifier for the request. This value must be unique for each evaluation. Reusing an ID causes RiskOS™ to treat the request as a re-run and can impact processing behavior, results, and downstream workflows. "a86580cc-1733-4188-86b5-717166e1db8c"
timestamp String <Date-Time> Required RFC 3339 timestamp indicating when the evaluation request was initiated by your system. "2025-05-02T12:44:22.059Z"
workflow String Required Your environment-specific workflow identifier. You can find this value in the RiskOS™ Dashboard > Developer Workbench > Integration Checklist. "consumer_onboarding"

Individual fields

Field Type Required Description Example
given_name String Required Consumer's first/given name (max 240 characters). "Franky"
family_name String Required Consumer's last/family name (max 240 characters). "Valley"
national_id String Required National identifier such as SSN, SIN, or equivalent, depending on geography. "555667772"
date_of_birth String Required Consumer's date of birth in ISO 8601 format (YYYY-MM-DD). "1992-03-11"
email String Required Consumer's email address (must be a valid email format). "frankeyV@test.com"
phone_number String Required Consumer's phone number. The API expects E.164 format but tolerates hyphens and spaces for user convenience. "16673681976"
di_session_token String (UUID) Required Token from the Digital Intelligence SDK that links the device session. Must be generated client-side before submitting the evaluation. "eyJraWQiOi_di_token"

Address fields

Field Type Required Description Example
line_1 String Optional The first line of the consumer's address. "742 Evergreen Terrace"
line_2 String Optional An optional second line for the address, such as apartment number, suite, or building landmarks. "Apt 2B"
locality String Optional City, town, or village name where the consumer resides. "Springfield"
major_admin_division String Optional The state, province, or region where the consumer resides. "IL"
country String Optional The country where the consumer resides, specified in ISO 3166-1 alpha-2 country code format. "US"
postal_code String Optional The consumer's ZIP code, postal code, or equivalent regional identifier for mail delivery. "62704"

Additional context fields

Field Type Required Description Example
disclosure_purpose String Conditional Disclosure for running Sigma First-Party Fraud product. "GLBA_502(e)"

Predictive DocV fields

Field Type Required Description Example
docv Object Conditional Configuration object used when the workflow escalates an applicant to Predictive DocV for document verification and biometric review. { "config": { "send_message": true } }

Handling responses

Decision routing

Decision Action
ACCEPT Continue onboarding
REJECT Deny the application or route to a fallback flow
REVIEW Trigger a step-up (DocV, manual review) depending on workflow configuration

Use the decision field as your primary control signal. Do not use status, sub_status, or eval_status for business decisions — those fields describe evaluation lifecycle state only.

Example response

Example response (truncated)

{
  "id": "895dc35b-cee7-4f14-af06-6e26482178f8",
  "workflow": "consumer_onboarding",
  "eval_id": "b1c0e610-822d-4793-a970-8bfc0a9b883f",
  "decision": "ACCEPT",
  "status": "CLOSED",
  "eval_status": "evaluation_completed",
  "score": 11,
  "data_enrichments": [
    {
      "enrichment_name": "Socure Digital Intelligence",
      "status_code": 200
    },
    {
      "enrichment_name": "Socure Verify Plus",
      "status_code": 200
    },
    {
      "enrichment_name": "Socure Global Watchlist Plus",
      "status_code": 200
    }
  ]
}

Key response fields

Area Fields Purpose
Decision and routing decision, tags, review_queues, score Primary signals for application logic and secondary routing
Traceability id, eval_id Persist for correlation across API calls, logs, webhooks, and support
Enrichment results data_enrichments[] Module-specific scores, reason codes, and signals
Workflow context workflow, workflow_id, workflow_version Debugging and version tracking
Lifecycle eval_status, status, sub_status Monitoring and async flow tracking only

For complete response field definitions, see the Evaluation API Reference.