Integrate Workforce Verification

For AI agents: visit https://help.socure.com/llms.txt for an index of all pages formatted in Markdown and endpoints in OpenAPI.

Before you start Skip link to 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 Skip link to Postman collection

The following Postman collection can be used to test the Workforce Verification solution with the Evaluation endpoint.

Choose your environment Skip link to Choose your environment

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

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

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

Get an API key Skip link to Get an API key

  1. In the Sandbox RiskOS™ Dashboard, go to Developer Workbench > API Keys.

  2. Copy your API key securely.

  3. In the Production RiskOS™ Dashboard, go to Developer Workbench > API Keys.

  4. Copy your API key securely

How it works Skip link to How it works

  1. Send a POST /api/evaluation request with candidate identity and device data.
  2. RiskOS™ evaluates the request using your Workforce Verification workflow.
  3. You receive a decision (ACCEPT, REVIEW, REJECT, or RESUBMIT).
  4. Apply the decision to proceed with onboarding, request additional verification, route to manual review, or halt the workflow.

📘

Note: The decision values 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 Skip link to 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 Skip link to Start a new evaluation

Endpoint Skip link to Endpoint

SandboxProduction

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

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

Authentication and headers Skip link to Authentication and headers

Include your API key in the Authorization header as a Bearer token, along with standard JSON headers:

HTTP

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
Accept: application/json
X-API-Version: 2025-01-01.orion   # optional – pins a specific API version

Top of the funnel Skip link to Top of the funnel

Example requests Skip link to Example requests

JSONcURL

{
  "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": "franky@test.com",
      "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": "franky@test.com",
        "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"
      }
    }
  }'

Education verification is an optional top-of-funnel enrichment for verifying degree credentials.

JSONcURL

Request schema Skip link to Request schema

Top-level fields Skip link to 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 Required RFC 3339 timestamp indicating when the evaluation request was initiated. "2025-05-02T12:44:22.059Z"
workflow String Required Workflow name configured in the RiskOS™ Dashboard.
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.		 "trust_and_safety"
data Object Required Main payload containing individual identity data and event context. See data schema below.

data fields Skip link to [object Object], fields

Field Type Required Description Example
event_type String Optional Event label for configuring different fraud checks in the workflow. Possible values are:
- passive: Template workflow runs passive checks only.

- reverify: Template workflow runs Selfie Reverification flow.

- (unset or any other value): Template workflow runs Predictive DocV verification flow.

Customers can customize the workflow based on their business risks and risk posture.		 "passive"
event_category String Optional High-level categorization of the verification event type. "workforce_verification"
individual Object Required Primary candidate identity information, including name, contact details, and verification tokens. See individual schema below.
custom Object Optional Use this field to send any additional, customer-specific data relevant to the Education verification workflow.

individual fields Skip link to [object Object], 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. "john.smith@gmail.com"
phone_number String Required Candidate’s phone number with country code. The API expects the standard E.164 format but tolerates hyphens and spaces for user convenience. "+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 Skip link to [object Object], 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 Skip link to [object Object], fields - Optional

Use 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 Skip link to 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.

Passive identity verificationEducation verification

{
  "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": "franky@test.com",\
        "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": "franky@test.com",\
        "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": "franky@test.com",\
        "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": "franky@test.com",\
        "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.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": "franky@test.com",\
        "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": "franky@test.com",\
        "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": "franky@test.com",\
        "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"
}

Key response fields Skip link to 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 Skip link to 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) Skip link to Decision and routing (primary control signals)

Use these fields to determine what action your application should take.

decision values 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
• REJECT
Note: 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 Skip link to 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 Skip link to 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 Skip link to 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 Skip link to 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) Skip link to Example ,[object Object], 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. "john.smith@gmail.com"
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) Skip link to Example ,[object Object], 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 Skip link to [object Object], 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  Skip link to Mid-Funnel: Document Verification 

Example request Skip link to Example request

JSONcURL

{
  "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": "franky@test.com",
      "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": "franky@test.com",
        "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 Skip link to Example response

Sample response when Document Verification is initiated:

JSON

{
    "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 Skip link to 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.

JSON

{
    "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": "john.smith@gmail.com",\
                "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,\
                                "deviceNetworkTimezoneOffsetDiffMinutes": 60,\
                                "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": "test123@tester.com",\
                                "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 Skip link to Bottom of the funnel: Selfie Reverification

Example request Skip link to Example request

JSONcURL

{
  "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": "franky@test.com",
      "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": "franky@test.com",
        "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 Skip link to Example response

Sample response when Selfie Reverification is initiated:

JSON

{
    "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 Skip link to 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.

JSON

{
    "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": "franky@test.com",\
                "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": "test123@tester.com",\
                                "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 Skip link to API explorer

To make Sandbox calls in the API explorer:

  1. Complete RiskOS™ environment Setup guide.
  2. Go to the RiskOS™ Dashboard > Developer Workbench > API Keys page and collect your Sandbox API key.
  3. Paste your key into the API Key field.
  1. 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.

Best practices for integration and maintenance Skip link to Best practices for integration and maintenance

Validation checklist Skip link to Validation checklist

Test coverage Skip link to Test coverage

Valid candidates → ACCEPT

Fraudulent candidates → REJECT or REVIEW

Edge cases logged + reviewed

Schema & error handling Skip link to Schema & error handling

Fields match schema across environments

Errors are structured and retryable

Use exponential fallback with jitter for retries

Logging & observability Skip link to Logging & observability

Log full request/response

Include correlation IDs

Redact sensitive data from logs

Updated about 13 hours ago

Did this page help you?

Yes

No

Copy Page