Integration Guide
Learn how to call the RiskOS™ Evaluation API for workforce candidate identity verification with Socure Workforce Verification.
Workforce Verification API integration guide
This guide walks you through how to integrate with Socure's /api/evaluation endpoint using the Workforce Verification workflow. You’ll learn how to send candidate identity data, parse the response, and apply decision logic to support hiring, payroll, marketplace, or compliance workflows.
Before you start
Make sure your RiskOS™ environment is provisioned with:
A workflow configured for the Workforce Verification solution.
Verified global support for the Workforce Verification solution.
Postman collection
The following Postman collection can be used to test the Workforce Verification solution with the Evaluation endpoint.
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 an API key
- In the Sandbox RiskOS™ Dashboard, go to Developer Workbench > API Keys.
- Copy your API key securely.
How it works
- Send a
POST /api/evaluationrequest with candidate identity and device data. - RiskOS™ evaluates the request using your Workforce Verification workflow.
- You receive a decision (
ACCEPT,REVIEW,REJECT, orRESUBMIT). - Apply the decision to proceed with onboarding, request additional verification, route to manual review, or halt the workflow.
Note: The
decisionvalues shown in this guide (ACCEPT,REVIEW,REJECT,RESUBMIT) reflect a customized Workforce Verification workflow.Your environment may use different default decision values depending on how your workflow is configured.
Common integration patterns
The table below outlines common integration patterns for Workforce Verification, including typical input requirements and expected outcomes across different markets and use cases.
| Use Case | Required Inputs | Response |
|---|---|---|
| Passive identity verification at the top of the funnel (e.g., when a job application is submitted) | di_session_token + given_name + family_name + phone_number + email + address | Risk decision + Digital Intelligence + Verify Plus |
| Document Verification mid-funnel (e.g., at the interview stage or after an offer is accepted) | di_session_token + given_name + family_name + phone_number + national_id + selfie | Predictive DocV + biometric match |
| Selfie Reverification at the bottom of the funnel (e.g., during the onboarding stage) | di_session_token + given_name + family_name + phone_number + selfie | Selfie Reverification |
| Payroll setup | di_session_token + given_name + family_name + email + phone_number + address + date_of_birth + national_id | Risk decision + Digital Intelligence + Verify Plus |
| Marketplace contractor onboarding | di_session_token + given_name + family_name + email + phone_number + address + date_of_birth + national_id | Risk decision + Digital Intelligence + Verify Plus |
Start a new evaluation
Endpoint
POST https://riskos.sandbox.socure.com/api/evaluationPOST https://riskos.socure.com/api/evaluationAuthentication and headers
Include your API key in the Authorization header as a Bearer token, along with standard JSON headers:
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
Accept: application/json
X-API-Version: 2025-01-01.orion # optional – pins a specific API versionTop of the funnel
Example requests
{
"id": "a86580cc-1733-4188-86b5-717166e1db8c",
"workflow": "trust_and_safety",
"timestamp": "2025-05-02T12:44:22.059Z",
"data": {
"event_type": "passive",
"event_category": "workforce_verification",
"individual": {
"id": "09237776-f16b-4eec-9305-fc425843d887",
"given_name": "Franky",
"family_name": "Valley",
"email": "[email protected]",
"phone_number": "+14155550123",
"address": {
"line_1": "742 Evergreen Terrace",
"line_2": "Apt 2B",
"locality": "Springfield",
"major_admin_division": "IL",
"country": "US",
"postal_code": "62704"
},
"di_session_token": "test123"
}
}
}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",
"workflow": "trust_and_safety",
"timestamp": "2025-05-02T12:44:22.059Z",
"data": {
"event_type": "passive",
"event_category": "workforce_verification",
"individual": {
"id": "09237776-f16b-4eec-9305-fc425843d887",
"given_name": "Franky",
"family_name": "Valley",
"email": "[email protected]",
"phone_number": "+14155550123",
"address": {
"line_1": "742 Evergreen Terrace",
"line_2": "Apt 2B",
"locality": "Springfield",
"major_admin_division": "IL",
"country": "US",
"postal_code": "62704"
},
"di_session_token": "test123"
}
}
}'
Request schema
Top-level fields
Field | Type | Required | Description | Example |
|---|---|---|---|---|
| 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. |
|
| String | Required | RFC 3339 timestamp indicating when the evaluation request was initiated. |
|
| String | Required | Workflow name configured in the RiskOS™ Dashboard. |
|
| Object | Required | Main payload containing individual identity data and event context. | See |
data fields
data fieldsField | Type | Required | Description | Example |
|---|---|---|---|---|
| String | Optional | Event label for configuring different fraud checks in the workflow. Possible values are:
Customers can customize the workflow based on their business risks and risk posture. |
|
| String | Optional | High-level categorization of the verification event type. |
|
| Object | Required | Primary candidate identity information, including name, contact details, and verification tokens. | See |
| Object | Optional | Use this field to send any additional, customer-specific data relevant to the Education verification workflow. |
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. | "09237776-f16b-4eec-9305-fc425843d887" |
given_name | String | Required | Candidate’s legal first name as it appears on government-issued identification. Max 240 characters. | "John" |
family_name | String | Required | Candidate’s legal last name as it appears on government-issued identification. Max 240 characters. | "Smith" |
email | String | Required | Valid email address for candidate communication and identity verification. | "[email protected]" |
phone_number | String | Required | Candidate’s phone number with country code. E.164 format preferred for best results. | "+14155550123" |
address | Object | Optional | Candidate’s mailing address used for identity verification and geographic risk assessment. | See address schema below. |
di_session_token | String | Required | Token required to extract Device Intelligence (DI) signals. | "eyJraWQiOiJmMzRiN2Yi... |
address fields
address fields| Field | Type | Required | Description | Example |
|---|---|---|---|---|
line_1 | String | Optional | Primary address line including street number, house name, and street name. | "123 Main Street" |
line_2 | String | Optional | Secondary address information such as apartment number, suite, or building landmarks. | "Apt 4B" |
locality | String | Optional | City, town, or village name where the candidate resides. | "New York" |
minor_admin_division | String | Optional | District, borough, or county subdivision for precise geographic identification. | "Manhattan" |
major_admin_division | String | Optional | State, province, or primary administrative region. | "NY" |
country | String | Optional | ISO 3166-1 alpha-2 country code for international address standardization. | "US" |
postal_code | String | Optional | ZIP code, postal code, or equivalent regional identifier for mail delivery. | "10001" |
external_device fields - Optional
external_device fields - OptionalUse these fields when integrating device data from third-party providers (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 |
Example 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 workflow.
{
"id": "a86580cc-1733-4188-86b5-717166e1db8c",
"workflow": "trust_and_safety",
"workflow_id": "e2c86213-d59c-4196-ae01-03e146b488d2",
"workflow_version": "4.53.0",
"eval_source": "API",
"eval_id": "7bc4b7c8-eb67-429b-919a-cdc9ab3c590f",
"eval_start_time": "2025-10-30T17:39:55.583772757Z",
"eval_end_time": "2025-10-30T17:39:56.498977384Z",
"decision": "ACCEPT",
"decision_at": "2025-10-30T17:39:56.498765175Z",
"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": "test123",
"email": "[email protected]",
"firstName": "Franky",
"mobileNumber": "+14155550123",
"modules": [
"digitalintelligence"
],
"parentTxnId": "7bc4b7c8-eb67-429b-919a-cdc9ab3c590f",
"physicalAddress": "742 Evergreen Terrace",
"physicalAddress2": "Apt 2B",
"riskOSId": "a86580cc-1733-4188-86b5-717166e1db8c",
"state": "IL",
"surName": "Valley",
"userId": "09237776-f16b-4eec-9305-fc425843d887",
"workflow": "trust_and_safety",
"zip": "62704"
},
"response": {
"customerProfile": {
"userId": "09237776-f16b-4eec-9305-fc425843d887"
},
"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": "1b134afb-23a0-475c-bbb9-65b9e679234e"
},
"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",
"email": "[email protected]",
"firstName": "Franky",
"mobileNumber": "+14155550123",
"modules": [
"graphintelligence",
"fraud"
],
"parentTxnId": "7bc4b7c8-eb67-429b-919a-cdc9ab3c590f",
"physicalAddress": "742 Evergreen Terrace",
"physicalAddress2": "Apt 2B",
"riskOSId": "a86580cc-1733-4188-86b5-717166e1db8c",
"state": "IL",
"surName": "Valley",
"userId": "09237776-f16b-4eec-9305-fc425843d887",
"workflow": "trust_and_safety",
"zip": "62704"
},
"response": {
"customerProfile": {
"userId": "09237776-f16b-4eec-9305-fc425843d887"
},
"fraud": {
"reasonCodes": [
"I641",
"I555",
"I576",
"I602"
],
"scores": [
{
"name": "sigma",
"score": 0.21,
"version": "4.0"
}
]
},
"graphIntelligence": {
// Socure returns additional raw address signals not shown here for brevity and sensitivity.
},
"referenceId": "3bad7434-8998-46f9-b7bc-f79a23fd5109"
},
"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",
"email": "[email protected]",
"firstName": "Franky",
"mobileNumber": "+14155550123",
"modules": [
"synthetic"
],
"parentTxnId": "7bc4b7c8-eb67-429b-919a-cdc9ab3c590f",
"physicalAddress": "742 Evergreen Terrace",
"physicalAddress2": "Apt 2B",
"riskOSId": "a86580cc-1733-4188-86b5-717166e1db8c",
"state": "IL",
"surName": "Valley",
"userId": "09237776-f16b-4eec-9305-fc425843d887",
"workflow": "trust_and_safety",
"zip": "62704"
},
"response": {
"customerProfile": {
"userId": "09237776-f16b-4eec-9305-fc425843d887"
},
"referenceId": "5df737cf-cc00-49c0-be43-a55c41d12d04",
"synthetic": {
"reasonCodes": [
"I205",
"R223",
"R221"
],
"scores": [
{
"name": "synthetic",
"score": 0.423,
"version": "4.0"
}
]
}
},
"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": {
"city": "Springfield",
"country": "US",
"email": "[email protected]",
"firstName": "Franky",
"mobileNumber": "+14155550123",
"modules": [
"phonerisk"
],
"parentTxnId": "7bc4b7c8-eb67-429b-919a-cdc9ab3c590f",
"physicalAddress": "742 Evergreen Terrace",
"physicalAddress2": "Apt 2B",
"riskOSId": "a86580cc-1733-4188-86b5-717166e1db8c",
"state": "IL",
"surName": "Valley",
"userId": "09237776-f16b-4eec-9305-fc425843d887",
"workflow": "trust_and_safety",
"zip": "62704"
},
"response": {
"customerProfile": {
"userId": "09237776-f16b-4eec-9305-fc425843d887"
},
"namePhoneCorrelation": {
"reasonCodes": [
"I621",
"I618",
"I622"
],
"score": 0.99
},
"phoneRisk": {
"reasonCodes": [
"I608",
"I601",
"I620"
],
"score": 0.01,
"scores": [
{
"name": "RiskPhoneUS.V6__Custom.Atlanticus.2324.Norm.V1",
"score": 0.01,
"version": "6.0"
}
]
},
"referenceId": "55cd81db-7260-4187-b177-37dad5d40341"
},
"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",
"email": "[email protected]",
"firstName": "Franky",
"mobileNumber": "+14155550123",
"modules": [
"emailrisk"
],
"parentTxnId": "7bc4b7c8-eb67-429b-919a-cdc9ab3c590f",
"physicalAddress": "742 Evergreen Terrace",
"physicalAddress2": "Apt 2B",
"riskOSId": "a86580cc-1733-4188-86b5-717166e1db8c",
"state": "IL",
"surName": "Valley",
"userId": "09237776-f16b-4eec-9305-fc425843d887",
"workflow": "trust_and_safety",
"zip": "62704"
},
"response": {
"customerProfile": {
"userId": "09237776-f16b-4eec-9305-fc425843d887"
},
"emailRisk": {
"reasonCodes": [
"I555",
"I520",
"I553"
],
"score": 0.01
},
"nameEmailCorrelation": {
"reasonCodes": [
"I556",
"I558",
"I557"
],
"score": 0.99
},
"referenceId": "5c03d1cc-0278-4cb1-99bc-ae13abf1cbe9"
},
"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",
"email": "[email protected]",
"firstName": "Franky",
"mobileNumber": "+14155550123",
"modules": [
"addressrisk"
],
"parentTxnId": "7bc4b7c8-eb67-429b-919a-cdc9ab3c590f",
"physicalAddress": "742 Evergreen Terrace",
"physicalAddress2": "Apt 2B",
"riskOSId": "a86580cc-1733-4188-86b5-717166e1db8c",
"state": "IL",
"surName": "Valley",
"userId": "09237776-f16b-4eec-9305-fc425843d887",
"workflow": "trust_and_safety",
"zip": "62704"
},
"response": {
"addressRisk": {
"reasonCodes": [
"I704",
"I705",
"I720"
],
"score": 0.01
},
"customerProfile": {
"userId": "09237776-f16b-4eec-9305-fc425843d887"
},
"nameAddressCorrelation": {
"reasonCodes": [
"I709",
"I710",
"I708"
],
"score": 0.99
},
"referenceId": "db992cc9-7022-46a2-baea-92e85341d40e"
},
"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",
"email": "[email protected]",
"firstName": "Franky",
"mobileNumber": "+14155550123",
"modules": [
"kycplus"
],
"parentTxnId": "d160f049-5501-475c-a603-f0d42aacd70d",
"physicalAddress": "742 Evergreen Terrace",
"physicalAddress2": "Apt 2B",
"riskOSId": "a86580cc-1733-4188-86b5-717166e1db8c",
"state": "IL",
"surName": "Valley",
"userId": "09237776-f16b-4eec-9305-fc425843d887",
"workflow": "trust_and_safety",
"zip": "62704"
},
"response": {
"customerProfile": {
"userId": "09237776-f16b-4eec-9305-fc425843d887"
},
"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,
"email": 0.99,
"firstName": 0.99,
"mobileNumber": 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": "a5b90efa-aac0-4f8d-915f-0cf749033fdc"
},
"is_source_cache": false,
"total_attempts": 1
}
],
"eval_status": "evaluation_completed",
"score": 11,
"environment_name": "Sandbox"
}
{
"id": "a86580cc-1733-4188-86b5-717166e1db8c",
"workflow": "trust_and_safety",
"workflow_id": "e2c86213-d59c-4196-ae01-03e146b488d2",
"workflow_version": "4.53.0",
"eval_source": "API",
"eval_id": "7bc4b7c8-eb67-429b-919a-cdc9ab3c590f",
"eval_start_time": "2025-10-30T17:39:55.583772757Z",
"eval_end_time": "2025-10-30T17:39:56.498977384Z",
"decision": "ACCEPT",
"decision_at": "2025-10-30T17:39:56.498765175Z",
"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": "test123",
"email": "[email protected]",
"firstName": "Franky",
"mobileNumber": "+14155550123",
"modules": ["digitalintelligence"],
"parentTxnId": "7bc4b7c8-eb67-429b-919a-cdc9ab3c590f",
"physicalAddress": "742 Evergreen Terrace",
"physicalAddress2": "Apt 2B",
"riskOSId": "a86580cc-1733-4188-86b5-717166e1db8c",
"state": "IL",
"surName": "Valley",
"userId": "09237776-f16b-4eec-9305-fc425843d887",
"workflow": "trust_and_safety",
"zip": "62704"
},
"response": {
"customerProfile": {
"userId": "09237776-f16b-4eec-9305-fc425843d887"
},
"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/"
}
},
"referenceId": "1b134afb-23a0-475c-bbb9-65b9e679234e"
},
"is_source_cache": false,
"total_attempts": 1
},
{
"enrichment_name": "Education Verification",
"enrichment_endpoint": "https://mockserver.com/api/vs/static/insights/v3/a2/submit-request",
"enrichment_provider": "RestAPI",
"status_code": 200,
"response": {
"derived_results": [
{
"degree": "MASTER OF SCIENCE",
"degree_match_level": 0.9,
"official_school_name": "VS - HOMETOWN UNIVERSITY",
"school_match_level": 1
},
{
"degree": "MASTER OF BUSINESS ADMINISTRATION",
"degree_match_level": 0.9,
"official_school_name": "VS - HOMETOWN UNIVERSITY",
"school_match_level": 1
}
]
},
"is_source_cache": false,
"total_attempts": 1
}
],
"eval_status": "evaluation_completed",
"score": 72,
"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-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.
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• RESUBMIT• 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-10-30T17:39:56.498765175Z" |
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. Indicates whether processing is complete or paused for async steps. 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• ON_HOLD• CLOSED | "CLOSED" |
sub_status | String | Provides additional detail about the evaluation status. Example values: • Under Review• Pending Verification• Accept• Reject | "Reject" |
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. | "a86580cc-1733-4188-86b5-717166e1db8c" |
eval_id | String (UUID) | RiskOS™-generated unique identifier for the evaluation. | "7bc4b7c8-eb67-429b-919a-cdc9ab3c590f" |
workflow | String | Name of the workflow executed. | "trust_and_safety" |
workflow_id | String (UUID) | Unique identifier for the workflow run. | "e2c86213-d59c-4196-ae01-03e146b488d2" |
workflow_version | String | Version of executed workflow. | "4.53.0" |
Execution context
These fields provide timing and environment context for monitoring and debugging.
| 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 when RiskOS started processing. | "2025-10-30T17:39:55.583772757Z" |
eval_end_time | String <Date-Time> | RFC 3339 timestamp when RiskOS finished processing. | "2025-10-30T17:39:56.498977384Z" |
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 | Display name for the enrichment/module executed. | "Socure Digital Intelligence" |
enrichment_endpoint | String | Endpoint that processed the enrichment. | "https://sandbox.socure.com/api/3.0/EmailAuthScore" |
enrichment_provider | String | Provider name (Socure / vendor / internal identifier). | "Socure" |
status_code | Integer | HTTP status code returned by the enrichment call. | 200 |
request | Object | Request payload sent to the enrichment service. | See request schema below. |
response | Object | Normalized response returned by the enrichment. | See response schema below. |
error | String | Populated only if the enrichment encountered an error. | |
is_source_cache | Boolean | true if cached data was used instead of a live call. | false |
total_attempts | Integer | Number of attempts to retrieve enrichment data. | 1 |
Example request fields (varies by enrichment)
request fields (varies by enrichment)| Field | Type | Description | Example |
|---|---|---|---|
country | String | ISO 3166-1 alpha-2 country code submitted to the enrichment service. | "US" |
firstName | String | Candidate’s first name as submitted to the enrichment provider. | "John" |
surName | String | Candidate’s last name as submitted to the enrichment provider. | "Smith" |
nationalId | String | Government-issued identifier (e.g., SSN or National ID) sent for identity verification. | "123456789" |
dob | String | Candidate’s date of birth formatted as YYYY-MM-DD for age and identity verification. | "1990-05-15" |
streetAddress | String | Complete street address line submitted for address verification. | "123 Main Street" |
city | String | City name submitted for geographic verification and risk assessment. | "New York" |
state | String | State or province code submitted for regional risk analysis. | "NY" |
zip | String | ZIP or postal code submitted for precise location verification. | "10001" |
ipAddress | String | IP address submitted for device intelligence and geolocation analysis. | "203.0.113.42" |
phone | String | Phone number in E.164 format submitted for phone risk and validation analysis. | "+13475550100" |
email | String | Email address submitted for email risk assessment and validation. | "[email protected]" |
deviceSessionId | String (UUID) | Digital Intelligence session token submitted for device fingerprinting analysis. | "eyJraWQiOiJmMzRiN2Yi..." |
modules | Array of Strings | List of RiskOS™ modules requested for evaluation in this enrichment call. | ["digitalintelligence"] |
parentTxnId | String (UUID) | Parent transaction identifier linking this enrichment to the main evaluation. | "3d848e40-c166-4d30-bd84-03f1de461be3" |
physicalAddress | String | Full concatenated address string as submitted by the candidate. | "123 Main Street" |
riskOSId | String (UUID) | RiskOS™ transaction identifier for correlation and tracking purposes. | "a86580cc-1733-4188-86b5-717166e1db8c" |
userId | String (UUID) | Customer-provided unique user identifier for the candidate being evaluated. | "09237776-f16b-4eec-9305-fc425843d887" |
workflow | String | Workflow name passed to the enrichment service for context and routing. | "trust_and_safety" |
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. | "09237776-f16b-4eec-9305-fc425843d887" |
Mid-Funnel: Document Verification
Example request
{
"id": "a86580cc-1733-4188-86b5-717166e1db8c",
"workflow": "trust_and_safety",
"timestamp": "2025-05-02T12:44:22.059Z",
"data": {
"event_type": "docv",
"event_category": "workforce_verification",
"individual": {
"id": "09237776-f16b-4eec-9305-fc425843d887",
"given_name": "Franky",
"family_name": "Valley",
"email": "[email protected]",
"phone_number": "+14155550123",
"address": {
"line_1": "742 Evergreen Terrace",
"line_2": "Apt 2B",
"locality": "Springfield",
"major_admin_division": "IL",
"country": "US",
"postal_code": "62704"
},
"docv": {
"config": {
"send_message": true
}
},
"di_session_token": "test123"
}
}
}
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",
"workflow": "trust_and_safety",
"timestamp": "2025-05-02T12:44:22.059Z",
"data": {
"event_type": "docv",
"event_category": "workforce_verification",
"individual": {
"id": "09237776-f16b-4eec-9305-fc425843d887",
"given_name": "Franky",
"family_name": "Valley",
"email": "[email protected]",
"phone_number": "+14155550123",
"address": {
"line_1": "742 Evergreen Terrace",
"line_2": "Apt 2B",
"locality": "Springfield",
"major_admin_division": "IL",
"country": "US",
"postal_code": "62704"
},
"docv": {
"config": {
"send_message": true
}
},
"di_session_token": "test123"
}
}
}'Example response
Sample response when Document Verification is initiated:
{
"id": "a86580cc-1733-4188-86b5-717166e1db8c",
"workflow": "trust_and_safety",
"workflow_id": "e2c86213-d59c-4196-ae01-03e146b488d2",
"workflow_version": "4.53.0",
"eval_source": "API",
"eval_id": "aef52513-0fe1-4a81-aa7f-766cd0628e10",
"eval_start_time": "2025-10-30T18:03:57.271550989Z",
"eval_end_time": "2025-10-30T18:03:57.959628131Z",
"decision": "REVIEW",
"decision_at": "2025-10-30T18:03:57.959642081Z",
"status": "ON_HOLD",
"sub_status": "",
"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,
"request": {
"city": "Springfield",
"config": {
"sendMessage": true
},
"country": "US",
"firstName": "Franky",
"mobileNumber": "+14155550123",
"physicalAddress": "742 Evergreen Terrace",
"physicalAddress2": "Apt 2B",
"state": "IL",
"surName": "Valley",
"zip": "62704"
},
"response": {
"data": {
"docvTransactionToken": "649ccd1d-6629-4c7a-b977-77fd6f5950ff",
"eventId": "649ccd1d-6629-4c7a-b977-77fd6f5950ff",
"qrCode": "data:image/png;base64, iVBORw0KGgoAAAANSUhEUgAAAZoAAAGaCAIAAAC5Z...",
"url": "https://verify.socure.com/#/dv/649ccd1d-6629-4c7a-b977-77fd6f5950ff"
},
"referenceId": "8bbb80d5-5dff-4c0b-b705-5f08aba38642"
},
"is_source_cache": false,
"total_attempts": 1
}
],
"eval_status": "evaluation_paused",
"environment_name": "Sandbox"
}Retrieve the evaluation results
Once Document Verification is complete, you will receive an evaluation_completed webhook event. See webhook Event Subscription Types for more details.
Alternatively, you can also retrieve evaluation results from the Evaluation endpoint via a GET request.
{
"id": "a86580cc-1733-4188-86b5-717166e1db8c",
"workflow": "trust_and_safety",
"workflow_id": "cdefa08b-5dce-4b0a-a87a-23693c01b5e5",
"workflow_version": "4.36.0",
"eval_source": "API",
"eval_id": "1e85e088-ade0-4ef6-bb6d-3524da429114",
"eval_start_time": "2025-09-25T16:43:39.984733153Z",
"eval_end_time": "2025-09-25T16:48:11.028110755Z",
"decision": "ACCEPT",
"decision_at": "2025-09-25T16:48:11.028038014Z",
"status": "CLOSED",
"sub_status": "Accept",
"tags": null,
"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,
"request": {
"city": "New York",
"config": {
"sendMessage": true
},
"country": "US",
"firstName": "John",
"mobileNumber": "19083004979",
"physicalAddress": "123 Main Street",
"state": "NY",
"surName": "Smith",
"zip": "10001"
},
"response": {
"__third_party_name__": "Socure Document Request - Default Flow",
"data": {
"docvTransactionToken": "6a95fcbd-4f42-4673-890f-ca90cd54f7f0",
"eventId": "6a95fcbd-4f42-4673-890f-ca90cd54f7f0",
"qrCode": "data:image/png;base64,...",
"url": "https://verify.socure.com/#/dv/6a95fcbd-4f42-4673-890f-ca90cd54f7f0"
},
"deviceSessionToken": "eyJraWQiOiJmMzRiN2YiLCJhbGciOiJIUzUxMiIsInR5cCI6Ik...",
"status": "SESSION_COMPLETE"
},
"is_source_cache": false,
"total_attempts": 1
},
{
"enrichment_name": "Socure Document Verification - Default Flow",
"enrichment_endpoint": "https://sandbox.socure.com/api/3.0/EmailAuthScore",
"enrichment_provider": "Socure",
"status_code": 200,
"request": {
"authorityVerificationConfig": {},
"city": "New York",
"country": "US",
"deviceSessionId": "eyJraWQiOiJmMzRiN2YiLCJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.DI_LOW_SCORE",
"docvTransactionToken": "6a95fcbd-4f42-4673-890f-ca90cd54f7f0",
"email": "[email protected]",
"firstName": "John",
"mobileNumber": "19083004979",
"modules": [
"documentverification"
],
"parentTxnId": "1e85e088-ade0-4ef6-bb6d-3524da429114",
"physicalAddress": "123 Main Street",
"riskOSId": "a86580cc-1733-4188-86b5-717166e1db8c",
"state": "NY",
"surName": "Smith",
"userId": "09237776-f16b-4eec-9305-fc425843d887",
"workflow": "trust_and_safety",
"zip": "10001"
},
"response": {
"customerProfile": {
"userId": "09237776-f16b-4eec-9305-fc425843d887"
},
"documentVerification": {
"decision": {
"name": "standard",
"value": "accept"
},
"digitalIntelligence": {
"behavioral": {
"aggregations": {
"blurCount": 10,
"clickCount": 1,
"focusCount": 1,
"inputChangeCount": 1,
"pasteCount": 1,
"submissionCount": 1,
"totalEventCount": 10
},
"duration": 5050,
"serverCreated": "2025-01-14T00:10:50.942Z",
"serverUpdated": "2025-01-14T00:10:51.692Z",
"sessionId": "a1cf60e7-5915-4734-9130-223c8371f12a",
"source": "http://localhost:3000/"
},
"device": {
"attributes": {
"androidAttributes": {},
"battery": {
"batteryLevel": 0.88,
"batteryState": "charging"
},
"deviceManufacturer": "Apple",
"deviceMemory": 8,
"deviceModel": "Apple Macintosh",
"devicePixelRatio": 1.1,
"deviceType": "Desktop",
"iOSAttributes": {},
"language": "en-US",
"location": {},
"os": "Mac OS",
"osVersion": "14.5.0",
"platform": "Web",
"screenHeight": 1080,
"screenWidth": 1920,
"sdkVersion": "2.5.0",
"timeZone": "America/Los_Angeles",
"timeZoneOffset": -480,
"viewportHeight": 668,
"viewportWidth": 598,
"webAttributes": {
"browser": "Chrome",
"browserVersion": "131.0.6778.205",
"userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/131.0.0.0 Safari/537.36",
"userAgentExtractionRequired": true
}
},
"computed": {
"isVirtualMachine": false,
"sessionAgeMinutes": 45,
"statisticalId": "e81a14d6621cfd2ed9390be9d9eba266851e391aa751881cda9f74377197980b"
},
"deviceCaptureAt": "2025-01-14T00:10:49.385195428Z",
"history": {
"daysSeen": [
"2025-01-08",
"2025-01-14"
],
"firstSeen": "2025-01-08T15:55:46.143356159Z",
"ips": [
"192.184.177.36",
"72.150.12.157"
],
"isps": [
"sonic.net llc",
"comcast cable communications inc."
],
"lastSeen": "2025-01-14T00:10:49.385195428Z",
"networkLocations": [
"houston, ca",
"redwood city, ca"
]
},
"id": "844da0ea-767a-48da-8cb5-5f2e179f43f4",
"network": {
"asn": 7922,
"asnName": "comcast cable communications llc",
"connectionIp": "72.150.12.157",
"domainName": "comcast.net",
"isConsumerPrivacy": false,
"isMobileCarrier": false,
"isProxy": false,
"isRiskyNetwork": false,
"isTor": false,
"isVpn": false,
"isp": "comcast cable communications inc.",
"ispType": "home",
"networkLocation": {
"city": "redwood city",
"continentCode": "NA",
"countryCode": "us",
"gmtOffset": "-800",
"latitude": 37.38,
"longitude": -122.23,
"metroCode": 807,
"postalCode": "94062",
"region": "ca",
"timezoneName": "america/los_angeles"
},
"org": "comcast cable communications inc.",
"realIp": "72.150.12.157",
"speed": "cable",
"webRtcInternalIp": "72.150.12.157",
"webRtcPublicIp": "72.150.12.157"
},
"sessionCreatedAt": "2025-01-14T00:10:49.377717442Z"
},
"entityProfiler": [
{
"entity": "[email protected]",
"entityType": "email",
"profile": {
"deviceIsps": [
"comcast cable communications inc."
],
"deviceLanguages": [
"en-us"
],
"deviceModels": [
"iphone",
"apple macintosh"
],
"deviceTimezones": [
"america/los_angeles"
],
"deviceTypes": [
"phone",
"desktop"
],
"firstSeen": "2019-08-30",
"lastSeen": "2025-01-06",
"networkLocationPostalCodes": [
"94062"
],
"networkLocationStates": [
"ca"
],
"seenCount": 30
}
},
{
"entity": "+14159999999",
"entityType": "phone",
"profile": {
"deviceIsps": [
"comcast cable communications inc."
],
"deviceLanguages": [
"en-us"
],
"deviceModels": [
"iphone",
"apple macintosh"
],
"deviceTimezones": [
"america/los_angeles"
],
"deviceTypes": [
"phone",
"desktop"
],
"firstSeen": "2019-08-30",
"lastSeen": "2025-01-06",
"networkLocationPostalCodes": [
"94062"
],
"networkLocationStates": [
"ca"
],
"seenCount": 30
}
},
{
"entity": "123123123",
"entityType": "nationalId",
"profile": {
"deviceIsps": [
"comcast cable communications inc."
],
"deviceLanguages": [
"en-us"
],
"deviceModels": [
"iphone",
"apple macintosh"
],
"deviceTimezones": [
"america/los_angeles"
],
"deviceTypes": [
"phone",
"desktop"
],
"firstSeen": "2019-08-30",
"lastSeen": "2025-01-06",
"networkLocationPostalCodes": [
"94062"
],
"networkLocationStates": [
"ca"
],
"seenCount": 30
}
}
],
"latestNavigationContexts": [
{
"backgroundCount": 0,
"combinedContext": "/#/sdk/consent?ref_id=6bd2183f-33d2-4981-a3a6-82bd97cc2bfe",
"estimatedStartTimestamp": "2025-01-14T15:24:24.881081805Z",
"ipAddresses": [
"99.153.72.238"
],
"submissionCount": 0,
"tabId": "70b9ec39-8b11-4727-9273-3bbc1edc09c1",
"timeInContext": 53111,
"timeInForeground": 53111
}
],
"velocityMetrics": {
"historicalCount": {
"email": {
"uniqueCount": 1,
"uniqueSharePercent": 100
},
"firstName": {
"uniqueCount": 0,
"uniqueSharePercent": 0
},
"mobileNumber": {
"uniqueCount": 1,
"uniqueSharePercent": 100
},
"surName": {
"uniqueCount": 0,
"uniqueSharePercent": 0
}
}
}
},
"documentData": {
"address": "463 Mertz Motorway, Port Spencer, OH 65036",
"dob": "1980-01-01",
"documentNumber": "11223344",
"expirationDate": "2030-01-01",
"firstName": "Jane",
"fullName": "Jane Doe",
"issueDate": "2015-01-01",
"parsedAddress": {
"city": "Port Spencer",
"country": "USA",
"physicalAddress": "463 Mertz Motorway",
"state": "OH",
"zip": "65036"
},
"surName": "Doe"
},
"documentType": {
"country": "USA",
"state": "NY",
"type": "Drivers License"
},
"reasonCodes": [
"I831",
"I836"
]
},
"referenceId": "85dab430-0cbd-4286-a745-f03be14e33e2"
},
"is_source_cache": false,
"total_attempts": 1
},
{
"enrichment_name": "Socure Image Request - Default Flow",
"enrichment_endpoint": "https://upload.socure.com/api/5.0/documents/{referenceId}",
"enrichment_provider": "SocureImageRequest",
"error_message": "zip: not a valid zip file",
"request": {
"referenceId": "85dab430-0cbd-4286-a745-f03be14e33e2"
},
"is_source_cache": false,
"total_attempts": 1
}
],
"eval_status": "evaluation_completed",
"environment_name": "Sandbox"
}Bottom of the funnel: Selfie Reverification
Example request
{
"id": "a86580cc-1733-4188-86b5-717166e1db8c",
"workflow": "trust_and_safety",
"timestamp": "2025-05-02T12:44:22.059Z",
"data": {
"event_type": "reverify",
"event_category": "workforce_verification",
"individual": {
"id": "09237776-f16b-4eec-9305-fc425843d887",
"given_name": "Franky",
"family_name": "Valley",
"email": "[email protected]",
"phone_number": "+14155550123",
"address": {
"line_1": "742 Evergreen Terrace",
"line_2": "Apt 2B",
"locality": "Springfield",
"major_admin_division": "IL",
"country": "US",
"postal_code": "62704"
},
"docv": {
"config": {
"send_message": true,
"transaction_token": "1e89eec0-f7a3-4210-b74b-a76bc9556c50"
}
},
"di_session_token": "test123"
}
}
}
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",
"workflow": "trust_and_safety",
"timestamp": "2025-05-02T12:44:22.059Z",
"data": {
"event_type": "reverify",
"event_category": "workforce_verification",
"individual": {
"id": "09237776-f16b-4eec-9305-fc425843d887",
"given_name": "Franky",
"family_name": "Valley",
"email": "[email protected]",
"phone_number": "+14155550123",
"address": {
"line_1": "742 Evergreen Terrace",
"line_2": "Apt 2B",
"locality": "Springfield",
"major_admin_division": "IL",
"country": "US",
"postal_code": "62704"
},
"docv": {
"config": {
"send_message": true,
"transaction_token": "1e89eec0-f7a3-4210-b74b-a76bc9556c50"
}
},
"di_session_token": "test123"
}
}
}'Example response
Sample response when Selfie Reverification is initiated:
{
"id": "a86580cc-1733-4188-86b5-717166e1db8c",
"workflow": "trust_and_safety",
"workflow_id": "e2c86213-d59c-4196-ae01-03e146b488d2",
"workflow_version": "4.53.0",
"eval_source": "API",
"eval_id": "006a0d5e-bcb7-4bae-b889-773e1f332808",
"eval_start_time": "2025-10-30T18:17:25.167651117Z",
"eval_end_time": "2025-10-30T18:17:25.629737544Z",
"decision": "REVIEW",
"decision_at": "2025-10-30T18:17:25.629750204Z",
"status": "ON_HOLD",
"sub_status": "",
"tags": [],
"notes": "",
"review_queues": [
"Default Queue"
],
"data_enrichments": [
{
"enrichment_name": "Socure Document Request - Selfie Reverification",
"enrichment_endpoint": "https://service.socure.com/api/5.0/documents/request",
"enrichment_provider": "SocureDocRequest",
"status_code": 200,
"request": {
"city": "Springfield",
"config": {
"sendMessage": true,
"useCaseKey": "selfie"
},
"country": "US",
"firstName": "Franky",
"mobileNumber": "+14155550123",
"physicalAddress": "742 Evergreen Terrace",
"physicalAddress2": "Apt 2B",
"state": "IL",
"surName": "Valley",
"zip": "62704"
},
"response": {
"data": {
"docvTransactionToken": "3880b1ef-f8bf-40b8-bd6a-2cbd796dc57a",
"eventId": "3880b1ef-f8bf-40b8-bd6a-2cbd796dc57a",
"qrCode": "data:image/png;base64, iVBORw0KGgoAAAANSUhEUgAAAZoA...",
"url": "https://verify.socure.com/#/dv/3880b1ef-f8bf-40b8-bd6a-2cbd796dc57a"
},
"referenceId": "676b667f-a255-478c-9ec1-330960abfe68"
},
"is_source_cache": false,
"total_attempts": 1
}
],
"eval_status": "evaluation_paused",
"environment_name": "Sandbox"
}Retrieve the evaluation results
Once Selfie Reverification is complete, you will receive an evaluation_completed webhook event. See webhook Event Subscription Types for more details.
Alternatively, you can also retrieve evaluation results from the Evaluation endpoint via a GET request.
{
"id": "a86580cc-1733-4188-86b5-717166e1db8c",
"workflow": "trust_and_safety",
"workflow_id": "e2c86213-d59c-4196-ae01-03e146b488d2",
"workflow_version": "4.53.0",
"eval_source": "API",
"eval_id": "91c3f067-ff65-45a7-891b-425e5b60c636",
"eval_start_time": "2025-10-30T18:18:44.231781216Z",
"eval_end_time": "2025-10-30T18:19:21.51605824Z",
"decision": "ACCEPT",
"decision_at": "2025-10-30T18:19:21.51596761Z",
"status": "CLOSED",
"sub_status": "Accept",
"tags": null,
"notes": "",
"review_queues": [
"Default Queue"
],
"data_enrichments": [
{
"enrichment_name": "Socure Document Request - Selfie Reverification",
"enrichment_endpoint": "https://service.socure.com/api/5.0/documents/request",
"enrichment_provider": "SocureDocRequest",
"status_code": 200,
"request": {
"city": "Springfield",
"config": {
"sendMessage": true,
"useCaseKey": "selfie"
},
"country": "US",
"firstName": "Franky",
"mobileNumber": "+19083004979",
"physicalAddress": "742 Evergreen Terrace",
"physicalAddress2": "Apt 2B",
"state": "IL",
"surName": "Valley",
"zip": "62704"
},
"response": {
"__third_party_name__": "Socure Document Request - Selfie Reverification",
"data": {
"docvTransactionToken": "fbc341f7-efc6-421e-90cf-fe25257cf193",
"eventId": "fbc341f7-efc6-421e-90cf-fe25257cf193",
"qrCode": "data:image/png;base64, iVBORw0KGgoAAAANSUhEUgAAAZo...",
"url": "https://verify.socure.com/#/dv/fbc341f7-efc6-421e-90cf-fe25257cf193"
},
"deviceSessionToken": "eyJraWQiOiJmMzRiN2YiLCJhbGciOiJIUzUxMiIs...",
"referenceId": "894813fa-1d0f-4050-92cf-4c014e0d1ed5",
"status": "SESSION_COMPLETE"
},
"is_source_cache": false,
"total_attempts": 1
},
{
"enrichment_name": "Socure Document Verification - Selfie Reverification",
"enrichment_endpoint": "https://sandbox.socure.com/api/3.0/EmailAuthScore",
"enrichment_provider": "Socure",
"status_code": 200,
"request": {
"city": "Springfield",
"country": "US",
"deviceSessionId": "test123",
"docvTransactionToken": "fbc341f7-efc6-421e-90cf-fe25257cf193",
"email": "[email protected]",
"firstName": "Franky",
"mobileNumber": "+19083004979",
"modules": [
"selfiereverification"
],
"parentTxnId": "91c3f067-ff65-45a7-891b-425e5b60c636",
"physicalAddress": "742 Evergreen Terrace",
"physicalAddress2": "Apt 2B",
"riskOSId": "a86580cc-1733-4188-86b5-717166e1db8c",
"state": "IL",
"surName": "Valley",
"userId": "09237776-f16b-4eec-9305-fc425843d887",
"workflow": "trust_and_safety",
"zip": "62704"
},
"response": {
"customerProfile": {
"userId": "09237776-f16b-4eec-9305-fc425843d887"
},
"referenceId": "69f29044-27d2-4390-8f9c-5b046298bb20",
"selfieReverification": {
"decision": {
"strategy": "standard",
"value": "accept"
},
"digitalIntelligence": {
"behavioral": {
"aggregations": {
"blurCount": 10,
"clickCount": 1,
"focusCount": 1,
"inputChangeCount": 1,
"pasteCount": 1,
"submissionCount": 1,
"totalEventCount": 10
},
"duration": 5050,
"serverCreated": "2025-01-14T00:10:50.942Z",
"serverUpdated": "2025-01-14T00:10:51.692Z",
"sessionId": "a1cf60e7-5915-4734-9130-223c8371f12a",
"source": "https://example.com/"
},
"device": {
"attributes": {
"androidAttributes": {},
"battery": {
"batteryLevel": 0.88,
"batteryState": "charging"
},
"deviceManufacturer": "Apple",
"deviceMemory": 8,
"deviceModel": "Apple Macintosh",
"devicePixelRatio": 1.1,
"deviceType": "Desktop",
"iOSAttributes": {},
"language": "en-US",
"location": {},
"os": "Mac OS",
"osVersion": "14.5.0",
"platform": "Web",
"screenHeight": 1080,
"screenWidth": 1920,
"sdkVersion": "2.5.0",
"timeZone": "America/Los_Angeles",
"timeZoneOffset": -480,
"viewportHeight": 668,
"viewportWidth": 598,
"webAttributes": {
"browser": "Chrome",
"browserVersion": "131.0.6778.205",
"userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/131.0.0.0 Safari/537.36",
"userAgentExtractionRequired": true
}
},
"computed": {
"isVirtualMachine": false,
"statisticalId": "e81a14d6621cfd2ed9390be9d9eba266851e391aa751881cda9f74377197980b"
},
"deviceCaptureAt": "2025-01-14T00:10:49.385195428Z",
"history": {
"daysSeen": [
"2025-01-08",
"2025-01-14"
],
"firstSeen": "2025-01-08T15:55:46.143356159Z",
"ips": [
"192.184.177.36",
"72.150.12.157"
],
"isps": [
"sonic.net llc",
"comcast cable communications inc."
],
"lastSeen": "2025-01-14T00:10:49.385195428Z",
"networkLocations": [
"houston, ca",
"redwood city, ca"
]
},
"id": "844da0ea-767a-48da-8cb5-5f2e179f43f4",
"network": {
"asn": 7922,
"asnName": "comcast cable communications llc",
"connectionIp": "72.150.12.157",
"domainName": "comcast.net",
"isConsumerPrivacy": false,
"isMobileCarrier": false,
"isProxy": false,
"isRiskyNetwork": false,
"isTor": false,
"isVpn": false,
"isp": "comcast cable communications inc.",
"ispType": "home",
"networkLocation": {
"city": "redwood city",
"continentCode": "NA",
"countryCode": "us",
"gmtOffset": "-800",
"latitude": 37.38,
"longitude": -122.23,
"metroCode": 807,
"postalCode": "94062",
"region": "ca",
"timezoneName": "america/los_angeles"
},
"org": "comcast cable communications inc.",
"realIp": "72.150.12.157",
"speed": "cable",
"webRtcInternalIp": "72.150.12.157",
"webRtcPublicIp": "72.150.12.157"
},
"sessionCreatedAt": "2025-01-14T00:10:49.377717442Z"
},
"entityProfiler": [
{
"entity": "[email protected]",
"entityType": "email",
"profile": {
"deviceIsps": [
"comcast cable communications inc."
],
"deviceLanguages": [
"en-us"
],
"deviceModels": [
"iphone",
"apple macintosh"
],
"deviceTimezones": [
"america/los_angeles"
],
"deviceTypes": [
"phone",
"desktop"
],
"firstSeen": "2019-08-30",
"lastSeen": "2025-01-06",
"networkLocationPostalCodes": [
"94062"
],
"networkLocationStates": [
"ca"
],
"seenCount": 30
}
},
{
"entity": "+14159999999",
"entityType": "phone",
"profile": {
"deviceIsps": [
"comcast cable communications inc."
],
"deviceLanguages": [
"en-us"
],
"deviceModels": [
"iphone",
"apple macintosh"
],
"deviceTimezones": [
"america/los_angeles"
],
"deviceTypes": [
"phone",
"desktop"
],
"firstSeen": "2019-08-30",
"lastSeen": "2025-01-06",
"networkLocationPostalCodes": [
"94062"
],
"networkLocationStates": [
"ca"
],
"seenCount": 30
}
},
{
"entity": "123123123",
"entityType": "nationalId",
"profile": {
"deviceIsps": [
"comcast cable communications inc."
],
"deviceLanguages": [
"en-us"
],
"deviceModels": [
"iphone",
"apple macintosh"
],
"deviceTimezones": [
"america/los_angeles"
],
"deviceTypes": [
"phone",
"desktop"
],
"firstSeen": "2019-08-30",
"lastSeen": "2025-01-06",
"networkLocationPostalCodes": [
"94062"
],
"networkLocationStates": [
"ca"
],
"seenCount": 30
}
}
],
"latestNavigationContexts": [
{
"backgroundCount": 0,
"combinedContext": "/#/sdk/consent?ref_id=6bd2183f-33d2-4981-a3a6-82bd97cc2bfe",
"estimatedStartTimestamp": "2025-01-14T15:24:24.881081805Z",
"ipAddresses": [
"99.153.72.238"
],
"submissionCount": 0,
"tabId": "70b9ec39-8b11-4727-9273-3bbc1edc09c1",
"timeInContext": 53111,
"timeInForeground": 53111
}
],
"velocityMetrics": {
"historicalCount": {
"email": {
"uniqueCount": 1,
"uniqueSharePercent": 100
},
"firstName": {
"uniqueCount": 0,
"uniqueSharePercent": 0
},
"mobileNumber": {
"uniqueCount": 1,
"uniqueSharePercent": 100
},
"surName": {
"uniqueCount": 0,
"uniqueSharePercent": 0
}
}
}
},
"previousReferenceId": "ff00dc2e-a696-4b3e-ad7f-3b46dff3671c",
"reasonCodes": [
"I834",
"I836"
]
}
},
"is_source_cache": false,
"total_attempts": 1
}
],
"eval_status": "evaluation_completed",
"environment_name": "Sandbox"
}API explorer
To make Sandbox calls in the API explorer:
- Complete RiskOS™ environment Setup guide.
- Go to the RiskOS™ Dashboard > Developer Workbench > API Keys page and collect your Sandbox API key.
- Paste your key into the API Key field.
- The explorer automatically adds the
Authorization: Bearerheader.
- The explorer automatically adds the
- Click Send Request to execute the call.
Note:
The Sandbox environment requires specific field values to return a properly formatted response. Modifying the input data may result in HTTP errors.
POST
https://riskos.sandbox.socure.com/api/evaluation
Request | Response
Request Body
API Response
Response will appear here.
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
Valid candidates →
ACCEPT
Fraudulent candidates →
REJECT or REVIEW
Edge cases logged + reviewed
Schema & error handling
Fields match schema across environments
Errors are structured and retryable
Use exponential fallback with jitter for retries
Logging & observability
Log full request/response
Include correlation IDs
Redact sensitive data from logs
Updated 6 days ago