Integrating with RiskOS™

RiskOS™ is Socure's real-time identity and risk decisioning platform. It connects your applications directly to Socure's products using REST APIs and webhooks, enabling you to evaluate users, detect fraud, and automate compliance decisions as events happen.

What you can do with RiskOS™

Integration with RiskOS™ means your systems can:

Send evaluations

Send evaluation requests with user or transaction data to trigger real-time workflows.

Get instant decisions

Receive structured risk insights and decision outcomes (e.g., ACCEPT, REJECT, REVIEW).

Stay in sync

Subscribe to webhook events to stay updated on case decisions, workflow progress, and watchlist changes.

How it works

flowchart LR
    EndUser[Consumer]
    Customer["Your Application"]
    RiskOS[RiskOS™ Platform]

    EndUser -->|Initiates Action| Customer
    Customer -->|Sends Data / Request| RiskOS
    RiskOS -->|Returns Decision / Response| Customer
    Customer -->|Delivers Result| EndUser

RiskOS™ exposes RESTful APIs for submitting evaluation requests and receiving structured JSON responses containing scores, decisions, and enrichment data.

Your application typically sends a POST request to the Evaluation API and receives a decision in milliseconds.

Some workflows include asynchronous steps—like Document Verification or One-Time Passcode validation. In these cases, you can update an evaluation with a PATCH request or wait for a webhook event when processing completes.

Integration flow overview

1. Build a workflow

Create and publish a workflow in the RiskOS™ Dashboard using the visual Workflow Builder. Define input steps, enrichment sources, and decision logic to determine how evaluations are processed in real time.

2. Send data for evaluation

Your application sends a POST request to the RiskOS™ Evaluation API with user or transaction data.
Include the workflow name and relevant parameters in your request body.

3. Receive a decision

RiskOS™ runs your configured workflow, applies risk models and enrichments, and returns a structured JSON response.

The response includes the decision outcome, risk scores, and enrichment details.

4. Handle async events

If a workflow includes asynchronous steps—such as One-Time Passcode or Predictive Document Verification — you’ll receive a webhook notification once processing completes.

You can also update evaluations manually using a PATCH request.

5. Act on outcomes

Use the decision and enrichment data to automate onboarding, trigger manual review, or apply your custom business logic.

Integrate these results directly into your operational systems or customer workflows.

Integration types

RiskOS™ provides flexible REST APIs for embedding risk and identity decisioning into your systems.

Best for: Instant onboarding or transaction approval flows

Returns immediate decisions (in milliseconds).
Perfect for real-time user experiences.
No waiting for external processes.
Direct API call → immediate response.

Each API response includes risk scores, reason codes, and enrichment data that can be logged, audited, or used to automate downstream workflows.

Webhooks for real-time updates

Event-driven

Get notified for completed evaluations, case updates, or watchlist changes.

Secure

Supports Basic, Bearer, and OAuth 2.0 authentication, with retry logic for reliability.

Configurable

Manage webhook endpoints and event subscriptions directly in the RiskOS™ Dashboard.

When a subscribed event occurs, RiskOS™ sends an HTTPS POST request to your configured endpoint — allowing your system to act immediately, such as approving a user, triggering Predictive Document Verificaiton, or routing a case to review.

Step-by-step integration guide

Before you start

Make sure you have the following:

RiskOS™ Dashboard access with appropriate user permissions.

Step 1 - Environment setup and authentication

Choose your environment

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

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

No real customer data
Free testing environment
Unlimited API calls

Get your API key

Sandbox API Key

Log into the Sandbox RiskOS™ Dashboard.
Go to Developer Workbench > API Keys.
Copy your API key securely.

Production API Keys

Log into the Production RiskOS™ Dashboard.
Navigate to Developer Workbench > API Keys.
Copy your API key securely.

(Optional) Configure IP allowlisting

📘
Note:
IP allowlisting is optional and limits which IPs can send requests. It’s separate from your API key, which authenticates who is calling the API. See the IP Filtering guide for more information.

