Response format

All RiskOS™ API responses follow a consistent JSON structure that makes integration predictable and debugging straightforward.

Core structure

Every response includes these elements:

Element	Type	Description
HTTP Status Code	Integer	Standard HTTP status indicating request outcome.
Response Body	JSON Object	Contains the actual response data and metadata.
Headers	Object	Additional metadata about the response.

Response body standards

JSON format details

Content-Type: Always application/json unless otherwise specified
Character Encoding: UTF-8
Timestamp Format: ISO 8601 UTC format (YYYY-MM-DDTHH:MM:SSZ)
Null Values: Explicitly included where relevant
Array Consistency: Empty arrays returned as [], never null

Success example response

When your request succeeds, RiskOS™ returns a 2xx status code with structured data.

200 OK - Request Completed

When you'll see this:

Evaluation completed successfully
Data retrieved without issues
Synchronous operations finished

What to expect:

Complete response data
Final decision and status
All enrichment results included

201 Created - Resource Created

When you'll see this:

New evaluation initiated
Asynchronous process started
Resource pending additional data

What to expect:

Partial response data
eval_status indicating ongoing process
May require additional API calls to complete

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

{
  "id": "BIZ-9876",
  "eval_id": "async-239s9-df29dj",
  "workflow": "business_onboarding",
  "eval_status": "evaluation_paused",
  "decision": "REVIEW",
  "status": "OPEN",
  "sub_status": "Pending Docs",
  "workflow_id": "4a2288ff-b3a8-4e69-89dd-069d5e2bcb44",
  "workflow_version": "3.7.0",
  "eval_source": "API",
  "eval_start_time": "2024-12-02T10:30:24.456771162Z",
  "data_enrichments": [
    {
      "enrichment_name": "Deliver OTP SMS",
      "enrichment_endpoint": "https://idplus.dev.socure.com/api/1.0/otp/send",
      "enrichment_provider": "SocureOTP",
      "status_code": 200,
      "request": {
        "channel": "email",
        "destination": "darshanvaishnav24@gmail.com"
      },
      "response": {
        "error": "",
        "verificationId": "5ac71c12-32df-4fb2-ab76-5493444f3f97"
      },
      "is_source_cache": false
    },
    {
      "enrichment_name": "Verify OTP SMS",
      "enrichment_endpoint": "https://idplus.dev.socure.com/api/1.0/otp/verify",
      "enrichment_provider": "SocureOTP",
      "status_code": 200,
      "request": {
        "otp": "508070",
        "verificationId": "5ac71c12-32df-4fb2-ab76-5493444f3f97"
      },
      "response": {
        "attemptCount": 1,
        "error": "",
        "status": "approved",
        "verificationId": "5ac71c12-32df-4fb2-ab76-5493444f3f97"
      },
      "is_source_cache": false
    },
    {
      "enrichment_name": "Socure Address risk",
      "enrichment_endpoint": "https://sandbox.dev.socure.com/api/3.0/EmailAuthScore",
      "enrichment_provider": "Socure",
      "status_code": 200,
      "request": {
        "city": "bakersfield",
        "country": "US",
        "deviceSessionId": "234ac3ff-3ed1-42de-8f33-8f332febfa54",
        "dob": "1990-05-17",
        "email": "johnsmith123+test@example.com",
        "modules": [
          "addressrisk"
        ],
        "nationalId": "454236793"
      },
      "response": {
        "addressRisk": {
          "reasonCodes": [
            "I704",
            "I705",
            "I708"
          ],
          "score": 0.01,
          "scores": [
            {
              "name": "addressrisk_cus1",
              "score": 0.01,
              "version": "10.0"
            },
            {
              "name": "address_risk_pri",
              "score": 0.01,
              "version": "9.0"
            }
          ]
        },
        "referenceId": "4ca693ee-af2a-45ef-9688-834683ac1b34"
      },
      "is_source_cache": false,
      "total_attempts": 1
    },
    {
      "enrichment_name": "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": "Alice Johnson",
        "callerType": "BUSINESS",
        "countryCode": "US",
        "phoneNumber": "+1-415-555-5678",
        "valid": true
      },
      "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 outputs that depend on your workflow configuration.

Where to find specific results

Area	Fields	How to use it
Decision and routing	`decision`, `decision_at`, `tags`, `review_queues`, `notes`, `score`	Primary control signals. Branch application logic using `decision`. Use tags, queues, notes, and score for secondary routing, review, and explanation.
Module results	Module-specific fields (for example: `reasonCodes`, scores, extracted attributes)	Evidence and signals produced by workflow modules. Use for escalation, compliance review, investigation, and audit.
Identifiers and traceability	`id`, `eval_id`	Persist these identifiers to correlate API calls, logs, webhooks, GET requests, and support cases.
Enrichment execution	`data_enrichments[]` (`response`, `status_code`, `total_attempts`, `is_source_cache`)	Inspect enrichment outputs and detect provisioning issues, partial failures, retries, or cached responses.
Workflow context	`workflow`, `workflow_id`, `workflow_version`	Understand which workflow ran and which version produced the result. Useful for debugging and historical analysis.
Evaluation lifecycle	`eval_status`, `status`, `sub_status`	Execution and case state only. Useful for monitoring and asynchronous workflows. Do not use for business decisions.
Execution context	`eval_source`, `eval_start_time`, `eval_end_time`, `environment_name`	Observability and performance metadata for latency tracking, environment validation, and API vs Dashboard attribution.

Decision and routing (primary control signals)

These fields describe the outcome of an evaluation and any routing applied by the workflow.

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` • `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.	`"2025-12-11T17:49:28.930Z"`
`score`	Number	If configured for a workflow, provides an aggregate score of all steps. This can be used for risk banding, additional routing, or analytics alongside the primary `decision` value.	`11`
`tags`	Array of Strings	Array of labels applied during the workflow to highlight routing choices, notable signals, or rule outcomes. Useful for reporting, segmentation, or UI highlighting in the RiskOS™ Dashboard.	`[]`
`review_queues`	Array of Strings	Lists any manual review queues the evaluation was sent to. Empty when the case is fully auto-resolved without human review.	`[]`
`notes`	String	Freeform text field for analyst or system comments about the evaluation. Often used to capture manual review rationale or investigation context.	`""`

Evaluation lifecycle and status

These fields describe where the evaluation is in its lifecycle and are useful for monitoring and asynchronous workflows.

Field	Type	Description	Example
`eval_status`	String (enum)	Internal RiskOS™ evaluation lifecycle state. Possible values: • `evaluation_completed` • `evaluation_paused` • `evaluation_in_progress`	`"evaluation_completed"`
`status`	String (enum)	Case-level status of the evaluation. Possible values: • `OPEN` • `CLOSED`	`"CLOSED"`
`sub_status`	String	Provides additional detail about the evaluation status. Example values: • `Under Review` • `Pending Verification` • `Accept` • `Reject`	`"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.	`"onb-12345"`
`eval_id`	String (UUID)	RiskOS-generated unique identifier for the evaluation.	`"6dc8f39c-ecc3-4fe0-9283-fc8e5f99e816"`
`workflow`	String	Name of the workflow executed.	`"consumer_onboarding"`
`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 the evaluation.

Field	Type	Description	Example
`eval_source`	String (enum)	Indicates where the evaluation was initiated from. Possible values: • `API`: Request submitted via the Evaluation API. • `Dashboard`: Case created or evaluated through the RiskOS™ Dashboard.	`"API"`
`eval_start_time`	String `<Date-Time>`	RFC 3339 timestamp for when RiskOS™ started processing the evaluation. Useful for latency and performance monitoring.	`"2024-12-02T10:28:24.456771162Z"`
`eval_end_time`	String `<Date-Time>`	RFC 3339 timestamp for when RiskOS™ finished processing the evaluation. Can be paired with `eval_start_time` to compute total processing time.	`"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. Each object corresponds to a module executed as part of the Consumer Onboarding workflow.

Field	Type	Description	Example
`enrichment_name`	String	Name of the enrichment executed.	`"Socure Address risk"`
`enrichment_provider`	String	Provider of the enrichment.	`"Socure"`
`status_code`	Integer	HTTP status returned by the enrichment call.	`200`
`request`	Object	Provider request payload (for observability and debugging).
`response`	Object	Normalized enrichment response.
`is_source_cache`	Boolean	Indicates whether cached data was used.	`false`
`total_attempts`	Integer	Number of attempts made to retrieve the data.	`1`

Error responses

When something goes wrong, RiskOS™ provides detailed error information to help you debug and resolve issues quickly. See Errors for more information.