Build the Integration

Connect your systems to the RiskOS™ Evaluation API to submit Consumer Onboarding evaluations and handle decisions.

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

sequenceDiagram
    participant Client as Client App
    participant DI as Digital Intelligence SDK
    participant Backend as Your Backend
    participant RiskOS as RiskOS™

    Client->>DI: Initialize SDK
    DI-->>Client: di_session_token
    Client->>Backend: Submit PII + di_session_token
    Backend->>RiskOS: POST /api/evaluation
    RiskOS-->>Backend: Decision response
    alt ACCEPT
        Backend-->>Client: Continue onboarding
    else REJECT
        Backend-->>Client: Deny or fallback
    else REVIEW / Step-Up
        Backend-->>Client: Trigger DocV or manual review
        RiskOS-->>Backend: Final decision (webhook)
    end

Integration flow

Collect the Digital Intelligence session token on the client. This solution uses the Digital Intelligence SDK for device collection.
Gather identity data from the consumer (name, date of birth, SSN, address, phone, email).
Submit a POST /api/evaluation request from your backend with the collected data.
Act on the decision field in the response to route the consumer.
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.

Postman Collection

Endpoint

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

Include your API key in the Authorization header:

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

Example request

{
  "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": "[email protected]",
      "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"
  }
}

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": "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": "[email protected]",
        "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

📘
Note:
For the complete field schema, see the Evaluation API Reference.

Top-level fields

Path: root request object

Field	Type	Required	Description
`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.
`timestamp`	String `<Date-Time>`	Required	RFC 3339 timestamp indicating when the evaluation request was initiated by your system.
`workflow`	String	Required	Your environment-specific workflow identifier. You can find this value in the RiskOS™ Dashboard > Developer Workbench > Integration Checklist.

Individual fields

Path: data.individual

Field	Type	Required	Description
`given_name`	String	Required	Consumer's first/given name (max 240 characters).
`family_name`	String	Required	Consumer's last/family name (max 240 characters).
`national_id`	String	Required	National identifier such as SSN, SIN, or equivalent, depending on geography.
`date_of_birth`	String	Required	Consumer's date of birth in ISO 8601 format (`YYYY-MM-DD`).
`email`	String	Required	Consumer's email address (must be a valid email format).
`phone_number`	String	Required	Consumer's phone number. The API expects E.164 format but tolerates hyphens and spaces for user convenience.
`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.

Address fields

Path: data.individual.address

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

Additional context fields

Path: data.individual.additional_context

Field	Type	Required	Description
`disclosure_purpose`	String	Conditional	Disclosure for running Sigma First-Party Fraud product.

Predictive DocV fields

Path: data.individual.docv

Field	Type	Required	Description
`docv`	Object	Conditional	Configuration object used when the workflow escalates an applicant to Predictive DocV for document verification and biometric review.

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

{
  "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.

Async flow references

When the workflow triggers a step-up such as Predictive DocV, the evaluation pauses and completes asynchronously. Your integration receives the final decision through a webhook.

For details on detecting paused evaluations, extracting DocV handoff tokens, and handling the async lifecycle, see Handle Review & Step-Up Flows.

For background on synchronous vs asynchronous behavior, see Synchronous vs Asynchronous Evaluations.

Integration testing

Known good applicants return ACCEPT

High-risk or synthetic applicants return REJECT or REVIEW

Required request fields are validated before submission

Identity, address, and di_session_token formats match schema requirements

Error responses are captured, logged, and handled

Webhook endpoint receives and processes evaluation_completed events

id and eval_id are persisted for traceability

Before going live

Production API key is provisioned and securely stored

Production workflow is published and active

Webhook endpoint is registered in the Production Dashboard

Monitoring is configured for decision distribution and latency

Sensitive data (national ID, date of birth, API keys) is redacted from logs

For a comprehensive go-live process, see the Go-Live Checklist.

FAQs

What format should the di_session_token be in?

The di_session_token is a JWT string generated by the Digital Intelligence SDK on the client side. Pass it as-is to the Evaluation API. See the Digital Intelligence SDK documentation for integration details.

Can I use the Evaluation API without the Digital Intelligence SDK?

You can submit requests without a di_session_token, but the Digital Intelligence enrichment does not produce device risk signals. This may reduce the accuracy of downstream fraud and risk scoring. For third-party device data, use the external_device fields instead.

How do I know if my evaluation completed synchronously or asynchronously?

Check the eval_status field. If it is "evaluation_completed", the result is final. If it is "evaluation_paused", the workflow is waiting for a step-up (such as DocV) and the final result arrives via webhook.

What should I do if the API returns an error?

Log the error response including the id you submitted and any error details returned. Use exponential backoff with jitter for transient errors (5xx). For 4xx errors, validate your request against the schema requirements above.

Related concepts

Updated 5 days ago