For enhanced security, restrict API access to specific IP addresses:

Go to Developer Workbench > IP Filtering.
- 🔗 Sandbox IP Filtering
- 🔗 Production IP Filtering
Add your IP addresses or domains, separated by commas, into the Domain Name field.
Test access after configuration.

Step 2 - Build a workflow in the RiskOS™ Dashboard

What are workflows?

Workflows in RiskOS™ are are automated, customizable decision strategies that help organizations manage risk and detect fraud by guiding cases through a series of defined steps.

Workflows are built visually using the Workflow Builder in the RiskOS™ Dashboard, a no-code tool that lets users drag and drop steps, define rules, and orchestrate data services.

Once published, a workflow is triggered by an API call to the Evaluation endpoint, which executes each step in real time to reach a decision outcome.

Common workflow steps

Input Step

Collects applicant data.

Enrichment Step

Pulls in additional data from Socure products or third-party APIs.

Condition Step

Applies logic to determine workflow branching.

Decision Step

Finalizes the outcome (approve, decline, or route for manual review).

👍
Pre-built Solutions for common use cases:
Choose from our proven RiskOS™ workflow templates, or build a custom one. For more information, see the Integration Guides .

Step 3 - Call the Evaluation endpoint

Synchronous vs. asynchronous integrations

Make an API call to the Evaluation endpoint to initiate your workflow sequence. Depending on how you configured your workflow in Step 2, your integration will follow one of the examples below:

How it works

Start a new evaluation: Make a POST request to the Evaluation endpoint with the required data (such as consumer information for identity verification).
Receive the results immediately: The API processes the request and returns a response within milliseconds, containing the evaluation decision and any relevant data. Your application can then use this response to make real-time decisions (e.g., approve or deny a user registration).

Example synchronous integration workflow

Start a new evaluation

Use the /api/evaluation endpoint to submit applicant or transaction data for RiskOS™ to evaluate in real time. The workflow runs automatically based on the configured rules and steps.

Endpoint

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

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

Authentication and headers

To authenticate requests, include your API key in the Authorization header as a Bearer token. Also include standard JSON headers as shown below:

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": "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",
      "address": {
        "line_1": "742 Evergreen Terrace",
        "line_2": "Apt 12B",
        "locality": "Springfield",
        "major_admin_division": "IL",
        "country": "US",
        "postal_code": "62704"
      },
      "di_session_token": "eyJ0eXAiOiJKV1QiLCJhbGc..."
    }
  }
}

Request schema

Top-level fields

Field	Type	Required	Description	Example
`id`	String	Required	Unique identifier assigned by the customer to track the evaluation request.	`"onb-12345"`
`timestamp`	String	Required	ISO 8601 timestamp indicating when the evaluation request was initiated.	`"2023-12-01T08:15:30.456Z"`
`workflow`	String	Required	The name of the RiskOS™ workflow configured in the RiskOS™ Dashboard.	`"consumer_onboarding"`
`data`	Object	Required	Main payload containing individual and contextual information for evaluation.
→ `individual`	Object	Required	Primary applicant’s information, including name, identifiers, and contact data.

Receive a decision

The response includes a top-level decision and detailed module-level enrichments. Each enrichment contains request, response, and scoring details for transparency.

{
  "id": "onb-12345",
  "eval_id": "6dc8f39c-ecc3-4fe0-9283-fc8e5f99e816",
  "workflow": "consumer_onboarding",
  "eval_status": "evaluation_completed",
  "decision": "REJECT",
  "status": "CLOSED",
  "sub_status": "Reject",
  "workflow_id": "472288ff-b3a8-4e69-89dd-069d5e2bcb41",
  "workflow_version": "3.7.0",
  "tags": [],
  "review_queues": [],
  "data_enrichments": [
    {
      "enrichment_name": "Socure Address risk",
      "request": {},
      "response": {}
    }
  ],
  "computed": {}
}

