Integration Guide

Login and Authentication API integration guide

This guide walks you through how to integrate with Socure’s /api/evaluation endpoint using the Login and Authentication workflow. You’ll learn how to send login data, parse the response, and apply decision logic to protect against account takeover, support trusted authentication, and strengthen fraud prevention.

Before you start

Make sure your RiskOS™ environment is provisioned with:

A workflow configured for the Login and Authentication solution.

Verified global support coverage for the Login and Authentication solution.

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/evaluation request with login event, identity, and device data.
RiskOS™ evaluates the request using your Login and Authentication workflow.
You receive a decision (APPROVE, REVIEW, or REJECT).
Apply the decision to allow access, require step-up verification, or block the login attempt.

📘
Note: The decision values shown in this guide (APPROVE, REVIEW, REJECT) reflect a customized Login and Authentication workflow.
Your environment may use different default decision values depending on how your workflow is configured.

Start a new evaluation

Endpoint

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

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

Authentication 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 version

Example request: application/json required

{
  "id": "ato-78901",
  "timestamp": "2023-12-01T15:45:12.678Z",
  "workflow": "account_takeover",
  "data": {
    "event_type": "address_update",
    "event_category": "update",
    "ip_address": "203.0.113.10",
    "individual": {
      "id": "ind-9876543",
      "given_name": "Jane",
      "family_name": "Smith",
      "national_id": "123456789",
      "date_of_birth": "1990-05-15",
      "email": "[email protected]",
      "phone_number": "+1-312-555-1234",
      "address": {
        "line_1": "742 Evergreen Terrace",
        "line_2": "Apt 12B",
        "locality": "Springfield",
        "major_admin_division": "IL",
        "country": "US",
        "postal_code": "62704"
      },
      "di_session_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzUxMiJ...PiUsws9D6O3DjSjNDCbIJKciX44s"
    },
    "event_details": {
      "previous": {
        "address": {
          "line_1": "123 Main Street",
          "line_2": "Suite 100",
          "locality": "Brooklyn",
          "major_admin_division": "NY",
          "country": "US",
          "postal_code": "11201"
        }
      }
    },
    "custom": {}
  }
}

curl --location '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": "ato-78901",
  "timestamp": "2023-12-01T15:45:12.678Z",
  "workflow": "account_takeover",
  "data": {
    "event_type": "address_update",
    "event_category": "update",
    "ip_address": "203.0.113.10",
    "individual": {
      "id": "ind-9876543",
      "given_name": "Jane",
      "family_name": "Smith",
      "national_id": "123456789",
      "date_of_birth": "1990-05-15",
      "email": "[email protected]",
      "phone_number": "+1-312-555-1234",
      "address": {
        "line_1": "742 Evergreen Terrace",
        "line_2": "Apt 12B",
        "locality": "Springfield",
        "major_admin_division": "IL",
        "country": "US",
        "postal_code": "62704"
      },
      "di_session_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzUxMiJ...PiUsws9D6O3DjSjNDCbIJKciX44s"
    },
    "event_details": {
      "previous": {
        "address": {
          "line_1": "123 Main Street",
          "line_2": "Suite 100",
          "locality": "Brooklyn",
          "major_admin_division": "NY",
          "country": "US",
          "postal_code": "11201"
        }
      }
    },
    "custom": {}
  }
}'

Request schema

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.	`"ato-78901"`
`timestamp`	String `<Date-Time>`	Required	RFC 3339 timestamp indicating when the evaluation request was initiated by your system.	`"2023-12-01T15:45:12.678Z"`
`workflow`	String	Required	Workflow name configured in the RiskOS™ Dashboard. Use `"account_takeover"` for ATO evaluations.	`"account_takeover"`
`data`	Object	Required	Main payload containing consumer information, device data, and event details for evaluation.	See `data` fields below.

`data` fields

Field	Type	Required	Description	Example
`event_category`	String	Optional	Category of the event occurring on the consumer account. Helps contextualize the risk assessment. Possible values: `Authenticate`, `Action`, `Information`, `Update`.	`"Update"`
`event_type`	String	Required	Specific type of event being evaluated (e.g., login attempt, profile change, payment method update).	`"address_update"`
`ip_address`	String	Optional	Consumer's IP address in IPv4 decimal or IPv6 hexadecimal format. Used for geolocation and risk analysis.	`"203.0.113.10"`
`individual`	Object	Optional (Recommended)	Core identity information for the primary consumer being evaluated. Include as many fields as possible for optimal risk assessment.	See `individual` fields below.
`external_device`	Object	Optional	Third-party device intelligence data when not using Socure's Digital Intelligence solution.	See `external_device` fields below.
`event_details`	Object	Optional	Additional context about the specific event, including previous values for comparison.	See example request.
`custom`	Object	Optional	Custom data fields specific to your business logic and risk models.

