Integration Guide
Use the RiskOS™ Evaluation API to verify consumer identity, detect fraud, and perform compliance screening.
Overview
This guide shows you how to:
- Send a
POST /api/evaluationrequest using the Consumer Onboarding workflow. - Include identity and device data, including
di_session_token. - Interpret the response and decision (
ACCEPT,REVIEW,REJECT). - Trigger Document Verification (DocV) when additional verification is required.
- Handle asynchronous final decisions when DocV is enabled.
Before you start
Make sure you have:
A workflow configured for the Consumer Onboarding solution.
Integration with the Digital Intelligence SDK to collect the required di_session_token.
Integration with the Predictive DocV SDK or Hosted Flow to collect consumer identity documents when a step-up is required.
An optional webhook endpoint to receive asynchronous status updates from RiskOS™.
Postman Collection
The following Postman collection can be used to test the Consumer Onboarding solution with the Evaluation endpoint.
Quickstart
Endpoint
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
Authentication
- In the Sandbox RiskOS™ Dashboard, go to Developer Workbench > API Keys.
- Copy your API key securely.
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 versionMinimum example request
{
"id": "a86580cc-1733-4188-86b5-717166e1db8c",
"timestamp": "2026-04-02T12:00:00Z",
"workflow": "consumer_onboarding",
"data": {
"individual": {
"given_name": "Jane",
"family_name": "Smith",
"address": {
"country": "US"
},
"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": "consumer_onboarding",
"data": {
"individual": {
"given_name": "Jane",
"family_name": "Smith",
"address": {
"country": "US"
},
"di_session_token": "YOUR_DI_SESSION_TOKEN"
}
}
}'Decision handling
| Decision | Action |
|---|---|
ACCEPT | Continue onboarding |
REJECT | Stop or route to fallback |
REVIEW | Trigger Document Verification (DocV) or manual review, depending on workflow configuration |
What matters for your integration
| Category | Fields | How to use |
|---|---|---|
| Required to send | id, timestamp, workflow, data | Minimum fields required to submit a valid request |
| Required to act on | decision | Primary field used to determine application behavior |
| Required to store | id, eval_id | Persist for traceability, debugging, webhooks, and support |
| Optional but useful | tags, review_queues, notes, score | Use for routing, review flows, analytics, and internal context |
| Diagnostic only | data_enrichments, status, sub_status | Use for debugging and analysis only — not for primary decisions |
Integration contract
endpoint: POST /api/evaluation
workflow: consumer_onboarding
authentication:
type: Bearer token
header: Authorization
content_type: application/json
required_top_level_fields:
- id
- timestamp
- workflow
- data
required_identity_fields:
- given_name
- family_name
- address.country
required_device_field:
- di_session_token
primary_decision_field: decision
important_response_fields:
- decision
- eval_id
- tags
- review_queues
traceability_fields:
- id
- eval_id
do_not_use_for_primary_decision:
- status
- sub_statusHow the workflow evaluates a user
After you submit an evaluation request, RiskOS™ evaluates the applicant across identity, device, fraud, and compliance checks. Depending on the risk signals returned by your configured workflow, the evaluation can be accepted, rejected, routed to review, or stepped up to Document Verification (DocV).
Typical stages include:
-
Device and session risk Review Digital Intelligence signals such as device, network, and behavioral risk.
-
Identity verification Validate consumer identity attributes using identity verification products such as Verify Plus.
-
Fraud screening Evaluate synthetic identity, fraud, email, phone, address, and graph-based risk signals.
-
Step-up verification If risk is elevated but not conclusive, trigger DocV or another review step.
-
Compliance and final routing Apply watchlist screening, first-party fraud checks, tags, queues, and final decision logic.
sequenceDiagram
participant CP as Platform
participant SC as Socure
CP->>SC: POST /evaluation (consumer_onboarding)
SC->>SC: Run device, identity, fraud, compliance checks
alt ACCEPT
SC-->>CP: decision = ACCEPT
else REJECT
SC-->>CP: decision = REJECT
else REVIEW
SC-->>CP: decision = REVIEW
else Step-up required
SC->>SC: DocV / manual review
SC-->>CP: decision = ACCEPT / REVIEW / REJECT
end
Request schema
The example below shows a common Consumer Onboarding request with identity, address, device, and optional DocV configuration data.
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",
"middle_name": "",
"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,
"use_case_key": "",
"language": ""
}
}
},
"ip_address": "203.0.113.10"
}
}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": "a86580cc-1733-4188-86b5-717166e1db8c",
"timestamp": "2025-05-02T12:44:22.059Z",
"workflow": "consumer_onboarding",
"data": {
"individual": {
"id": "username",
"given_name": "Franky",
"middle_name": "",
"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,
"use_case_key": "",
"language": ""
}
}
},
"ip_address": "203.0.113.10"
}
}'Request structure overview
id
timestamp
workflow
data
├─ individual
│ ├─ id
│ ├─ given_name
│ ├─ family_name
│ ├─ national_id
│ ├─ date_of_birth
│ ├─ email
│ ├─ phone_number
│ ├─ address
│ ├─ additional_context
│ ├─ di_session_token
│ └─ docv
├─ ip_addressCommon identity and device fields
The table below lists the typical set of PII inputs collected for the Consumer Onboarding solution.
These fields are not all required—different elements can be selectively included depending on the product modules used within your workflow.
You’ll find additional details below on input field formatting and structure within the API request.
| Field | Type | Description | Example |
|---|---|---|---|
given_name | String | First name of the consumer. | "Franky" |
family_name | String | Last name of the consumer. | "Valley" |
phone_number | String | Consumer's phone number in E.164 format. The API expects the standard E.164 format but tolerates hyphens and spaces for user convenience. | "+1-667-368-1976" |
date_of_birth | String | Consumer's date of birth in ISO 8601 format (YYYY-MM-DD). | "1992-03-11" |
national_id | String | National identifier such as SSN, SIN, or equivalent, depending on geography. | "555667772" |
email | String | Consumer's email address. | "[email protected]" |
address | Object | Consumer's residential or mailing address, typically including street, city, region, postal code, and country. | "742 Evergreen Terrace, Apt 2B, Springfield, IL 62704, US" |
di_session_token | String | Token from the Digital Intelligence SDK that links the device session. | "eyJraWQiOi_di_token" |
Field reference
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. Note: The workflow name must be unique within your RiskOS™ environment. It is not scoped by use case and must identify a single active workflow for each Evaluation API request. | "consumer_onboarding" |
data | Object | Required | Main payload containing consumer information, device data, and event details for evaluation. | |
→ individual | Object | Required | Primary identity object containing individual's information. | See individual schema below. |
→ip_address | String | Optional | Consumer's IP address in IPv4 decimal or IPv6 hexadecimal format. Used for geolocation and risk analysis. | "203.0.113.10" |
individual fields
individual fields| Field | Type | Required | Description | Example |
|---|---|---|---|---|
id | String | Optional | Maps to the userId in enrichments or a customer’s internal identifier. Can be enabled as a searchable field in RiskOS™ Dashboard. | "username" |
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" |
email | String | Required | Consumer's email address (must be a valid email format) | "[email protected]" |
phone_number | String | Required | Consumer's phone number. The API expects E.164 format but tolerates hyphens and spaces for user convenience. | "+1-667-368-1976" |
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" |
address | Object | Optional | Consumer's mailing address used for identity verification and geographic risk assessment. | See address schema below. |
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" |
additional_context | Object | Required | Disclosure or consent metadata for products such as Sigma First-Party Fraud. | See additional_context schema below. |
docv | Object | Required (if using Predictive DocV) | Configuration object for Document Verification. Defines message delivery, language, and use-case options. | See docv schema below. |
address fields
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 for international address standardization. | "US" |
postal_code | String | Optional | The consumer's ZIP code, postal code, or equivalent regional identifier for mail delivery. | "62704" |
additional_context fields
additional_context fields| Field | Type | Required | Description | Example |
|---|---|---|---|---|
disclosure_purpose | String | Required | Disclosure for running Sigma First-Party Fraud product. | "GLBA_502(e)" |
docv fields (only required when using Predictive DocV in your workflow)
docv fields (only required when using Predictive DocV in your workflow)| Field | Type | Required | Description | Example |
|---|---|---|---|---|
transaction_token | String | Conditional | The transaction token from the Document Request API response (v5). Use this if integrated with Socure's DocV solution. | "1e89eec0-f7a3-4210-b74b-a76bc9556c50" |
config | Object | Optional | Configuration options controlling Capture App behavior and document verification flow for a given transaction. | See config schema below. |
→ send_message | Boolean | Optional | Set to true to send an SMS to the provided phone number with the document request URL. Defaults to false. - US & Canada: sent from short code 33436 - Other countries: sent from +1 (510) 330-19xx | true |
→ language | String | Optional | Determines Capture App UI language. Defaults to en-us. | "en-us" |
→ use_case_key | String | Optional | Deploys a specific Capture App flow created in RiskOS™. Defaults to the account’s default flow or the flow configured in the RiskOS™ workflow. | "default_capture_flow" |
→ redirect | Object | Optional | Object containing post-capture redirect behavior. | See redirect schema below. |
→ redirect.method | String | Conditional | Required if redirect is provided. Accepts GET or POST. | "POST" |
→ redirect.url | String | Conditional | Required if redirect is provided. The destination URL to send the consumer after capture. Can include query strings for transaction tracking. | "https://example.com/docv" |
→ document_type | String | Optional | Restrict to a single document type (license or passport) for a simplified flow. Users skip the document type selection screen when passed. | "license" |
→ transaction_token | String | Optional | Used primarily in Sandbox testing to indicate the expected decision outcome. Required when simulating test results. | "sandbox-simulated-pass" |
external_device fields - Optional
external_device fields - OptionalUse these fields when integrating device data from third-party providers (if not using Socure Digital Intelligence).
| Field | Type | Description | Example |
|---|---|---|---|
id | String | Unique customer-side identifier for the device across sessions. | "device-abc123" |
session | String | Unique identifier for the current device session. | "session-xyz789" |
fingerprint | String | Device fingerprint from your third-party provider. | "fp-unique-identifier" |
fingerprint_provider | String | Name of the fingerprint provider generating the device data. | "FingerprintJS" |
user_agent | String | Complete user agent string from the device browser or app. | "Mozilla/5.0 (iPhone; CPU iPhone OS..." |
device_type | String | Type of device being used for the session. One of mobile, desktop, or tablet. | "mobile" |
is_known | Boolean | Indicates whether this device has been seen before by your system. | true |
first_seen_time | String <Date-Time> | RFC 3339 timestamp when this device was first encountered. | "2023-10-01T10:00:00.000Z" |
last_seen_time | String <Date-Time> | RFC 3339 timestamp when this device was most recently seen. | "2023-12-01T15:30:00.000Z" |
timezone_mismatch | Boolean | Indicates whether the device timezone differs from the expected location. | false |
ip_address | String | Current IP address of the device. | "203.0.113.10" |
is_ip_bad_proxy | Boolean | Indicates whether the IP is associated with known malicious proxy services. | false |
is_ip_proxy | Boolean | Indicates whether the IP address is identified as any type of proxy. | true |
ip_risk_score | Number <Float> | Risk score (0–100) associated with the device’s IP address. | 25.7 |
ip_isp | String | Internet service provider name for the device’s IP. | "Comcast Cable" |
ip_country_code | String | ISO 3166-1 alpha-2 country code for the IP address location. | "US" |
ip_city | String | City name associated with the IP address geolocation. | "Chicago" |
ip_region | String | State or region name for the IP address location. | "Illinois" |
is_ip_tor | Boolean | Indicates whether the IP address is associated with Tor network traffic. | false |
is_emulator | Boolean | Indicates whether the device is identified as an emulator or virtual device. | false |
Interpret the response
When you call the Evaluation API, RiskOS™ returns a JSON payload that includes the final decision, evaluation metadata, and enrichment-specific results produced by your Consumer Onboarding workflow.
Example response
{
"id": "895dc35b-cee7-4f14-af06-6e26482178f8",
"workflow": "consumer_onboarding",
"workflow_id": "8b93f74b-7273-410c-a16e-b2ad14613f11",
"workflow_version": "2.6.0",
"eval_source": "API",
"eval_id": "b1c0e610-822d-4793-a970-8bfc0a9b883f",
"eval_start_time": "2025-12-11T17:49:28.529047165Z",
"eval_end_time": "2025-12-11T17:49:28.931231288Z",
"decision": "ACCEPT",
"decision_at": "2025-12-11T17:49:28.930983809Z",
"status": "CLOSED",
"sub_status": "Accept",
"tags": [],
"notes": "",
"review_queues": [],
"data_enrichments": [
{
"enrichment_name": "Socure Digital Intelligence",
"enrichment_endpoint": "https://sandbox.socure.com/api/3.0/EmailAuthScore",
"enrichment_provider": "Socure",
"status_code": 200,
"request": {
"city": "Springfield",
"country": "US",
"deviceSessionId": "eyJraWQiOi_di_token",
"dob": "1992-03-11",
"email": "[email protected]",
"firstName": "Franky",
"mobileNumber": "16673681976",
"modules": [
"digitalintelligence"
],
"nationalId": "435960859",
"parentTxnId": "b1c0e610-822d-4793-a970-8bfc0a9b883f",
"physicalAddress": "742 Evergreen Terrace",
"physicalAddress2": "Apt 2B",
"riskOSId": "895dc35b-cee7-4f14-af06-6e26482178f8",
"state": "IL",
"surName": "Valley",
"userId": "username",
"workflow": "consumer_onboarding",
"zip": "62704"
},
"response": {
"customerProfile": {
"userId": "username"
},
"digitalIntelligence": {
"behavioral": {
"aggregations": {
"blurCount": 3,
"clickCount": 3,
"focusCount": 0,
"inputChangeCount": 6,
"pasteCount": 0,
"submissionCount": 1,
"totalEventCount": 26
},
"duration": 120910,
"serverCreated": "2021-09-01T11:19:58.796Z",
"serverUpdated": "2021-09-11T16:19:58.796Z",
"sessionId": "d34304a6-a726-4dec-b1cd-9c4a3c192a0d",
"source": "https://example.com/"
},
"device": {
"attributes": {
"androidAttributes": {
"isRooted": false,
"mobileNetwork": [
{
"carrierName": "T-Mobile",
"isoCountryCode": "us"
}
]
},
"battery": {
"batteryLevel": 0.47,
"batteryState": "charging"
},
"deviceContext": "homepage",
"deviceManufacturer": "Apple",
"deviceModel": "iphone14,7",
"devicePixelRatio": 1.5,
"deviceType": "tablet",
"iOSAttributes": {
"isRooted": false,
"mobileNetwork": [
{
"carrierName": "T-Mobile",
"isoCountryCode": "us"
}
]
},
"isEmulator": false,
"language": "en-US",
"location": {
"altitude": 998.2,
"bearing": 32,
"bearingAccuracy": 2.1,
"horizontalAccuracy": 2.1,
"latitude": 41.50854591662628,
"longitude": -81.69534315646631,
"speed": 1.3,
"speedAccuracy": 0.2,
"verticalAccuracy": 0
},
"network": {
"vpnStatus": true
},
"os": "iOS",
"osVersion": "17",
"platform": "iOS",
"screenHeight": 1080,
"screenWidth": 1920,
"sdkVersion": "3.0.1",
"timeZone": "America/New_York",
"timeZoneOffset": -480,
"viewportHeight": 400,
"viewportWidth": 600,
"webAttributes": {
"browser": "Google Chrome",
"browserVersion": "116",
"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
}
},
"computed": {
"isVirtualMachine": false,
"statisticalId": "9349d69fef75cd356744293487462f8cd912"
},
"deviceCaptureAt": "2023-10-24T15:55:17.368756891Z",
"history": {
"daysSeen": [
"2023-10-24"
],
"firstSeen": "2023-10-24T15:55:16.368Z",
"ips": [
"78.32.11.221",
"70.45.2.1"
],
"isps": [
"RogersCable",
"T-Mobile"
],
"lastSeen": "2023-10-24T15:55:16.368Z",
"networkLocations": [
"chicago, il",
"new york, ny",
"paris, fr"
]
},
"id": "234ac3ff-3ed1-42de-8f33-8f332febfa54",
"network": {
"asn": 27364,
"asnName": "armstrong",
"connectionIp": "38.48.122.126",
"domainName": "zoominternet.net",
"forwardedForIps": [
"78.32.11.221",
"70.45.2.1"
],
"isConsumerPrivacy": false,
"isMobileCarrier": true,
"isProxy": false,
"isRiskyNetwork": false,
"isTor": false,
"isVpn": false,
"isp": "comcast",
"ispType": "home",
"networkLocation": {
"city": "Tacoma",
"continentCode": "na",
"countryCode": "US",
"gmtOffset": "-0400",
"latitude": 47.2529001,
"longitude": -122.4443,
"metroCode": 819,
"postalCode": "98401",
"region": "WA",
"timezoneName": "America/New_York"
},
"org": "comcast",
"realIp": "38.48.122.126",
"speed": "cable",
"webRtcInternalIp": "192.168.1.85",
"webRtcPublicIp": "176.124.54.12"
},
"sessionCreatedAt": "2023-10-24T15:55:16.368492137Z"
},
"velocityMetrics": {
"historicalCount": {
"email": {
"uniqueCount": 3,
"uniqueSharePercent": 50
},
"firstName": {
"uniqueCount": 3,
"uniqueSharePercent": 50
},
"lastName": {
"uniqueCount": 3,
"uniqueSharePercent": 50
},
"mobileNumber": {
"uniqueCount": 3,
"uniqueSharePercent": 50
}
}
}
},
"referenceId": "ec2fb84f-81b5-4421-a4a6-ac070b874f46"
},
"is_source_cache": false,
"total_attempts": 1
},
{
"enrichment_name": "Socure Phone Risk",
"enrichment_endpoint": "https://sandbox.socure.com/api/3.0/EmailAuthScore",
"enrichment_provider": "Socure",
"status_code": 200,
"request": {
"city": "Springfield",
"country": "US",
"dob": "1992-03-11",
"email": "[email protected]",
"firstName": "Franky",
"mobileNumber": "16673681976",
"modules": [
"phonerisk"
],
"nationalId": "435960859",
"parentTxnId": "b1c0e610-822d-4793-a970-8bfc0a9b883f",
"physicalAddress": "742 Evergreen Terrace",
"physicalAddress2": "Apt 2B",
"riskOSId": "895dc35b-cee7-4f14-af06-6e26482178f8",
"state": "IL",
"surName": "Valley",
"userId": "username",
"workflow": "consumer_onboarding",
"zip": "62704"
},
"response": {
"customerProfile": {
"userId": "username"
},
"namePhoneCorrelation": {
"reasonCodes": [
"I622",
"I621",
"I618"
],
"score": 0.99
},
"phoneRisk": {
"reasonCodes": [
"I609",
"I618",
"I608"
],
"scores": [
{
"name": "RiskPhoneUS.V7__Uniform.V1",
"score": 0.01,
"version": "4.0"
}
]
},
"referenceId": "fd9e43dc-8a7b-4819-9f0f-eb79401dc795"
},
"is_source_cache": false,
"total_attempts": 1
},
{
"enrichment_name": "Socure OTP - static accept",
"enrichment_endpoint": "https://mockserver.com/api/3.0/EmailAuthScore",
"enrichment_provider": "RestAPI",
"status_code": 200,
"response": {
"attemptCount": 1,
"error": "",
"status": "accept",
"verificationId": "10901fa6-bf0a-441a-8190-7cd109dbab65"
},
"is_source_cache": false,
"total_attempts": 1
},
{
"enrichment_name": "Socure Verify Plus",
"enrichment_endpoint": "https://sandbox.socure.com/api/3.0/EmailAuthScore",
"enrichment_provider": "Socure",
"status_code": 200,
"request": {
"city": "Springfield",
"country": "US",
"dob": "1992-03-11",
"email": "[email protected]",
"firstName": "Franky",
"mobileNumber": "16673681976",
"modules": [
"kycplus"
],
"nationalId": "435960859",
"parentTxnId": "b1c0e610-822d-4793-a970-8bfc0a9b883f",
"physicalAddress": "742 Evergreen Terrace",
"physicalAddress2": "Apt 2B",
"riskOSId": "895dc35b-cee7-4f14-af06-6e26482178f8",
"state": "IL",
"surName": "Valley",
"userId": "username",
"workflow": "consumer_onboarding",
"zip": "62704"
},
"response": {
"customerProfile": {
"userId": "username"
},
"kycPlus": {
"bestMatchedEntity": {
"associatedAddresses": [],
"associatedEmails": [],
"associatedPhoneNumbers": [],
"dob": "",
"emailAddress": "",
"firstName": "",
"middleName": "",
"mobileNumber": "",
"normalizedAddress": {
"city": "Springfield",
"state": "IL",
"streetAddress": "742 Evergreen Terrace",
"zip": "62704"
},
"ssn": "",
"ssnIssued": "",
"suffix": "",
"surName": ""
},
"fieldValidations": {
"city": 0.99,
"dob": 0.99,
"email": 0.99,
"firstName": 0.99,
"mobileNumber": 0.99,
"ssn": 0.99,
"state": 0.99,
"streetAddress": 0.99,
"surName": 0.99,
"zip": 0.99
},
"reasonCodes": [
"I919"
],
"socureId": "0318d3c3-541c-4090-8250-dec3e41efa89",
"sourceAttribution": [
"Alternative Credit",
"County Tax"
]
},
"referenceId": "aa96eebe-7ae8-446f-837d-df36e704aa9c"
},
"is_source_cache": false,
"total_attempts": 1
},
{
"enrichment_name": "Socure Sigma Synthetic",
"enrichment_endpoint": "https://sandbox.socure.com/api/3.0/EmailAuthScore",
"enrichment_provider": "Socure",
"status_code": 200,
"request": {
"city": "Springfield",
"country": "US",
"dob": "1992-03-11",
"email": "[email protected]",
"firstName": "Franky",
"mobileNumber": "16673681976",
"modules": [
"synthetic"
],
"nationalId": "435960859",
"parentTxnId": "b1c0e610-822d-4793-a970-8bfc0a9b883f",
"physicalAddress": "742 Evergreen Terrace",
"physicalAddress2": "Apt 2B",
"riskOSId": "895dc35b-cee7-4f14-af06-6e26482178f8",
"state": "IL",
"surName": "Valley",
"userId": "username",
"workflow": "consumer_onboarding",
"zip": "62704"
},
"response": {
"customerProfile": {
"userId": "username"
},
"referenceId": "4615f59b-51c6-45de-84e5-47bfa2d5c546",
"synthetic": {
"reasonCodes": [
"I204",
"R223",
"I206"
],
"scores": [
{
"name": "synthetic",
"score": 0.127,
"version": "4.1"
}
]
}
},
"is_source_cache": false,
"total_attempts": 1
},
{
"enrichment_name": "Socure Email Risk",
"enrichment_endpoint": "https://sandbox.socure.com/api/3.0/EmailAuthScore",
"enrichment_provider": "Socure",
"status_code": 200,
"request": {
"city": "Springfield",
"country": "US",
"dob": "1992-03-11",
"email": "[email protected]",
"firstName": "Franky",
"mobileNumber": "16673681976",
"modules": [
"emailrisk"
],
"nationalId": "435960859",
"parentTxnId": "b1c0e610-822d-4793-a970-8bfc0a9b883f",
"physicalAddress": "742 Evergreen Terrace",
"physicalAddress2": "Apt 2B",
"riskOSId": "895dc35b-cee7-4f14-af06-6e26482178f8",
"state": "IL",
"surName": "Valley",
"userId": "username",
"workflow": "consumer_onboarding",
"zip": "62704"
},
"response": {
"customerProfile": {
"userId": "username"
},
"emailRisk": {
"reasonCodes": [
"I553",
"I555",
"I556"
],
"scores": [
{
"name": "RiskEmailUS.V11__Uniform.V1",
"score": 0.01,
"version": "4.0"
}
]
},
"nameEmailCorrelation": {
"reasonCodes": [
"I557",
"I556",
"I558"
],
"score": 0.99
},
"referenceId": "02ed96ca-8fb3-4101-9b52-2590eeb676c9"
},
"is_source_cache": false,
"total_attempts": 1
},
{
"enrichment_name": "Socure Address Risk",
"enrichment_endpoint": "https://sandbox.socure.com/api/3.0/EmailAuthScore",
"enrichment_provider": "Socure",
"status_code": 200,
"request": {
"city": "Springfield",
"country": "US",
"dob": "1992-03-11",
"email": "[email protected]",
"firstName": "Franky",
"mobileNumber": "16673681976",
"modules": [
"addressrisk"
],
"nationalId": "435960859",
"parentTxnId": "b1c0e610-822d-4793-a970-8bfc0a9b883f",
"physicalAddress": "742 Evergreen Terrace",
"physicalAddress2": "Apt 2B",
"riskOSId": "895dc35b-cee7-4f14-af06-6e26482178f8",
"state": "IL",
"surName": "Valley",
"userId": "username",
"workflow": "consumer_onboarding",
"zip": "62704"
},
"response": {
"addressRisk": {
"reasonCodes": [
"I720",
"I705",
"I708"
],
"scores": [
{
"name": "RiskAddressNOIPUS.V8__Uniform.V1",
"score": 0.01,
"version": "4.0"
}
]
},
"customerProfile": {
"userId": "username"
},
"nameAddressCorrelation": {
"reasonCodes": [
"I709",
"I708",
"I710"
],
"score": 0.99
},
"referenceId": "2032ad44-b0ae-4bde-a9dd-51285b27ed92"
},
"is_source_cache": false,
"total_attempts": 1
},
{
"enrichment_name": "Socure GraphIntelligence + Sigma Fraud",
"enrichment_endpoint": "https://sandbox.socure.com/api/3.0/EmailAuthScore",
"enrichment_provider": "Socure",
"status_code": 200,
"request": {
"city": "Springfield",
"country": "US",
"dob": "1992-03-11",
"email": "[email protected]",
"firstName": "Franky",
"mobileNumber": "16673681976",
"modules": [
"graphintelligence",
"fraud"
],
"nationalId": "435960859",
"parentTxnId": "b1c0e610-822d-4793-a970-8bfc0a9b883f",
"physicalAddress": "742 Evergreen Terrace",
"physicalAddress2": "Apt 2B",
"riskOSId": "895dc35b-cee7-4f14-af06-6e26482178f8",
"state": "IL",
"surName": "Valley",
"userId": "username",
"workflow": "consumer_onboarding",
"zip": "62704"
},
"response": {
"customerProfile": {
"userId": "username"
},
"fraud": {
"reasonCodes": [
"I641",
"I555",
"I576",
"I602"
],
"scores": [
{
"name": "sigma",
"score": 0.11,
"version": "4.0"
}
]
},
"graphIntelligence": {
// Socure returns additional raw address signals not shown here for brevity and sensitivity.
},
"referenceId": "d4c0e92f-cc57-449e-adad-4e0b67b782a8"
},
"is_source_cache": false,
"total_attempts": 1
},
{
"enrichment_name": "Socure First Party Fraud",
"enrichment_endpoint": "https://sandbox.socure.com/api/3.0/EmailAuthScore",
"enrichment_provider": "Socure",
"status_code": 200,
"request": {
"city": "Springfield",
"country": "US",
"disclosurePurpose": "GLBA_502(e)",
"dob": "1992-03-11",
"email": "[email protected]",
"firstName": "Franky",
"mobileNumber": "16673681976",
"modules": [
"firstpartyfraud"
],
"nationalId": "435960859",
"parentTxnId": "b1c0e610-822d-4793-a970-8bfc0a9b883f",
"physicalAddress": "742 Evergreen Terrace",
"physicalAddress2": "Apt 2B",
"riskOSId": "895dc35b-cee7-4f14-af06-6e26482178f8",
"state": "IL",
"surName": "Valley",
"userId": "username",
"workflow": "consumer_onboarding",
"zip": "62704"
},
"response": {
"customerProfile": {
"userId": "username"
},
"firstPartyFraud": {
"reasonCodes": [],
"scores": [
{
"name": "Identity Manipulation",
"score": 0.14,
"version": "1.0"
}
],
"signals": {
// Socure returns additional raw address signals not shown here for brevity and sensitivity.
}
},
"referenceId": "2a4c212c-3169-4f97-b0de-08526e5dffca"
},
"is_source_cache": false,
"total_attempts": 1
},
{
"enrichment_name": "Socure Global Watchlist Plus",
"enrichment_endpoint": "https://sandbox.socure.com/api/3.0/EmailAuthScore",
"enrichment_provider": "Socure",
"status_code": 200,
"request": {
"city": "Springfield",
"country": "US",
"dob": "1992-03-11",
"email": "[email protected]",
"firstName": "Franky",
"mobileNumber": "16673681976",
"modules": [
"watchlistplus"
],
"nationalId": "435960859",
"parentTxnId": "b1c0e610-822d-4793-a970-8bfc0a9b883f",
"physicalAddress": "742 Evergreen Terrace",
"physicalAddress2": "Apt 2B",
"riskOSId": "895dc35b-cee7-4f14-af06-6e26482178f8",
"state": "IL",
"surName": "Valley",
"userId": "username",
"workflow": "consumer_onboarding",
"zip": "62704"
},
"response": {
"customerProfile": {
"userId": "username"
},
"globalWatchlist": {
"matches": {},
"reasonCodes": [
"I196"
]
},
"referenceId": "1ac4f38a-60cd-4cbe-8b66-111ba43f4d47"
},
"is_source_cache": false,
"total_attempts": 1
}
],
"eval_status": "evaluation_completed",
"score": 11,
"environment_name": "Sandbox"
}
{
"id": "4c5510af-a397-4430-b628-c952977b6c1f",
"workflow": "consumer_onboarding",
"workflow_id": "8b93f74b-7273-410c-a16e-b2ad14613f11",
"workflow_version": "2.6.0",
"eval_source": "API",
"eval_id": "35bccdd5-e285-4988-b4e2-f9b55602b4a3",
"eval_start_time": "2025-12-12T14:42:12.738920438Z",
"eval_end_time": "2025-12-12T14:42:13.494653846Z",
"decision": "REVIEW",
"decision_at": "2025-12-12T14:42:13.494374036Z",
"status": "OPEN",
"sub_status": "In Review",
"tags": [
"Watchlist Review"
],
"notes": "",
"review_queues": [
"Compliance"
],
"data_enrichments": [
{
"enrichment_name": "Socure Digital Intelligence",
"enrichment_endpoint": "https://sandbox.socure.com/api/3.0/EmailAuthScore",
"enrichment_provider": "Socure",
"status_code": 200,
"request": {
"city": "FPO",
"country": "US",
"deviceSessionId": "eyJraWQiOiJmMzRiN2YiLCJh_DI_LOW_SCORE",
"dob": "1999-02-06",
"email": "[email protected]",
"firstName": "Carl",
"ipAddress": "183.119.136.106",
"mobileNumber": "+116787345437",
"modules": [
"digitalintelligence"
],
"nationalId": "590618849",
"parentTxnId": "35bccdd5-e285-4988-b4e2-f9b55602b4a3",
"physicalAddress": "USNS Collins",
"physicalAddress2": "Unit 7",
"riskOSId": "4c5510af-a397-4430-b628-c952977b6c1f",
"state": "AA",
"surName": "Sell",
"userId": "ANALYSTDEMO_IDPLUS-9109_SCENARIO_3",
"workflow": "consumer_onboarding",
"zip": "98765"
},
"response": {
"customerProfile": {
"userId": "ANALYSTDEMO_IDPLUS-9109_SCENARIO_3"
},
"digitalIntelligence": {
"behavioral": {
"aggregations": {
"blurCount": 3,
"clickCount": 3,
"focusCount": 0,
"inputChangeCount": 6,
"pasteCount": 0,
"submissionCount": 1,
"totalEventCount": 26
},
"duration": 120910,
"serverCreated": "2021-09-01T11:19:58.796Z",
"serverUpdated": "2021-09-11T16:19:58.796Z",
"sessionId": "d34304a6-a726-4dec-b1cd-9c4a3c192a0d",
"source": "https://example.com/"
},
"device": {
"attributes": {
"androidAttributes": {
"isRooted": false,
"mobileNetwork": [
{
"carrierName": "T-Mobile",
"isoCountryCode": "us"
}
]
},
"battery": {
"batteryLevel": 0.47,
"batteryState": "charging"
},
"deviceContext": "homepage",
"deviceManufacturer": "Apple",
"deviceModel": "iphone14,7",
"devicePixelRatio": 1.5,
"deviceType": "tablet",
"iOSAttributes": {
"isRooted": false,
"mobileNetwork": [
{
"carrierName": "T-Mobile",
"isoCountryCode": "us"
}
]
},
"isEmulator": false,
"language": "en-US",
"location": {
"altitude": 998.2,
"bearing": 32,
"bearingAccuracy": 2.1,
"horizontalAccuracy": 2.1,
"latitude": 41.50854591662628,
"longitude": -81.69534315646631,
"speed": 1.3,
"speedAccuracy": 0.2,
"verticalAccuracy": 0
},
"network": {
"vpnStatus": true
},
"os": "iOS",
"osVersion": "17",
"platform": "iOS",
"screenHeight": 1080,
"screenWidth": 1920,
"sdkVersion": "3.0.1",
"timeZone": "America/New_York",
"timeZoneOffset": -480,
"viewportHeight": 400,
"viewportWidth": 600,
"webAttributes": {
"browser": "Google Chrome",
"browserVersion": "116",
"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
}
},
"computed": {
"isVirtualMachine": false,
"statisticalId": "9349d69fef75cd356744293487462f8cd912"
},
"deviceCaptureAt": "2023-10-24T15:55:17.368756891Z",
"history": {
"daysSeen": [
"2023-10-24"
],
"firstSeen": "2023-10-24T15:55:16.368Z",
"ips": [
"78.32.11.221",
"70.45.2.1"
],
"isps": [
"RogersCable",
"T-Mobile"
],
"lastSeen": "2023-10-24T15:55:16.368Z",
"networkLocations": [
"chicago, il",
"new york, ny",
"paris, fr"
]
},
"id": "234ac3ff-3ed1-42de-8f33-8f332febfa54",
"network": {
"asn": 27364,
"asnName": "armstrong",
"connectionIp": "38.48.122.126",
"domainName": "zoominternet.net",
"forwardedForIps": [
"78.32.11.221",
"70.45.2.1"
],
"isConsumerPrivacy": false,
"isMobileCarrier": true,
"isProxy": false,
"isRiskyNetwork": false,
"isTor": false,
"isVpn": false,
"isp": "comcast",
"ispType": "home",
"networkLocation": {
"city": "Tacoma",
"continentCode": "na",
"countryCode": "US",
"gmtOffset": "-0400",
"latitude": 47.2529001,
"longitude": -122.4443,
"metroCode": 819,
"postalCode": "98401",
"region": "WA",
"timezoneName": "America/New_York"
},
"org": "comcast",
"realIp": "38.48.122.126",
"speed": "cable",
"webRtcInternalIp": "192.168.1.85",
"webRtcPublicIp": "176.124.54.12"
},
"sessionCreatedAt": "2023-10-24T15:55:16.368492137Z"
},
"velocityMetrics": {
"historicalCount": {
"email": {
"uniqueCount": 3,
"uniqueSharePercent": 50
},
"firstName": {
"uniqueCount": 3,
"uniqueSharePercent": 50
},
"lastName": {
"uniqueCount": 3,
"uniqueSharePercent": 50
},
"mobileNumber": {
"uniqueCount": 3,
"uniqueSharePercent": 50
}
}
}
},
"referenceId": "c696cfb6-46b8-4db1-b6dc-8cdf1cd1161a"
},
"is_source_cache": false,
"total_attempts": 1
},
{
"enrichment_name": "Socure Phone Risk",
"enrichment_endpoint": "https://sandbox.socure.com/api/3.0/EmailAuthScore",
"enrichment_provider": "Socure",
"status_code": 200,
"request": {
"city": "FPO",
"country": "US",
"dob": "1999-02-06",
"email": "[email protected]",
"firstName": "Carl",
"ipAddress": "183.119.136.106",
"mobileNumber": "+116787345437",
"modules": [
"phonerisk"
],
"nationalId": "590618849",
"parentTxnId": "35bccdd5-e285-4988-b4e2-f9b55602b4a3",
"physicalAddress": "USNS Collins",
"physicalAddress2": "Unit 7",
"riskOSId": "4c5510af-a397-4430-b628-c952977b6c1f",
"state": "AA",
"surName": "Sell",
"userId": "ANALYSTDEMO_IDPLUS-9109_SCENARIO_3",
"workflow": "consumer_onboarding",
"zip": "98765"
},
"response": {
"customerProfile": {
"userId": "ANALYSTDEMO_IDPLUS-9109_SCENARIO_3"
},
"namePhoneCorrelation": {
"reasonCodes": [
"I618",
"I621",
"I622"
],
"score": 0.99
},
"phoneRisk": {
"reasonCodes": [
"I614",
"I609"
],
"scores": [
{
"name": "RiskPhoneUS.V7__Uniform.V1",
"score": 0.01,
"version": "4.0"
}
]
},
"referenceId": "30c8542a-7b5e-4e54-a710-c91e4990e58b"
},
"is_source_cache": false,
"total_attempts": 1
},
{
"enrichment_name": "Socure OTP - static accept",
"enrichment_endpoint": "https://mockserver.com/api/3.0/EmailAuthScore",
"enrichment_provider": "RestAPI",
"status_code": 200,
"response": {
"attemptCount": 1,
"error": "",
"status": "accept",
"verificationId": "10901fa6-bf0a-441a-8190-7cd109dbab65"
},
"is_source_cache": false,
"total_attempts": 1
},
{
"enrichment_name": "Socure Verify Plus",
"enrichment_endpoint": "https://sandbox.socure.com/api/3.0/EmailAuthScore",
"enrichment_provider": "Socure",
"status_code": 200,
"request": {
"city": "FPO",
"country": "US",
"dob": "1999-02-06",
"email": "[email protected]",
"firstName": "Carl",
"ipAddress": "183.119.136.106",
"mobileNumber": "+116787345437",
"modules": [
"kycplus"
],
"nationalId": "590618849",
"parentTxnId": "35bccdd5-e285-4988-b4e2-f9b55602b4a3",
"physicalAddress": "USNS Collins",
"physicalAddress2": "Unit 7",
"riskOSId": "4c5510af-a397-4430-b628-c952977b6c1f",
"state": "AA",
"surName": "Sell",
"userId": "ANALYSTDEMO_IDPLUS-9109_SCENARIO_3",
"workflow": "consumer_onboarding",
"zip": "98765"
},
"response": {
"customerProfile": {
"userId": "ANALYSTDEMO_IDPLUS-9109_SCENARIO_3"
},
"kycPlus": {
"bestMatchedEntity": {
"associatedAddresses": [],
"associatedEmails": [],
"associatedPhoneNumbers": [],
"dob": "",
"emailAddress": "",
"firstName": "",
"middleName": "",
"mobileNumber": "",
"normalizedAddress": {
"city": "FPO",
"state": "AA",
"streetAddress": "USNS Collins",
"zip": "98765"
},
"ssn": "",
"ssnIssued": "",
"suffix": "",
"surName": ""
},
"fieldValidations": {
"city": 0.99,
"dob": 0.99,
"email": 0.99,
"firstName": 0.99,
"mobileNumber": 0.99,
"ssn": 0.99,
"state": 0.99,
"streetAddress": 0.99,
"surName": 0.99,
"zip": 0.99
},
"reasonCodes": [
"I919"
],
"socureId": "0318d3c3-541c-4090-8250-dec3e41efa89",
"sourceAttribution": [
"Alternative Credit",
"County Tax"
]
},
"referenceId": "c8c69abe-772b-448a-abb0-64ea8b0bed29"
},
"is_source_cache": false,
"total_attempts": 1
},
{
"enrichment_name": "Socure Sigma Synthetic",
"enrichment_endpoint": "https://sandbox.socure.com/api/3.0/EmailAuthScore",
"enrichment_provider": "Socure",
"status_code": 200,
"request": {
"city": "FPO",
"country": "US",
"dob": "1999-02-06",
"email": "[email protected]",
"firstName": "Carl",
"ipAddress": "183.119.136.106",
"mobileNumber": "+116787345437",
"modules": [
"synthetic"
],
"nationalId": "590618849",
"parentTxnId": "35bccdd5-e285-4988-b4e2-f9b55602b4a3",
"physicalAddress": "USNS Collins",
"physicalAddress2": "Unit 7",
"riskOSId": "4c5510af-a397-4430-b628-c952977b6c1f",
"state": "AA",
"surName": "Sell",
"userId": "ANALYSTDEMO_IDPLUS-9109_SCENARIO_3",
"workflow": "consumer_onboarding",
"zip": "98765"
},
"response": {
"customerProfile": {
"userId": "ANALYSTDEMO_IDPLUS-9109_SCENARIO_3"
},
"referenceId": "ae5eb95d-ea79-4458-b863-703a0e263cde",
"synthetic": {
"reasonCodes": [
"I206",
"R224",
"I207"
],
"scores": [
{
"name": "synthetic",
"score": 0.158,
"version": "4.1"
{
"id": "53692841-4add-47d9-94b6-023f3ec59f79",
"workflow": "consumer_onboarding",
"workflow_id": "8b93f74b-7273-410c-a16e-b2ad14613f11",
"workflow_version": "2.6.0",
"eval_source": "API",
"eval_id": "8024151f-7677-4b18-80cb-d987b4ec933a",
"eval_start_time": "2025-12-12T14:46:35.123499275Z",
"eval_end_time": "2025-12-12T14:46:36.198301845Z",
"decision": "REJECT",
"decision_at": "2025-12-12T14:46:36.198147615Z",
"status": "CLOSED",
"sub_status": "Reject",
"tags": [
"Synthetic Fraud - High Risk"
],
"notes": "",
"review_queues": [],
"data_enrichments": [
{
"enrichment_name": "Socure Digital Intelligence",
"enrichment_endpoint": "https://sandbox.socure.com/api/3.0/EmailAuthScore",
"enrichment_provider": "Socure",
"status_code": 200,
"request": {
"city": "Piscataway",
"country": "US",
"deviceSessionId": "eyJraWQi_DI_LOW_SCORE",
"dob": "1974-09-07",
"email": "[email protected]",
"firstName": "Hope",
"ipAddress": "242.103.177.99",
"mobileNumber": "13471729423",
"modules": [
"digitalintelligence"
],
"nationalId": "733842318",
"parentTxnId": "8024151f-7677-4b18-80cb-d987b4ec933a",
"physicalAddress": "52032 Davis Fort",
"riskOSId": "53692841-4add-47d9-94b6-023f3ec59f79",
"state": "NJ",
"surName": "Lambert",
"userId": "ANY",
"workflow": "consumer_onboarding",
"zip": "08854"
},
"response": {
"customerProfile": {
"userId": "ANY"
},
"digitalIntelligence": {
"behavioral": {
"aggregations": {
"blurCount": 3,
"clickCount": 3,
"focusCount": 0,
"inputChangeCount": 6,
"pasteCount": 0,
"submissionCount": 1,
"totalEventCount": 26
},
"duration": 120910,
"serverCreated": "2021-09-01T11:19:58.796Z",
"serverUpdated": "2021-09-11T16:19:58.796Z",
"sessionId": "d34304a6-a726-4dec-b1cd-9c4a3c192a0d",
"source": "https://example.com/"
},
"device": {
"attributes": {
"androidAttributes": {
"isRooted": false,
"mobileNetwork": [
{
"carrierName": "T-Mobile",
"isoCountryCode": "us"
}
]
},
"battery": {
"batteryLevel": 0.47,
"batteryState": "charging"
},
"deviceContext": "homepage",
"deviceManufacturer": "Apple",
"deviceModel": "iphone14,7",
"devicePixelRatio": 1.5,
"deviceType": "tablet",
"iOSAttributes": {
"isRooted": false,
"mobileNetwork": [
{
"carrierName": "T-Mobile",
"isoCountryCode": "us"
}
]
},
"isEmulator": false,
"language": "en-US",
"location": {
"altitude": 998.2,
"bearing": 32,
"bearingAccuracy": 2.1,
"horizontalAccuracy": 2.1,
"latitude": 41.50854591662628,
"longitude": -81.69534315646631,
"speed": 1.3,
"speedAccuracy": 0.2,
"verticalAccuracy": 0
},
"network": {
"vpnStatus": true
},
"os": "iOS",
"osVersion": "17",
"platform": "iOS",
"screenHeight": 1080,
"screenWidth": 1920,
"sdkVersion": "3.0.1",
"timeZone": "America/New_York",
"timeZoneOffset": -480,
"viewportHeight": 400,
"viewportWidth": 600,
"webAttributes": {
"browser": "Google Chrome",
"browserVersion": "116",
"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
}
},
"computed": {
"isVirtualMachine": false,
"statisticalId": "9349d69fef75cd356744293487462f8cd912"
},
"deviceCaptureAt": "2023-10-24T15:55:17.368756891Z",
"history": {
"daysSeen": [
"2023-10-24"
],
"firstSeen": "2023-10-24T15:55:16.368Z",
"ips": [
"78.32.11.221",
"70.45.2.1"
],
"isps": [
"RogersCable",
"T-Mobile"
],
"lastSeen": "2023-10-24T15:55:16.368Z",
"networkLocations": [
"chicago, il",
"new york, ny",
"paris, fr"
]
},
"id": "234ac3ff-3ed1-42de-8f33-8f332febfa54",
"network": {
"asn": 27364,
"asnName": "armstrong",
"connectionIp": "38.48.122.126",
"domainName": "zoominternet.net",
"forwardedForIps": [
"78.32.11.221",
"70.45.2.1"
],
"isConsumerPrivacy": false,
"isMobileCarrier": true,
"isProxy": false,
"isRiskyNetwork": false,
"isTor": false,
"isVpn": false,
"isp": "comcast",
"ispType": "home",
"networkLocation": {
"city": "Tacoma",
"continentCode": "na",
"countryCode": "US",
"gmtOffset": "-0400",
"latitude": 47.2529001,
"longitude": -122.4443,
"metroCode": 819,
"postalCode": "98401",
"region": "WA",
"timezoneName": "America/New_York"
},
"org": "comcast",
"realIp": "38.48.122.126",
"speed": "cable",
"webRtcInternalIp": "192.168.1.85",
"webRtcPublicIp": "176.124.54.12"
},
"sessionCreatedAt": "2023-10-24T15:55:16.368492137Z"
},
"velocityMetrics": {
"historicalCount": {
"email": {
"uniqueCount": 3,
"uniqueSharePercent": 50
},
"firstName": {
"uniqueCount": 3,
"uniqueSharePercent": 50
},
"lastName": {
"uniqueCount": 3,
"uniqueSharePercent": 50
},
"mobileNumber": {
"uniqueCount": 3,
"uniqueSharePercent": 50
}
}
}
},
"referenceId": "c7eeb803-41d5-46da-8dec-afb65891a243"
},
"is_source_cache": false,
"total_attempts": 1
},
{
"enrichment_name": "Socure Phone Risk",
"enrichment_endpoint": "https://sandbox.socure.com/api/3.0/EmailAuthScore",
"enrichment_provider": "Socure",
"status_code": 200,
"request": {
"city": "Piscataway",
"country": "US",
"dob": "1974-09-07",
"email": "[email protected]",
"firstName": "Hope",
"ipAddress": "242.103.177.99",
"mobileNumber": "13471729423",
"modules": [
"phonerisk"
],
"nationalId": "733842318",
"parentTxnId": "8024151f-7677-4b18-80cb-d987b4ec933a",
"physicalAddress": "52032 Davis Fort",
"riskOSId": "53692841-4add-47d9-94b6-023f3ec59f79",
"state": "NJ",
"surName": "Lambert",
"userId": "ANY",
"workflow": "consumer_onboarding",
"zip": "08854"
},
"response": {
"customerProfile": {
"userId": "ANY"
},
"namePhoneCorrelation": {
"reasonCodes": [
"I621",
"I622",
"I618"
],
"score": 0.99
},
"phoneRisk": {
"reasonCodes": [
"I601",
"I602",
"I614"
],
"scores": [
{
"name": "RiskPhoneUS.V7__Uniform.V1",
"score": 0.01,
"version": "4.0"
}
]
},
"referenceId": "a2e60f1a-f656-4726-89d4-7c4c3994b765"
},
"is_source_cache": false,
"total_attempts": 1
},
{
"enrichment_name": "Socure OTP - static accept",
"enrichment_endpoint": "https://mockserver.com/api/3.0/EmailAuthScore",
"enrichment_provider": "RestAPI",
"status_code": 200,
"response": {
"attemptCount": 1,
"error": "",
"status": "accept",
"verificationId": "10901fa6-bf0a-441a-8190-7cd109dbab65"
},
"is_source_cache": false,
"total_attempts": 1
},
{
"enrichment_name": "Socure Verify Plus",
"enrichment_endpoint": "https://sandbox.socure.com/api/3.0/EmailAuthScore",
"enrichment_provider": "Socure",
"status_code": 200,
"request": {
"city": "Piscataway",
"country": "US",
"dob": "1974-09-07",
"email": "[email protected]",
"firstName": "Hope",
"ipAddress": "242.103.177.99",
"mobileNumber": "13471729423",
"modules": [
"kycplus"
],
"nationalId": "733842318",
"parentTxnId": "8024151f-7677-4b18-80cb-d987b4ec933a",
"physicalAddress": "52032 Davis Fort",
"riskOSId": "53692841-4add-47d9-94b6-023f3ec59f79",
"state": "NJ",
"surName": "Lambert",
"userId": "ANY",
"workflow": "consumer_onboarding",
"zip": "08854"
},
"response": {
"customerProfile": {
"userId": "ANY"
},
"kycPlus": {
"bestMatchedEntity": {
"associatedAddresses": [],
"associatedEmails": [],
"associatedPhoneNumbers": [],
"dob": "",
"emailAddress": "",
"firstName": "",
"middleName": "",
"mobileNumber": "",
"normalizedAddress": {
"city": "Piscataway",
"state": "NJ",
"streetAddress": "52032 Davis Fort",
"zip": "08854"
},
"ssn": "",
"ssnIssued": "",
"suffix": "",
"surName": ""
},
"fieldValidations": {
"city": 0.99,
"dob": 0.99,
"email": 0.99,
"firstName": 0.99,
"mobileNumber": 0.99,
"ssn": 0.99,
"state": 0.99,
"streetAddress": 0.99,
"surName": 0.99,
"zip": 0.99
},
"reasonCodes": [
"I919"
],
"socureId": "0318d3c3-541c-4090-8250-dec3e41efa89",
"sourceAttribution": [
"Alternative Credit",
"County Tax"
]
},
"referenceId": "82c7d304-d9ed-4ca3-b124-81743fd6ae42"
},
"is_source_cache": false,
"total_attempts": 1
},
{
"enrichment_name": "Socure Sigma Synthetic",
"enrichment_endpoint": "https://sandbox.socure.com/api/3.0/EmailAuthScore",
"enrichment_provider": "Socure",
"status_code": 200,
"request": {
"city": "Piscataway",
"country": "US",
"dob": "1974-09-07",
"email": "[email protected]",
"firstName": "Hope",
"ipAddress": "242.103.177.99",
"mobileNumber": "13471729423",
"modules": [
"synthetic"
],
"nationalId": "733842318",
"parentTxnId": "8024151f-7677-4b18-80cb-d987b4ec933a",
"physicalAddress": "52032 Davis Fort",
"riskOSId": "53692841-4add-47d9-94b6-023f3ec59f79",
"state": "NJ",
"surName": "Lambert",
"userId": "ANY",
"workflow": "consumer_onboarding",
"zip": "08854"
},
"response": {
"customerProfile": {
"userId": "ANY"
},
"referenceId": "d600c00e-bbc1-41c0-9a50-374563dad783",
"synthetic": {
"reasonCodes": [
"R606",
"R224",
"R216",
"I568",
"R203",
"R703",
"I708",
"R219",
"I569",
"R208",
"R223",
"R615",
"R299",
"I570"
],
"scores": [
{
"name": "synthetic",
"score": 0.995,
"version": "4.1"
}
]
}
},
"is_source_cache": false,
"total_attempts": 1
},
{
"enrichment_name": "Socure eCBSV Explicit",
"enrichment_endpoint": "https://sandbox.socure.com/api/3.0/EmailAuthScore",
"enrichment_provider": "Socure",
"status_code": 403,
"request": {
"city": "Piscataway",
"country": "US",
"dob": "1974-09-07",
"email": "[email protected]",
"firstName": "Hope",
"ipAddress": "242.103.177.99",
"mobileNumber": "13471729423",
"modules": [
"ecbsv"
],
"nationalId": "733842318",
"parentTxnId": "8024151f-7677-4b18-80cb-d987b4ec933a",
"physicalAddress": "52032 Davis Fort",
"riskOSId": "53692841-4add-47d9-94b6-023f3ec59f79",
"state": "NJ",
"surName": "Lambert",
"userId": "ANY",
"workflow": "consumer_onboarding",
"zip": "08854"
},
"response": {
"response": "{\"status\":\"Error\",\"referenceId\":\"64a90c05-0278-40b1-a712-152efdd280db\",\"data\":{\"permissions\":[\"ECBSV\"]},\"customerProfile\":{\"userId\":\"ANY\"},\"msg\":\"The API key isn't provisioned to serve the request.\"}"
},
"is_source_cache": false,
"total_attempts": 1
},
{
"enrichment_name": "Socure Email Risk",
"enrichment_endpoint": "https://sandbox.socure.com/api/3.0/EmailAuthScore",
"enrichment_provider": "Socure",
"status_code": 200,
"request": {
"city": "Piscataway",
"country": "US",
"dob": "1974-09-07",
"email": "[email protected]",
"firstName": "Hope",
"ipAddress": "242.103.177.99",
"mobileNumber": "13471729423",
"modules": [
"emailrisk"
],
"nationalId": "733842318",
"parentTxnId": "8024151f-7677-4b18-80cb-d987b4ec933a",
"physicalAddress": "52032 Davis Fort",
"riskOSId": "53692841-4add-47d9-94b6-023f3ec59f79",
"state": "NJ",
"surName": "Lambert",
"userId": "ANY",
"workflow": "consumer_onboarding",
"zip": "08854"
},
"response": {
"customerProfile": {
"userId": "ANY"
},
"emailRisk": {
"reasonCodes": [
"I556",
"I553",
"I520"
],
"scores": [
{
"name": "RiskEmailUS.V11__Uniform.V1",
"score": 0.01,
"version": "4.0"
}
]
},
"nameEmailCorrelation": {
"reasonCodes": [
"I556",
"I557",
"I558"
],
"score": 0.99
},
"referenceId": "2668c253-b5ac-4121-a951-05c162b4684c"
},
"is_source_cache": false,
"total_attempts": 1
},
{
"enrichment_name": "Socure Address Risk",
"enrichment_endpoint": "https://sandbox.socure.com/api/3.0/EmailAuthScore",
"enrichment_provider": "Socure",
"status_code": 200,
"request": {
"city": "Piscataway",
"country": "US",
"dob": "1974-09-07",
"email": "[email protected]",
"firstName": "Hope",
"ipAddress": "242.103.177.99",
"mobileNumber": "13471729423",
"modules": [
"addressrisk"
],
"nationalId": "733842318",
"parentTxnId": "8024151f-7677-4b18-80cb-d987b4ec933a",
"physicalAddress": "52032 Davis Fort",
"riskOSId": "53692841-4add-47d9-94b6-023f3ec59f79",
"state": "NJ",
"surName": "Lambert",
"userId": "ANY",
"workflow": "consumer_onboarding",
"zip": "08854"
},
"response": {
"addressRisk": {
"reasonCodes": [
"I708",
"I705",
"I704"
],
"scores": [
{
"name": "RiskAddressNOIPUS.V8__Uniform.V1",
"score": 0.01,
"version": "4.0"
}
]
},
"customerProfile": {
"userId": "ANY"
},
"nameAddressCorrelation": {
"reasonCodes": [
"I710",
"I709",
"I708"
],
"score": 0.99
},
"referenceId": "cb6137f8-de02-4837-9e63-844b2a1ee385"
},
"is_source_cache": false,
"total_attempts": 1
},
{
"enrichment_name": "Socure GraphIntelligence + Sigma Fraud",
"enrichment_endpoint": "https://sandbox.socure.com/api/3.0/EmailAuthScore",
"enrichment_provider": "Socure",
"status_code": 200,
"request": {
"city": "Piscataway",
"country": "US",
"dob": "1974-09-07",
"email": "[email protected]",
"firstName": "Hope",
"ipAddress": "242.103.177.99",
"mobileNumber": "13471729423",
"modules": [
"graphintelligence",
"fraud"
],
"nationalId": "733842318",
"parentTxnId": "8024151f-7677-4b18-80cb-d987b4ec933a",
"physicalAddress": "52032 Davis Fort",
"riskOSId": "53692841-4add-47d9-94b6-023f3ec59f79",
"state": "NJ",
"surName": "Lambert",
"userId": "ANY",
"workflow": "consumer_onboarding",
"zip": "08854"
},
"response": {
"customerProfile": {
"userId": "ANY"
},
"fraud": {
"reasonCodes": [
"I553",
"I121",
"I127"
],
"scores": [
{
"name": "sigma",
"score": 0.43,
"version": "4.0"
}
]
},
"graphIntelligence": {
// Socure returns additional raw address signals not shown here for brevity and sensitivity.
},
"referenceId": "a321b9f8-f115-4e23-8fee-12daa073b256"
},
"is_source_cache": false,
"total_attempts": 1
}
],
"eval_status": "evaluation_completed",
"score": 11,
"environment_name": "Sandbox"
}
Key response fields
RiskOS™ returns a consistent set of top-level fields that describe the outcome of an evaluation, along with enrichment outputs that depend on your workflow configuration.
Where to find specific results
| Area | Fields | How to use it |
|---|---|---|
| Decision and routing | decision, decision_at, tags, review_queues, notes, score | Primary control signals. Branch application logic using decision. Use tags, queues, notes, and score for secondary routing, review, and explanation. |
| Module results | Module-specific fields (for example: reasonCodes, scores, extracted attributes) | Evidence and signals produced by workflow modules. Use for escalation, compliance review, investigation, and audit. |
| Identifiers and traceability | id, eval_id | Persist these identifiers to correlate API calls, logs, webhooks, GET requests, and support cases. |
| Enrichment execution | data_enrichments[] (response, status_code, total_attempts, is_source_cache) | Inspect enrichment outputs and detect provisioning issues, partial failures, retries, or cached responses. |
| Workflow context | workflow, workflow_id, workflow_version | Understand which workflow ran and which version produced the result. Useful for debugging and historical analysis. |
| Evaluation lifecycle | eval_status, status, sub_status | Execution and case state only. Useful for monitoring and asynchronous workflows. Do not use for business decisions. |
| Execution context | eval_source, eval_start_time, eval_end_time, environment_name | Observability and performance metadata for latency tracking, environment validation, and API vs Dashboard attribution. |
Decision and routing (primary control signals)
These fields describe the outcome of an evaluation and any routing applied by the workflow.
decisionvalues are workflow-specific and may differ from the examples shown in this guide.
| Field | Type | Description | Example |
|---|---|---|---|
decision | String (enum) | Final evaluation result. Possible values: • ACCEPT• REVIEW• REJECTNote: The fields returned can be customized to fit your integration or business needs. | "ACCEPT" |
decision_at | String <Date-Time> | RFC 3339 timestamp when the decision was finalized. | "2025-12-11T17:49:28.930Z" |
score | Number | If configured for a workflow, provides an aggregate score of all steps. This can be used for risk banding, additional routing, or analytics alongside the primary decision value. | 11 |
tags | Array of Strings | Array of labels applied during the workflow to highlight routing choices, notable signals, or rule outcomes. Useful for reporting, segmentation, or UI highlighting in the RiskOS™ Dashboard. | [] |
review_queues | Array of Strings | Lists any manual review queues the evaluation was sent to. Empty when the case is fully auto-resolved without human review. | [] |
notes | String | Freeform text field for analyst or system comments about the evaluation. Often used to capture manual review rationale or investigation context. | "" |
Evaluation lifecycle and status
These fields describe where the evaluation is in its lifecycle and are useful for monitoring and asynchronous workflows.
| Field | Type | Description | Example |
|---|---|---|---|
eval_status | String (enum) | Internal RiskOS™ evaluation lifecycle state. Possible values: • evaluation_completed• evaluation_paused• evaluation_in_progress | "evaluation_completed" |
status | String (enum) | Case-level status of the evaluation. Possible values: • OPEN• CLOSED | "CLOSED" |
sub_status | String | Provides additional detail about the evaluation status. Example values: • Under Review• Pending Verification• Accept• Reject | "Accept" |
Identifiers and traceability
Use these fields to correlate requests, logs, webhooks, and support cases.
| Field | Type | Description | Example |
|---|---|---|---|
id | String (UUID or custom string) | Your evaluation identifier within RiskOS™. Note: This is customer-generated. | "895dc35b-cee7-4f14-af06-6e26482178f8" |
eval_id | String (UUID) | RiskOS-generated unique identifier for the evaluation. | "b1c0e610-822d-4793-a970-8bfc0a9b883f" |
workflow | String | Name of the workflow executed. | "consumer_onboarding" |
workflow_id | String (UUID) | Unique identifier for the workflow run. | "8b93f74b-7273-410c-a16e-b2ad14613f11" |
workflow_version | String | Version of the executed workflow. | "2.6.0" |
Execution context
These fields provide timing and environment context for the evaluation.
| Field | Type | Description | Example |
|---|---|---|---|
eval_source | String (enum) | Indicates where the evaluation was initiated from. Possible values: • API: Request submitted via the Evaluation API.• Dashboard: Case created or evaluated through the RiskOS™ Dashboard. | "API" |
eval_start_time | String <Date-Time> | RFC 3339 timestamp for when RiskOS™ started processing the evaluation. Useful for latency and performance monitoring. | "2025-12-11T17:49:28.529Z" |
eval_end_time | String <Date-Time> | RFC 3339 timestamp for when RiskOS™ finished processing the evaluation. Can be paired with eval_start_time to compute total processing time. | "2025-12-11T17:49:28.931Z" |
environment_name | String | Indicates which environment the evaluation ran in. Typically Sandbox for testing or Production for live traffic. | "Sandbox" |
Enrichment results
Enrichment outputs are returned in the data_enrichments array. Each object corresponds to a module executed as part of the Consumer Onboarding workflow.
| Field | Type | Description | Example |
|---|---|---|---|
enrichment_name | String | Name of the enrichment executed. | "Socure Digital Intelligence" |
enrichment_provider | String | Provider of the enrichment. | "Socure" |
status_code | Integer | HTTP status returned by the enrichment call. | 200 |
request | Object | Provider request payload (for observability and debugging). | See request schema below. |
response | Object | Normalized enrichment response. | See response schema below. |
is_source_cache | Boolean | Indicates whether cached data was used. | false |
total_attempts | Integer | Number of attempts made to retrieve the data. | 1 |
Example request fields (varies by enrichment)
request fields (varies by enrichment)| Field | Type | Required | Description | Example |
|---|---|---|---|---|
firstName | String | Required | Consumer's first/given name submitted to the enrichment. | "Emily" |
surName | String | Required | Consumer's last/family name submitted to the enrichment. | "Brown" |
nationalId | String | Optional | Government-issued identifier (e.g., SSN or National ID). | "555667777" |
dob | String YYYY-MM-DD | Required | Consumer's date of birth used for KYC and verification. | "1992-03-15" |
email | String | Required | Consumer's email address. | "emily.brown.[email protected]" |
mobileNumber | String (E.164) | Required | Consumer's phone number. | "16073680976" |
city | String | Optional | City, town, or village name where the consumer resides. | "Springfield" |
state | String | Optional | The state, province, or region where the consumer resides. | "IL" |
zip | String | Optional | The consumer's ZIP code, postal code, or equivalent regional identifier for mail delivery. | "62704" |
physicalAddress | String | Optional | The first line of the consumer's address. | "742 Evergreen Terrace" |
physicalAddress2 | String | Optional | An optional second line for the address, such as apartment number, suite, or building landmarks. | "Apt 2B" |
country | String | Optional | The country where the consumer resides, specified in ISO 3166-1 alpha-2 country code for international address standardization. | "US" |
workflow | String | Required | Workflow name for context routing. | "consumer_onboarding" |
modules | Array of Strings | Required | List of RiskOS™ modules invoked in the enrichment call. | ["digitalintelligence"] |
riskOSId | String (UUID) | Required | Transaction identifier linking this enrichment to the evaluation. | "cd9d9b8f-95a3-41b0-bf55-7fa45628f763" |
parentTxnId | String (UUID) | Required | Parent evaluation transaction ID. | "de8438af-c78c-4f25-b850-5ba613ee140d" |
userId | String | Optional | Customer’s internal identifier for the applicant. | "username" |
Example response fields (varies by enrichment)
response fields (varies by enrichment)| Field | Type | Description | Example |
|---|---|---|---|
customerProfile | Object | Customer profile information and identifiers associated with the evaluation. | See customerProfile schema below. |
digitalIntelligence | Object | Comprehensive device and behavioral intelligence data from Socure's DI service. | See Digital Intelligence. |
fraud | Object | Fraud risk scores and reason codes indicating potential fraudulent activity patterns. | See Sigma Identity Fraud. |
synthetic | Object | Synthetic identity detection scores and indicators for artificially created identities. | See Sigma Synthetic Fraud. |
phoneRisk | Object | Phone number risk assessment including validation, carrier info, and risk indicators. | See Phone Risk. |
emailRisk | Object | Email address risk evaluation including domain analysis and reputation scoring. | See Email Risk. |
addressRisk | Object | Address validation and risk assessment including deliverability and fraud indicators. | See Address Risk. |
graphIntelligence | Object | Network analysis showing connections between identity elements across Socure's data graph. | See Graph Intelligence. |
referenceId | String | Unique identifier assigned to each enrichment after a RiskOS™ workflow is finalized. | "4b905868-9d20-4d1c-9fde-544aeede981f" |
customerProfile fields
customerProfile fields| Field | Type | Description | Example |
|---|---|---|---|
userId | String | Customer-provided unique identifier for the individual being evaluated. | `"09237 |
Handle Step-Up with Predictive DocV
If your workflow includes the asynchronous Predictive DocV step, you must handle cases where RiskOS™ requires additional trust signals before it can issue a final decision.
In these cases, the evaluation pauses and requests a government-issued ID and selfie. Your integration must detect this paused state and launch either the DocV SDK or a Hosted Flow to collect the required verification assets.
Because this step completes asynchronously, RiskOS™ resumes the evaluation after document capture and returns the final outcome through the evaluation_completed webhook.
Detect the Step-Up signal
Detect a Step-Up condition by checking for both of the following in the evaluation response:
- Paused evaluation state:
eval_statusis"evaluation_paused"orstatusis"ON_HOLD". - DocV request enrichment:
data_enrichmentsincludes an object whereenrichment_provideris"SocureDocRequest".
Extract handoff assets
Locate the SocureDocRequest object and extract the following from response.data:
| Field | Purpose |
|---|---|
docvTransactionToken | Required. Use this value to initialize the DocV SDK. |
url | Optional. Use for direct mobile redirects to the Capture App (DocV Web SDK and Hosted Flows only). |
qrCode | Optional. Base64 PNG for desktop-to-mobile handoff (DocV Web SDK only). |
{
"eval_id": "500c6b88-9f5c-4d62-9422-163a59a343fe",
"decision": "REVIEW",
"status": "ON_HOLD",
"eval_status": "evaluation_paused",
"data_enrichments": [
{
"enrichment_provider": "SocureDocRequest",
"response": {
"data": {
"docvTransactionToken": "70c6a4bc-f646-4c6a-94c1-9cd428e356ef",
"url": "https://verify.socure.com/#/dv/70c6a4bc-f646-4c6a-94c1-9cd428e356ef"
}
}
}
]
}Complete the Handoff
If a token is present, your backend should:
- Persist the
eval_idand token for later correlation with the webhook result. - Return the token to your client-side application.
- Transition the user to the identity verification UI to launch the SDK.
Response schema
Top-level fields
| Field | Type | Description | Example |
|---|---|---|---|
id | String | Your original request id, echoed back in the response. | "DOCV-CASE-001234" |
eval_id | String (UUID) | Internally generated for each evaluation; required for GET/PATCH requests. | "e5c3b4b2-9e0f-44f2-9c6f-0a3a5f2b7b61" |
decision | String | Final decision — PASS, REVIEW, or FAIL. | "REVIEW" |
status | String | Case status in RiskOS™ — OPEN, CLOSED, or ON_HOLD. | "ON_HOLD" |
eval_status | String | Processing state — evaluation_paused indicates Step-Up is required. | "evaluation_paused" |
tags | Array | Labels explaining the decision (e.g., "Document Verification Triggered"). | ["Document Verification Triggered"] |
data_enrichments fields
data_enrichments fields| Field | Type | Description | Example |
|---|---|---|---|
enrichment_name | String | Name of the enrichment product. | "Socure DocV" |
enrichment_provider | String | Provider identifier. Look for SocureDocRequest. | "SocureDocRequest" |
status_code | Integer | HTTP status code of the enrichment call. | 200 |
response | Object | Payload containing the DocV handoff assets. | See response schema |
response.data Handoff Details
response.data Handoff Details| Field | Type | Description |
|---|---|---|
docvTransactionToken | String | Required to initialize the DocV Web SDK. |
url | String | Direct link to the Socure-hosted Capture App. |
qrCode | String | Base64-encoded PNG for desktop-to-mobile handoff. |
Launch the DocV SDK
The DocV SDKs and Hosted Flows embed the RiskOS™ document verification experience directly into your application.
It renders the Capture App, a secure mobile experience that guides the user through:
- Capturing a government-issued ID
- Taking a selfie
- Completing liveness verification
The Capture App UI is configurable from the DocV App page in the RiskOS™ Dashboard.
No resubmit: Treat DocV as a one-time step-up for the evaluation. If the step-up fails, RiskOS™ completes the evaluation and you should route the user to your fallback/manual flow (typically a final
REJECTdecision is delivered via webhook).
Receive the final decision (Webhook)
After the Capture App flow completes, RiskOS™ resumes the paused evaluation asynchronously. The final result is delivered via a webhook event.
To receive the final decision, configure a webhook endpoint on the Developer Workbench > Webhooks page in the RiskOS™ Dashboard.
Listen for the evaluation_completed event
evaluation_completed eventRiskOS™ sends an evaluation_completed event when processing finishes. The final outcome is in data.decision.
{
"event_type": "evaluation_completed",
"event_id": "3b31289c-2d4a-4107-80bc-dda63031d5a0",
"event_at": "2025-07-17T01:20:01Z",
"data": {
"eval_id": "11111111-2222-3333-4444-555555555555",
"id": "client-transaction-12345",
"workflow": "consumer_onboarding",
"workflow_id": "5937a624-f298-452c-9169-ceeae9e66b74",
"workflow_version": "1.0.0",
"environment_name": "Sandbox",
"eval_source": "API",
"eval_start_time": "2025-07-17T01:18:27Z",
"eval_end_time": "2025-07-17T01:20:01Z",
"eval_status": "evaluation_completed",
"decision": "ACCEPT",
"decision_at": "2025-07-17T01:20:01Z",
"status": "CLOSED",
"sub_status": "Accept",
"tags": [],
"notes": "",
"review_queues": [
"Default Queue"
],
"data_enrichments": [
{
"enrichment_name": "Socure Document Request - Default Flow",
"enrichment_endpoint": "https://service.socure.com/api/5.0/documents/request",
"enrichment_provider": "SocureDocRequest",
"status_code": 200,
"response": {
"referenceId": "ed6a5077-b272-4a75-8c21-b284e10927cd",
"status": "SESSION_COMPLETE",
"data": {
"docvTransactionToken": "7d6ad42b-f804-4255-b25e-268b8a77c86f",
"url": "https://verify.socure.com/#/dv/7d6ad42b-f804-4255-b25e-268b8a77c86f"
}
}
},
{
"enrichment_name": "Socure Document Verification",
"enrichment_endpoint": "https://service.socure.com/api/5.0/documents/verify",
"enrichment_provider": "Socure",
"status_code": 200,
"response": {
"referenceId": "ed6a5077-b272-4a75-8c21-b284e10927c",
"documentVerification": {
"decision": {
"name": "standard",
"value": "accept"
},
"reasonCodes": [
"I831",
"I836"
],
"documentType": {
"type": "Drivers License",
"country": "USA",
"state": "NY"
},
"documentData": {
"firstName": "Test",
"surName": "User",
"fullName": "Test User",
"dob": "1990-01-01",
"documentNumber": "TST1234567",
"expirationDate": "2030-01-01"
},
"digitalIntelligence": {
"device": {
"id": "e92ee549-e3c7-4307-9be7-32fefb0db9a4",
"globalDeviceId": "aecddd42-f223-3333-940c-87baab4c6645",
"sessionCreatedAt": "2025-07-17T01:18:28Z",
"deviceCaptureAt": "2025-07-17T01:18:45Z",
"computed": {
"statisticalId": "b90c8faddcd15cd5eafc09bfe4e460d557c5e516f8c5b44b8d3ec1e6f60c30f8",
"isVirtualMachine": false,
"sessionAgeMinutes": 45
},
"network": {
"connectionIp": "203.0.113.10",
"webRtcPublicIp": "203.0.113.10",
"webRtcInternalIp": "10.0.0.15",
"realIp": "203.0.113.10",
"isTor": false,
"isProxy": false,
"isVpn": false,
"isConsumerPrivacy": false,
"isRiskyNetwork": false,
"isp": "Example ISP",
"ispType": "home",
"asn": 64500,
"asnName": "EXAMPLE-NET",
"domainName": "example.net",
"org": "Example Org",
"isMobileCarrier": false,
"speed": "broadband",
"networkLocation": {
"countryCode": "US",
"region": "NY",
"city": "New York",
"postalCode": "10001",
"latitude": 40.75,
"longitude": -73.99,
"metroCode": 501,
"continentCode": "NA",
"timezoneName": "America/New_York",
"gmtOffset": "-0500"
}
}
}
}
}
}
}
]
}
}Key response fields
RiskOS™ returns a consistent set of top-level fields that describe the outcome of an evaluation, along with enrichment-specific results that depend on your workflow configuration.
Where to find specific results
| Area | Fields | How to use it |
|---|---|---|
| Decision and routing | decision, decision_at, tags, review_queues, notes, score | Primary control signals. Branch application logic using decision. Use tags, queues, notes, and score for secondary routing, review, and explanation. |
| Module results | Module-specific fields (for example: reasonCodes, scores, extracted attributes) | Evidence and signals produced by workflow modules. Use for escalation, compliance review, investigation, and audit. |
| Identifiers and traceability | id, eval_id | Persist these identifiers to correlate API calls, logs, webhooks, GET requests, and support cases. |
| Enrichment execution | data_enrichments[] (response, status_code, total_attempts, is_source_cache) | Inspect enrichment outputs and detect provisioning issues, partial failures, retries, or cached responses. |
| Workflow context | workflow, workflow_id, workflow_version | Understand which workflow ran and which version produced the result. Useful for debugging and historical analysis. |
| Evaluation lifecycle | eval_status, status, sub_status | Execution and case state only. Useful for monitoring and asynchronous workflows. Do not use for business decisions. |
| Execution context | eval_source, eval_start_time, eval_end_time, environment_name | Observability and performance metadata for latency tracking, environment validation, and API vs Dashboard attribution. |
Decision and routing (primary control signals)
Use these fields to determine what action your application should take.
Note:
decisionvalues are workflow-specific and may differ from the examples shown in this guide.
| Field | Type | Description | Example |
|---|---|---|---|
decision | String (enum) | Final evaluation result. Possible values: • ACCEPT• REVIEW• REJECTNote: The fields returned can be customized to fit your integration or business needs. | "REVIEW" |
decision_at | String <Date-Time> | RFC 3339 timestamp when the decision was finalized. | "2025-10-18T14:09:22.641Z" |
score | Number | If configured for a workflow, provides an aggregate score of all steps. This can be used for risk banding, additional routing, or analytics alongside the primary decision value. | 0.63 |
tags | Array of Strings | Array of labels applied during the workflow to highlight routing choices, notable signals, or rule outcomes. Useful for reporting, segmentation, or UI highlighting in the RiskOS™ Dashboard. | [] |
review_queues | Array of Strings | Lists any manual review queues the evaluation was sent to. Empty when the case is fully auto-resolved without human review. | [] |
notes | String | Freeform text field for analyst or system comments about the evaluation. Often used to capture manual review rationale or investigation context. | "Manual review recommended based on risk signals" |
Evaluation lifecycle and status
These fields describe where the evaluation is in its lifecycle and are useful for monitoring and asynchronous workflows.
| Field | Type | Description | Example |
|---|---|---|---|
eval_status | String (enum) | Indicates the current state of an evaluation in RiskOS™. Possible values: • evaluation_completed• evaluation_paused• evaluation_in_progress | "evaluation_completed" |
status | String (enum) | Indicates the current state of an evaluation or case. Possible values: • OPEN• CLOSED | "CLOSED" |
sub_status | String | Provides additional detail about the evaluation status. Example values: • Under Review• Pending Verification• Accept• Reject | "Under Review" |
Identifiers and traceability
Use these fields to correlate requests, logs, webhooks, and support cases.
| Field | Type | Description | Example |
|---|---|---|---|
id | String (UUID or custom string) | Your evaluation identifier within RiskOS™. Note: This is customer-generated. | "APP-123456" |
eval_id | String (UUID) | RiskOS-generated unique identifier for the evaluation. | "6dc8f39c-ecc3-4fe0-9283-fc8e5f99e816" |
workflow_id | String (UUID) | Unique identifier for the workflow run. | "dc7f261e-b158-477e-9770-7e4eae066156" |
workflow_version | String | Version of the executed workflow. | "28.16.0" |
Execution context
These fields provide timing and environment context for the evaluation.
| Field | Type | Description | Example |
|---|---|---|---|
eval_source | String enum | Indicates where the evaluation was initiated from. Possible values: • API: Request submitted via the Evaluation API.• Dashboard: Case created or evaluated through the RiskOS™ Dashboard. | "API" |
eval_start_time | String <Date-Time> | RFC 3339 timestamp for when RiskOS™ started processing the evaluation. Useful for latency and performance monitoring. | "2025-10-07T23:50:03.60187976Z" |
eval_end_time | String <Date-Time> | RFC 3339 timestamp for when RiskOS™ finished processing the evaluation. Can be paired with eval_start_time to compute total processing time. | "2025-10-07T23:50:03.738794253Z" |
environment_name | String | Indicates which environment the evaluation ran in. Typically Sandbox for testing or Production for live traffic. | "Sandbox" |
Enrichment results
Enrichment outputs are returned in the data_enrichments array.
| Field | Type | Description | Example |
|---|---|---|---|
enrichment_name | String | Name of the enrichment executed as part of the evaluation. | "Socure DocV" |
enrichment_endpoint | String | API endpoint used for the enrichment request. | "https://sandbox.dev.socure.com/api/3.0/DocumentVerification" |
enrichment_provider | String | Provider responsible for the enrichment. | "Socure" |
status_code | Integer | HTTP status code returned by the enrichment provider. | 200 |
request | Object | Payload sent to the enrichment provider (often redacted in documentation examples). | { ... } |
response | Object | Enrichment response payload containing DocV results. | See documentVerification response schema below. |
documentVerification fields
documentVerification fields| Field | Type | Description | Example |
|---|---|---|---|
reasonCodes | Array of Strings | List of rule or insight codes returned from DocV analysis. | ["I834","I823","I826","I845","I820"] |
documentType | Object | Details about the document type provided for verification. | See documentType fields |
decision | Object | Result of the document verification analysis. | See decision fields |
documentData | Object | Parsed data extracted from the submitted document. | See documentData fields |
reasonCodes are machine-readable flags that explain why a decision occurred (e.g., data mismatches, capture issues, authenticity checks). They appear under the DocV enrichment response and are intended for routing, UX, and review workflows. For more information, see the Reason Codes in the RiskOS™ Dashboard.
Where you’ll see them
data_enrichments.response.documentVerification.reasonCodes
How to use them
- Drive resubmission UX (e.g., prompt for glare removal if an image quality code is present).
- Route to manual review when authenticity or data consistency codes indicate risk.
- Log for audit and analytics.
The full catalog of reason codes and their descriptions is available in your Socure documentation/console or in the reason code list in the RiskOS™ Dashboard.
documentType
documentType| Field | Type | Description | Example |
|---|---|---|---|
type | String | Human-readable document type. | "Drivers License" |
country | String | Country associated with the document type. | "USA" |
state | String | State/region associated with the document type. | "NY" |
Supported document types
Below are the document types you may encounter in documentVerification.documentType and when configuring capture flows. Coverage and acceptance may vary by country and program.
| Document Type | Description |
|---|---|
| Drivers License | A government-issued license permitting the consumer to operate a motor vehicle. |
| Identification Card | A non-driver government-issued photo ID for verifying identity. |
| Passport | An official government document certifying identity and nationality, used for international travel. |
| Employment Authorization Card | A document issued by USCIS that proves authorization to work in the U.S. |
| Permanent Resident Card | A document (e.g., U.S. Green Card) proving the consumer’s lawful permanent resident status. |
| Passport Card | A wallet-sized U.S. document used for land and sea travel between certain countries. |
| Military ID | An ID card issued by a country’s armed forces to identify active-duty or retired service members. |
| Health Card | An ID card issued by a government or insurer to access health services. |
| Visa | An official endorsement permitting the consumer to enter, stay, or work in a foreign country. |
| Social Security Card | A U.S. government-issued card showing the consumer’s Social Security Number (SSN). |
| Weapons License | A document permitting the consumer to carry or own firearms or other regulated weapons. |
| Tribal ID Card | A government-recognized identity card issued by a Native American or Indigenous tribe. |
| Mexican Permanent Resident Card | An identity document for foreign nationals authorized to live permanently in Mexico. |
decision
decisionDocV responses are recommendations only. They are intended to inform your decisioning process and should be integrated into your organization’s broader risk strategy.
| Field | Type | Description | Example |
|---|---|---|---|
name | String | Internal label representing the configured decision rule set (e.g., "lenient" or "strict"). | "lenient" |
value | String | Outcome of the DocV analysis. One of: • accept — Images met validation criteria and were verified.• reject — Images failed some or all required validation criteria.• resubmit — User must resubmit due to unacceptable image quality or missing data.• review — Images did not meet configured criteria and should be manually reviewed. Returned only if enabled in your DocV Product Settings. | "reject" |
documentData
documentDataThe documentData object contains the extracted data from OCR, barcode, or MRZ.
If DocV cannot extract sufficient information due to poor image quality or unreadable fields, the documentData object will not be present, and the decision will be resubmit.
| Field | Type | Description | Example |
|---|---|---|---|
personalNumber | String | The personal identifier value extracted from the ID, when applicable. Note: The meaning and availability of this value vary by country and document type, but it generally represents an identifier tied to the individual rather than the document itself (for example, a tax identification number or voter ID). | "123456" |
personalNumberType | String | Indicates what the personal number represents. Supported values depend on the issuing country and document type. | BRA_CPF |
firstName | String | First/given name parsed from the document. | "John" |
surName | String | Last/family name parsed from the document. | "Smith" |
fullName | String | Full name as printed on the document. | "John Smith" |
address | String | Single-line address string (as returned). | "32194 N College Ave, New York City, NY 10001" |
parsedAddress | Object | Structured address parts extracted from address. | See parsedAddress fields |
documentNumber | String | Document identifier/number. | "00000000" |
dob | String | Date of birth (YYYY-MM-DD). | "1989-05-07" |
issueDate | String | Document issue date (YYYY-MM-DD). | "2021-01-12" |
expirationDate | String | Document expiration date (YYYY-MM-DD). | "2029-05-07" |
barcode | Object | Contains identity and license details parsed from the barcode of a government-issued ID. | See barcode fields. |
parsedAddress fields
parsedAddress fields| Field | Type | Description | Example |
|---|---|---|---|
physicalAddress | String | Primary street address (line 1) of the parsed location. | "32194 N College Ave" |
physicalAddress2 | String | Combined city, state, and postal code as returned from parsing. | "New York City NY 10001" |
city | String | City component extracted from the parsed address. | "New York City" |
state | String | State, province, or regional code component extracted from the address. | "NY" |
country | String | ISO 3166-1 alpha-2 country code associated with the parsed address. | "US" |
zip | String | Postal or ZIP code component extracted from the parsed address. | "10001" |
barcode fields
barcode fields| Field | Type | Description | Example |
|---|---|---|---|
firstName | String | The individual’s given or first name as encoded in the barcode. | "John" |
middleName | String | The individual’s middle name or initial extracted from the barcode. | "Larry" |
surName | String | The individual’s last name or family name as encoded in the barcode. | "Smith" |
nameSuffix | String | Any name suffix present, such as Jr., Sr., II, or III. | "JR" |
complianceType | String | Code representing the license’s compliance type (e.g., Federal or state). | "F" |
licenseClass | String | The class or category of license (e.g., commercial, operator, etc.). | "C" |
Route the user based on the final decision
Because the evaluation completes asynchronously, your frontend should wait for your backend to persist the final decision, then route the user accordingly.
ACCEPT→ Continue onboardingREJECT→ Route to fallback or review flow
One common approach is polling your API until the stored decision changes.
if (data.status?.decision === "ACCEPT") {
router.push("/success");
}
if (data.status?.decision === "REJECT") {
router.push("/review");
}Best practices for integration and maintenance
- Validate inputs against schema.
- Use sandbox identities during QA.
- Monitor
reasonCodes,tags, andreview_queuesfor routing and audit. - Redact secrets from logs and include correlation IDs.
Validation checklist
Test coverage
Known good applicants return
ACCEPT
High-risk or synthetic applicants return
REJECT or REVIEW
DocV step-up scenarios are tested end to end
Asynchronous final decisions are validated when Predictive DocV is enabled
Schema and error handling
Required request fields are validated before submission
Identity, address, and
di_session_token formats match schema requirements
Error responses are captured, logged, and handled safely
Retry logic uses exponential backoff with jitter where appropriate
Logging and observability
Store and log
id, eval_id, and relevant referenceId values
Track
decision, tags, and review_queues for routing and audit
Redact sensitive data such as national ID, date of birth, API keys, and DocV tokens from logs
Updated 1 day ago