{
  "id": "onb-12345",
  "eval_id": "6dc8f39c-ecc3-4fe0-9283-fc8e5f99e816",
  "workflow": "consumer_onboarding",
  "eval_status": "evaluation_completed",
  "decision": "REJECT",
  "status": "CLOSED",
  "sub_status": "Reject",
  "workflow_id": "472288ff-b3a8-4e69-89dd-069d5e2bcb41",
  "workflow_version": "3.7.0",
  "eval_source": "API",
  "eval_start_time": "2024-12-02T10:28:24.456771162Z",
  "eval_end_time": "2024-12-02T10:29:10.999Z",
  "tags": [
    "High Risk",
    "Bad Device"
  ],
  "score": 146,
  "review_queues": [
    "business_review"
  ],
  "data_enrichments": [
    {
      "enrichment_name": "Socure Address risk",
      "enrichment_endpoint": "https://sandbox.dev.socure.com/api/3.0/EmailAuthScore",
      "enrichment_provider": "Socure",
      "status_code": 200,
      "request": {
        "city": "bakersfield",
        "country": "US",
        "deviceSessionId": "234ac3ff-3ed1-42de-8f33-8f332febfa54",
        "dob": "1990-05-17",
        "email": "[email protected]",
        "modules": [
          "addressrisk"
        ],
        "nationalId": "454236793",
        "segmentation": {
          "channel": "mobile",
          "eventType": "accountOpen"
        }
      },
      "response": {
        "addressRisk": {
          "reasonCodes": [
            "I704",
            "I705",
            "I708"
          ],
          "score": 0.01,
          "scores": [
            {
              "name": "addressrisk_cus1",
              "score": 0.01,
              "version": "10.0"
            },
            {
              "name": "address_risk_pri",
              "score": 0.01,
              "version": "9.0"
            }
          ]
        },
        "referenceId": "4ca693ee-af2a-45ef-9688-834683ac1b34"
      },
      "is_source_cache": false,
      "total_attempts": 1
    },
    {
      "enrichment_name": "Socure Email Risk",
      "enrichment_endpoint": "https://sandbox.dev.socure.com/api/3.0/EmailAuthScore",
      "enrichment_provider": "Socure",
      "status_code": 200,
      "request": {
        "modules": [
          "emailrisk"
        ],
        "email": "[email protected]"
      },
      "response": {
        "emailRisk": {
          "reasonCodes": [
            "I520",
            "I555"
          ],
          "score": 0.01,
          "scores": [
            {
              "name": "email_risk_cus1",
              "score": 0.01,
              "version": "10.0"
            }
          ]
        },
        "referenceId": "92201637-1ec8-46b4-9537-236971eb6f9b"
      },
      "is_source_cache": false,
      "total_attempts": 1
    },
    {
      "enrichment_name": "Socure Phone Risk",
      "enrichment_endpoint": "https://sandbox.dev.socure.com/api/3.0/EmailAuthScore",
      "enrichment_provider": "Socure",
      "status_code": 200,
      "request": {
        "modules": [
          "phonerisk"
        ],
        "email": "[email protected]"
      },
      "response": {
        "phoneRisk": {
          "reasonCodes": [
            "I618",
            "I608"
          ],
          "score": 0.01,
          "scores": [
            {
              "name": "RiskPhoneUS.V6__Custom.Atlanticus.2324.Norm.V1",
              "score": 0.01,
              "version": "6.0"
            }
          ]
        },
        "referenceId": "68bb36f1-7e32-4600-bebf-26a6cdd39f8b"
      },
      "is_source_cache": false,
      "total_attempts": 1
    },
    {
      "enrichment_name": "SocureCNam",
      "enrichment_endpoint": "https://mfa-orchestrator-service-9.webapps.us-east-1.product-dev.socure.link/api/2.0/cnam",
      "enrichment_provider": "SocureCNam",
      "status_code": 200,
      "request": {
        "phoneNumber": "+1-312-555-1234"
      },
      "response": {
        "callerName": "Jane Smith",
        "callerType": "CONSUMER",
        "countryCode": "US",
        "phoneNumber": "+1-312-555-1234",
        "valid": true
      },
      "is_source_cache": false,
      "total_attempts": 1
    },
    {
      "enrichment_name": "Socure Digital Intelligence",
      "enrichment_endpoint": "https://sandbox.socure.com/api/3.0/EmailAuthScore",
      "enrichment_provider": "Socure",
      "status_code": 200,
      "request": {
        "modules": [
          "digitalintelligence"
        ],
        "deviceSessionId": "7b3c2c04-0e7e-46e4-afe8-b905cdf91833",
        "customerUserId": "129",
        "userId": "dwanyedever1975"
      },
      "response": {
        "referenceId": "7b3c2c04-0e7e-46e4-afe8-b905cdf91833",
        "digitalIntelligence": {
          "device": {
            "id": "234ac3ff-3ed1-42de-8f33-8f332febfa54",
            "globalDeviceId": "aecddd42-f223-3333-940c-87baab4c6645",
            "sessionCreatedAt": "2024-12-23T18:06:52.248985937Z",
            "deviceCapturedAt": "2024-12-23T18:09:12.735992851Z",
            "computed": {
              "statisticalId": "9349d69fef75cd356744293487462f8cd912",
              "isVirtualMachine": false,
              "isTamperedAndroidBuild": true,
              "sessionAgeMinutes": 45
            },
            "network": {
              "connectionIp": "38.48.122.126",
              "forwardedForIps": [
                "78.32.11.221",
                "70.45.2.1"
              ],
              "webRtcPublicIp": "176.124.54.12",
              "webRtcInternalIp": "192.168.1.85",
              "realIp": "38.48.122.126",
              "isTor": true,
              "isProxy": true,
              "isVpn": true,
              "isConsumerPrivacy": true,
              "isRiskyNetwork": true,
              "isp": "comcast",
              "ispType": "home",
              "asn": 27364,
              "asnName": "armstrong",
              "domainName": "zoominternet.net",
              "org": "comcast",
              "isMobileCarrier": true,
              "speed": "cable",
              "networkLocation": {
                "countryCode": "US",
                "region": "WA",
                "city": "Tacoma",
                "postalCode": "98401",
                "latitude": 47.2529001,
                "longitude": -122.4443,
                "metroCode": 819,
                "continentCode": "na",
                "timezoneName": "America/New_York",
                "gmtOffset": "-0400"
              }
            },
            "attributes": {
              "sdkVersion": "3.0.1",
              "platform": "iOS",
              "os": "iOS",
              "osVersion": 17,
              "deviceModel": "iphone14,7",
              "deviceManufacturer": "Apple",
              "deviceType": "tablet",
              "viewportWidth": 600,
              "viewportHeight": 400,
              "screenHeight": 1080,
              "screenWidth": 1920,
              "devicePixelRatio": 1.5,
              "network": {
                "vpnStatus": true
              },
              "location": {
                "latitude": 41.50854591662628,
                "longitude": -81.69534315646631,
                "horizontalAccuracy": 2.1,
                "altitude": 998.2,
                "verticalAccuracy": 0,
                "bearing": 32,
                "bearingAccuracy": 2.1,
                "speed": 1.3,
                "speedAccuracy": 0.2
              },
              "battery": {
                "batteryState": "charging",
                "batteryLevel": 0.47
              },
              "timeZone": "America/New_York",
              "timeZoneOffset": -480,
              "language": "en-US",
              "deviceArchitecture": "arm64",
              "applicationType": "native",
              "isEmulator": true,
              "deviceContext": "homepage",
              "androidAttributes": {
                "isRooted": true,
                "mobileNetwork": [
                  null
                ]
              },
              "iOSAttributes": {
                "isRooted": true,
                "mobileNetwork": [
                  null
                ]
              },
              "webAttributes": {
                "userAgent": "Mozilla/5.0 (iPhone; CPU iPhone OS 17_0 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Mobile/21A5291h [FBAN/FBIOS;FBDV/iPhone15,3;FBMD/iPhone;FBSN/iOS;FBSV/17.0;FBSS/3;FBID/phone;FBLC/fr_FR;FBOP/5]",
                "userAgentExtractionRequired": true,
                "browser": "Google Chrome",
                "browserVersion": 116
              }
            },
            "history": {
              "firstSeen": "2023-10-24T15:55:16.368Z",
              "lastSeen": "2023-10-24T15:55:16.368Z",
              "ips": [
                "78.32.11.221",
                "70.45.2.1"
              ],
              "isps": [
                "RogersCable",
                "T-Mobile"
              ],
              "daysSeen": [
                "2023-10-24"
              ],
              "networkLocations": [
                "chicago, il",
                "new york, ny",
                "paris, fr"
              ]
            }
          },
          "behavioral": {
            "sessionId": "d34304a6-a726-4dec-b1cd-9c4a3c192a0d",
            "serverCreated": "2021-09-01T11:19:58.796Z",
            "serverUpdated": "2021-09-11T16:19:58.796Z",
            "clientUpdated": "2021-09-11T16:14:58.796Z",
            "duration": 120910,
            "source": "https://example.com/",
            "aggregations": {
              "totalEventCount": 26,
              "focusCount": 0,
              "blurCount": 3,
              "inputChangeCount": 6,
              "submissionCount": 1,
              "clickCount": 3,
              "pasteCount": 0
            }
          },
          "entityProfiler": [
            {
              "entity": "12223334444",
              "entityType": "phone",
              "profile": {
                "seenCount": 2,
                "firstSeen": "2019-08-24T14:15:22Z",
                "lastSeen": "2019-08-24T14:15:22Z",
                "deviceTypes": [
                  "phone",
                  "tablet"
                ],
                "deviceModels": [
                  "iphone14,7",
                  "GT70053G"
                ],
                "deviceisps": [
                  "comcast",
                  "t-mobile"
                ],
                "deviceLanguages": [
                  "en-us",
                  "es-us"
                ],
                "deviceTimezones": [
                  "america/new_york",
                  "america/los_angeles"
                ],
                "networkLocationStates": [
                  "ca",
                  "az"
                ],
                "networkLocationPostalCodes": [
                  "12345",
                  "56789"
                ]
              }
            },
            {
              "entity": "[email protected]",
              "entityType": "email",
              "profile": {
                "seenCount": 5,
                "firstSeen": "2020-09-10T10:22:45Z",
                "lastSeen": "2020-09-15T13:45:32Z",
                "deviceTypes": [
                  "phone",
                  "desktop"
                ],
                "deviceModels": [
                  "moto g"
                ],
                "deviceisps": [
                  "at&t"
                ],
                "deviceLanguages": [
                  "en-us"
                ],
                "deviceTimezones": [
                  "america/los_angeles"
                ],
                "networkLocationStates": [
                  "or"
                ],
                "networkLocationPostalCodes": [
                  "56789"
                ]
              }
            },
            {
              "entity": "111223333",
              "entityType": "nationalId",
              "profile": {
                "seenCount": 3,
                "firstSeen": "2023-01-15T09:30:00Z",
                "lastSeen": "2023-09-10T14:45:00Z",
                "deviceTypes": [
                  "phone",
                  "tablet"
                ],
                "deviceModels": [
                  "GT70053G"
                ],
                "deviceisps": [
                  "comcast"
                ],
                "deviceLanguages": [
                  "de_us"
                ],
                "deviceTimezones": [
                  "america/chicago"
                ],
                "networkLocationStates": [
                  "il"
                ],
                "networkLocationPostalCodes": [
                  "12345"
                ]
              }
            }
          ],
          "velocityMetrics": {
            "historicalCount": {
              "firstName": {
                "uniqueCount": 1,
                "uniqueSharePercent": 100
              },
              "surName": {
                "uniqueCount": 1,
                "uniqueSharePercent": 100
              },
              "email": {
                "uniqueCount": 2,
                "uniqueSharePercent": 87
              },
              "mobileNumber": {
                "uniqueCount": 1,
                "uniqueSharePercent": 100
              }
            }
          }
        },
        "customerProfile": {
          "customerUserId": "129",
          "userId": "u8JpWn4QsF3R7tA2"
        }
      },
      "is_source_cache": false,
      "total_attempts": 1
    }
  ],
  "environment_name": "Sandbox"
}