`individual` fields

Field	Type	Required	Description	Example
`id`	String	Optional (Recommended)	Maps to the `userId` in enrichments or a customer’s internal identifier. Can be enabled as a searchable field in RiskOS™ Dashboard.	`"ind-9876543"`
`given_name`	String (≤ 240)	Optional (Recommended)	Consumer's given name (first name). Used for identity verification and name matching.	`"Jane"`
`family_name`	String (≤ 240)	Optional (Recommended)	Consumer's family name (last name). Combined with first name for comprehensive identity verification.	`"Smith"`
`national_id`	String	Optional (Recommended)	SSN/ITIN or national ID. Provide last-4 (US) or full ID where applicable.	`"1234"` (last 4) or `"123456789"` (full)
`date_of_birth`	String	Optional (Recommended)	Date of birth in `YYYY-MM-DD` format. Critical for age verification and identity matching.	`"1990-05-15"`
`email`	String	Optional	Consumer's email address. Used for email risk scoring and velocity analysis.	`"[email protected]"`
`phone_number`	String (E.164)	Optional (Recommended)	Consumer's phone number in E.164 international format. Enables phone intelligence and verification.	`"+13475550100"`
`di_session_token`	String	Optional	UUID from Digital Intelligence SDK.	`"eyJ0eXAiOiJKV` 1QiLCJhbGciOi..."`
`ip_address`	String	Optional	Consumer's IP address. Can be specified here or at the `data` level.	`"203.0.113.10"`
`address`	Object	Optional (Recommended)	Consumer's physical address information. Used for address verification and geolocation analysis.	See `address` fields below.

`address` fields

Field	Type	Required	Description	Example
`line_1`	String	Optional (Recommended)	Primary address line including street number and name.	`"742 Evergreen Terrace"`
`line_2`	String	Optional	Secondary address line for apartment, suite, or unit number.	`"Apt 12B"`
`locality`	String	Optional (Recommended)	City or locality name.	`"Springfield"`
`major_admin_division`	String	Optional (Recommended)	State, province, or major administrative division (use standard abbreviations).	`"IL"`
`country`	String	Optional (Recommended)	Country code in ISO 3166-1 alpha-2 format.	`"US"`
`postal_code`	String	Optional (Recommended)	ZIP code, postal code, or equivalent for the address.	`"62704"`