Key fields

These fields contain the core information needed for your routing logic:

Category	Fields	Definition
Identifiers	`id`, `eval_id`	Unique identifiers for tracking evaluations.
Workflow Details	`workflow`, `workflow_id`, `workflow_version`	Workflow configuration and versioning details.
Evaluation Status	`eval_status`, `status`, `sub_status`	Current state and sub-state of the evaluation.
Decision Outcomes	`decision`, `decision_at`	Final outcome and timestamp of the evaluation.
Tags and Review Queues	`tags`, `review_queues`	Labels for categorization, filtering, and routing to manual review queues.
Dynamic Enrichment Data	`data_enrichments`, `computed`	Details of external data sources, enrichment steps, and derived computed results used in the evaluation.

Response schema

Top-level fields

Field	Type	Description	Example
`id`	String	Your original request `id`, echoed back in the response.	`"onb-12345"`
`eval_id`	String (UUID)	Internally generated for each evaluation run and required for `GET` and `PATCH` requests in RiskOS™.	`"6dc8f39c-ecc3-4fe0-9283-fc8e5f99e816"`
`workflow`	String	RiskOS™ workflow name that processed the evaluation, matching the request.	`"consumer_onboarding"`
`workflow_id`	String (UUID)	Internal workflow configuration identifier used by RiskOS™.	`"472288ff-b3a8-4e69-89dd-069d5e2bcb41"`
`workflow_version`	String	Version number of the workflow configuration used during evaluation.	`"3.7.0"`
`eval_source`	String	Source of the evaluation request indicating how it was submitted.	`"API"`
`eval_start_time`	String `<Date-Time>`	RFC 3339 timestamp when the evaluation processing began in RiskOS™.	`"2024-12-02T10:28:24.456771162Z"`
`eval_end_time`	String `<Date-Time>`	RFC 3339 timestamp when the evaluation processing completed in RiskOS™.	`"2024-12-02T10:29:10.999Z"`
`decision`	String	Final evaluation decision determined by workflow logic and rules. Possible values: `ACCEPT`, `REJECT`, `REVIEW`, `RESUBMIT`.	`"REJECT"`
`decision_at`	String `<Date-Time>`	RFC 3339 timestamp when the final decision was rendered by the system.	Not present in this response
`status`	String	Current lifecycle status of the evaluation case. Possible values: `CLOSED`, `OPEN`, `ON_HOLD`.	`"CLOSED"`
`sub_status`	String	Detailed sub-classification providing additional context for the main status.	`"Reject"`
`tags`	Array of Strings	List of descriptive tags explaining decision reasoning and risk factors identified.	`["High Risk","Bad Device"]`
`notes`	String	Freeform text field for additional comments or observations about the evaluation.	Not present in this response
`review_queues`	Array of Strings	Manual review queues where the case has been routed for human analysis.	`["business_review"]`
`score`	Number	Computed numerical risk score derived from all evaluation factors and signals.	`146`
`data_enrichments`	Array of Objects	Detailed log of all third-party API calls and data enrichment processes executed.	See data_enrichments fields below.
`eval_status`	String	Processing status indicating whether the evaluation completed successfully or encountered issues.	`"evaluation_completed"`
`environment_name`	String	Name of the RiskOS™ environment where the evaluation was processed. Possible values: `Sandbox`, `Production`.	`"Sandbox"`

`data_enrichments` fields

Field	Type	Description	Example
`enrichment_name`	String	Human-readable name identifying the specific enrichment service or module called.	`"Socure Address risk"`
`enrichment_endpoint`	String	Full URL endpoint that was called to retrieve the enrichment data.	`"https://sandbox.dev.socure.com/` `api/3.0/EmailAuthScore"`
`enrichment_provider`	String	Name of the vendor/service providing the enrichment data.	`"Socure"`
`status_code`	Integer	HTTP response status code returned by the enrichment service API call.	`200`
`request`	Object	Payload sent to the enrichment provider for processing.	See `request` fields below.
`response`	Object	Complete response data returned by the enrichment provider.	See `response` fields below.
`error`	String	Error description if the enrichment call failed or encountered issues.	(only present on errors)
`is_source_cache`	Boolean	Indicates whether the response data was retrieved from cache rather than a live API call.	`false`
`total_attempts`	Integer	Number of retry attempts made for this enrichment call before success or final failure.	`1`

Example `request` fields (varies by enrichment)

Field	Type	Required	Description	Example
`country`	String	Optional	ISO 3166-1 alpha-2 country code submitted to the enrichment service.	`"US"`
`city`	String	Optional	City submitted for geographic verification and risk assessment.	`"bakersfield"`
`dob`	String `YYYY-MM-DD`	Optional	Date of birth for age/identity verification.	`"1990-05-17"`
`email`	String	Optional	Email used for email risk assessment.	`"[email protected]"`
`nationalId`	String	Optional	Government identifier used for verification.	`"454236793"`
`deviceSessionId`	String (Token)	Optional	Digital Intelligence session token for device fingerprinting.	`"7b3c2c04-0e7e-46e4-afe8-b905cdf91833"`
`modules`	Array of Strings	Optional	RiskOS™ modules requested for evaluation.	`"addressrisk"`
`segmentation`	Object	Optional	Context such as channel and event type for routing.	`"channel":"mobile","eventType":"accountOpen"`