`external_device` - 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

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 Login and Authentication workflow.

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

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.

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: • `APPROVE` • `REVIEW` • `REJECT` Note: The fields returned can be customized to fit your integration or business needs.	`"REJECT"`
`decision_at`	String `<Date-Time>`	RFC 3339 timestamp when the decision was finalized.	`"2024-12-02T10:29:10.999Z"`
`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.	`-76`
`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.	`["account ta", "high risk"]`
`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)	Indicates the current state of an evaluation in RiskOS™. Possible values: • `evaluation_completed` • `evaluation_paused` • `evaluation_in_progress`	`"evaluation_completed"`
`status`	String (enum)	Case-level status of the evaluation. Possible values: • `OPEN` • `CLOSED`	`"CLOSED"`
`sub_status`	String	Provides additional detail about the evaluation status. Example values: • `Under Review` • `Pending Verification` • `Accept` • `Reject`	`"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.	`"ato-78901"`
`eval_id`	String (UUID)	RiskOS™-generated unique identifier for the evaluation.	`"6dc8f39c-ecc3-4fe0-9283-fc8e5f99e816"`
`workflow`	String	Name of the workflow executed.	`"account_takeover"`
`workflow_id`	String (UUID)	Unique identifier for the workflow run.	`"472288ff-b3a8-4e69-89dd-069d5e2bcb41"`
`workflow_version`	String	Version of the executed workflow.	`"3.7.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.	`"2024-12-02T10:28:24.456771162Z"`
`eval_end_time`	String `<Date-Time>`	RFC 3339 timestamp when processing finished.	`"2024-12-02T10:29:10.999Z"`
`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.	`"SocureCNam"`
`enrichment_endpoint`	String	Endpoint that processed the enrichment.	`"https://.../api/2.0/cnam"`
`enrichment_provider`	String	Provider name (Socure / vendor / internal service identifier).	`"SocureCNam"`
`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 service.	See `response` schema below.
`is_source_cache`	Boolean	`true` if cached data was used instead of a live call.	`false`
`total_attempts`	Integer	Number of attempts made to retrieve enrichment data.	`1`

Example `request` fields (varies by enrichment)

Field	Type	Description	Example
`phoneNumber`	String	Phone number submitted for verification or lookup	`"+1-312-555-1234"`
`modules`	Array of Strings	Specific data modules or services requested	`["digitalintelligence"]`
`deviceSessionId`	String (UUID)	Session identifier for device intelligence requests	`"7b3c2c04-0e7e-46e4-afe8-b905cdf91833"`
`customerUserId`	String	Your internal user identifier for the request	`"129"`
`userId`	String	Normalized user identifier for enrichment processing	`"dwanyedever1975"`

Example `response` fields (varies by enrichment)

For phone verification services:

Field	Type	Description	Example
`referenceId`	String (UUID)	Unique identifier assigned to each enrichment after a RiskOS™ workflow is finalized.	`"7b3c2c04-0e7e-46e4-afe8-b905cdf91833"`
`callerName`	String	Name associated with the phone number.	`"Jane Smith"`
`callerType`	String	Type classification of the phone number owner.	`"CONSUMER"`
`countryCode`	String	ISO 3166-1 alpha-2 country code for the phone number.	`"US"`
`phoneNumber`	String	Phone number in E.164 format as processed.	`"+1-312-555-1234"`
`valid`	Boolean	Indicates whether the phone number is valid and reachable.	`true`

For Digital Intelligence services

Field	Type	Description
`digitalIntelligence`	Object	Complete device intelligence data including device, network, behavioral, and profiling information.
`device`	Object	Device hardware, software, and configuration details.
`network`	Object	Network and IP address intelligence including geolocation and risk indicators.
`behavioral`	Object	User behavioral patterns and session interaction data.
`entityProfiler`	Array of objects	Historical profiles for phone numbers, emails, and other identifiers.
`velocityMetrics`	Object	Velocity and frequency analysis for submitted data elements.

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: Bearer header.
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.

Request | Response

API Key *

Request Body

{
  "id": "ato-78901",
  "timestamp": "2023-12-01T15:45:12.678Z",
  "workflow": "account_takeover",
  "data": {
    "event_type": "address_update",
    "event_category": "update",
    "ip_address": "203.0.113.10",
    "individual": {
      "id": "ind-9876543",
      "given_name": "Jane",
      "family_name": "Smith",
      "national_id": "123456789",
      "date_of_birth": "1990-05-15",
      "email": "jane.smith@example.com",
      "phone_number": "+1-312-555-1234",
      "address": {
        "line_1": "742 Evergreen Terrace",
        "line_2": "Apt 12B",
        "locality": "Springfield",
        "major_admin_division": "IL",
        "country": "US",
        "postal_code": "62704"
      },
      "di_session_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzUxMiJ...PiUsws9D6O3DjSjNDCbIJKciX44s"
    },
    "event_details": {
      "previous": {
        "address": {
          "line_1": "123 Main Street",
          "line_2": "Suite 100",
          "locality": "Brooklyn",
          "major_admin_division": "NY",
          "country": "US",
          "postal_code": "11201"
        }
      }
    },
    "custom": {}
  }
}

API Response

Response will appear here.

Best practices for integration and maintenance

Validate request payloads against the schema before sending.
Use sandbox test identities for QA and automation.
Monitor decision, tags, and review_queues for routing and escalation.
Capture and persist eval_id and referenceId for traceability.

Validation checklist

Test coverage

Accepted logins → APPROVE

Fraudulent attempts → REJECT or REVIEW

Edge cases logged + reviewed

Schema + error handling

Fields match schema across environments

Errors are structured, descriptive, and retryable

Use exponential backoff with jitter for retries

Logging + observability

Log full request/response including eval_id

Include correlation IDs for traceability

Redact sensitive data (e.g., nationalId, SSN, secrets) from logs

Login and Authentication API integration guide

Before you start

Choose your environment

Get an API key

How it works

Start a new evaluation

Endpoint

Authentication and headers

Example request: application/json required

Request schema

Top-level fields

data fields

individual fields

address fields

external_device - Optional

Example response

Key response fields

Where to find specific results

Decision and routing (primary control signals)

Evaluation lifecycle and status

Identifiers and traceability

Execution context

Enrichment results

Example request fields (varies by enrichment)

Example response fields (varies by enrichment)

API explorer

API Key *

Request Body

API Response

Best practices for integration and maintenance

Validation checklist

Test coverage

Schema + error handling

Logging + observability

`data` fields

`individual` fields

`address` fields

`external_device` - Optional

Example `request` fields (varies by enrichment)

Example `response` fields (varies by enrichment)