Example `response` fields (varies by enrichment)

Field	Type	Required	Description	Example
`fraud`	Object	Optional	Fraud risk scores and reason codes indicating potential fraudulent activity patterns.	See Sigma Identity Fraud.
`synthetic`	Object	Optional	Synthetic identity detection scores and indicators for artificially created identities.	See Sigma Synthetic Fraud.
`phoneRisk`	Object	Optional	Phone number risk assessment including validation, carrier info, and risk indicators.	See Phone Risk.
`emailRisk`	Object	Optional	Email address risk evaluation including domain analysis and reputation scoring.	See Email Risk.
`addressRisk`	Object	Optional	Address validation and risk assessment including deliverability and fraud indicators.	See Address Risk.
`graphIntelligence`	Object	Optional	Network analysis showing connections between identity elements across Socure's data graph.	See Graph Intelligence.
`referenceId`	String	Required	Unique identifier assigned to each enrichment after a RiskOS™ workflow is finalized.	`"4b905868-9d20-4d1c-9fde-544aeede981f"`

Step 4 - (Conditional) Manual Review

If a workflow cannot clearly approve or decline an event, it receives a Manual Review value in the decision field and can be routed to Case Management.

If decision = Manual Review → send to Case Management for reviewer decision.
Otherwise → continue automated flow (no manual action required).

Depending on your configuration, your workflow may route cases to manual review when any of the items below occur.

Trigger Type	Example Criteria or Scenario
Risk Score Threshold	Fraud, synthetic, or phone/email risk scores exceed 0.99
Multiple Risk Signals	Uncorrelated PII, incorrect SSN, or conflicting data
Watchlist Match	Applicant matches OFAC, PEP, or sanctions list
Document Verification Issue	Ambiguous or failed DocV results
Custom Rule	Any user-defined condition not met for automatic decision
Borderline / Complex Case	Case does not clearly fit approve/decline logic

Troubleshooting

If you encounter any errors during your integration, check the following:

Issue	Explanation	Suggested fix
Invalid or missing API credentials	The API or SDK keys being used may not correspond to the correct environment (Sandbox vs. Production), or the integration account may lack required permissions.	Verify that you’re using the proper API and SDK keys for the target environment. Confirm that your user or integration account has the correct permissions and entitlements.
Misconfigured or inactive workflow	The workflow may not be published, may contain errors, or the wrong Workflow ID may be referenced in API calls.	Ensure the workflow is saved without errors and set to LIVE status if required. Double-check that the correct Workflow ID is included in your API requests and configuration parameters.
Missing or malformed input data	Required PII fields or other mandatory parameters may be missing, incomplete, or incorrectly formatted.	Confirm that all required inputs (e.g., name, DOB, SSN, address) are included and formatted correctly. If certain fields are optional or conditional, coordinate with Socure to ensure proper model mapping.
Network restrictions or blocked requests	The integration’s IP address or network may not be permitted to reach the Socure API endpoints.	Verify that your IP address is whitelisted (if required). Check for firewall or network restrictions that might be blocking outbound API traffic.
Integration not validated before launch	The integration was not tested in a Sandbox environment, leading to unexpected results in Production.	Use the Sandbox environment and test data to validate integration flows before going live. Review Case Management or single case view responses to confirm expected data flow.
API errors or workflow failures	The system returns error messages indicating issues such as missing fields, invalid credentials, or misconfigured workflows.	Review error responses carefully—they often indicate exactly which field or credential is invalid.
Missing or failed webhook delivery	Webhook endpoints may be misconfigured, inaccessible, or unable to handle incoming event data.	Confirm that webhook endpoints are correctly configured and reachable . Test event delivery and review logs for delivery failures or endpoint errors.
Unresolved or recurring issues	Persistent problems remain even after basic troubleshooting steps.	Contact Socure Support with detailed error messages, logs, and context. Include your Solution Consultant team for additional assistance.

Integrating with RiskOS™

What you can do with RiskOS™

How it works

Integration flow overview

Integration types

Webhooks for real-time updates

Step-by-step integration guide

Before you start

Step 1 - Environment setup and authentication

Choose your environment

Get your API key

(Optional) Configure IP allowlisting

Step 2 - Build a workflow in the RiskOS™ Dashboard

What are workflows?

Common workflow steps

Step 3 - Call the Evaluation endpoint

Synchronous vs. asynchronous integrations

How it works

Example synchronous integration workflow

Start a new evaluation

Endpoint

Authentication and headers

Example request

Request schema

Top-level fields

Receive a decision

Key fields

Response schema

Top-level fields

`data_enrichments` fields

Example `request` fields (varies by enrichment)

Example `response` fields (varies by enrichment)

Step 4 - (Conditional) Manual Review

Troubleshooting

Validation checklist

Request setup

Workflow behavior

Response handling

Error & retry handling

Validation

What you can do with RiskOS™

How it works

Integration flow overview

Integration types

Webhooks for real-time updates

Step-by-step integration guide

Before you start

Step 1 - Environment setup and authentication

Choose your environment

Get your API key

(Optional) Configure IP allowlisting

Step 2 - Build a workflow in the RiskOS™ Dashboard

What are workflows?

Common workflow steps

Step 3 - Call the Evaluation endpoint

Synchronous vs. asynchronous integrations

How it works

Example synchronous integration workflow

Start a new evaluation

Endpoint

Authentication and headers

Example request

Request schema

Top-level fields

Receive a decision

Key fields

Response schema

Top-level fields

data_enrichments fields

Example request fields (varies by enrichment)

Example response fields (varies by enrichment)

Step 4 - (Conditional) Manual Review

Troubleshooting

Validation checklist

Request setup

Workflow behavior

Response handling

Error & retry handling

Validation

`data_enrichments` fields

Example `request` fields (varies by enrichment)

Example `response` fields (varies by enrichment)