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

## Response format standards   [Skip link to Response format standards](https://help.socure.com/riskos/reference/api-responses\#response-format-standards)

| Field | Value |
| --- | --- |
| **Encoding** | UTF-8 |
| **Format** | JSON |
| **Timestamps** | ISO 8601 (UTC) — `YYYY-MM-DDTHH:MM:SS.fffZ` |
| **Arrays** | Empty arrays are always represented as `[]` (never `null`) |

## HTTP status codes   [Skip link to HTTP status codes](https://help.socure.com/riskos/reference/api-responses\#http-status-codes)

### Success   [Skip link to Success](https://help.socure.com/riskos/reference/api-responses\#success)

| Status | Meaning | When it occurs |
| --- | --- | --- |
| `200` | OK | Synchronous evaluation completed. The response contains a final `decision` and all enrichment results. |
| `201` | Created | Evaluation started but paused for asynchronous input (for example, OTP verification or document upload). Poll with `GET /api/evaluation/{eval_id}` or subscribe to webhooks for the `Evaluation Completed` event. |

### Errors   [Skip link to Errors](https://help.socure.com/riskos/reference/api-responses\#errors)

| Status | Meaning | When it occurs |
| --- | --- | --- |
| `400` | Bad request | Invalid JSON, missing required fields, or invalid field values. |
| `401` | Unauthorized | Missing or invalid API key. |
| `403` | Forbidden | Valid API key, but the request is blocked by an IP filter or insufficient permissions. |
| `404` | Not found | The endpoint or resource does not exist. |
| `415` | Unsupported media type | The `Content-Type` header is not `application/json`. |
| `422` | Unprocessable entity | Valid JSON, but the values are semantically invalid. |
| `429` | Too many requests | Rate limit exceeded. Retry after the interval specified in the response headers. |
| `500` | Internal server error | An unexpected error occurred on the RiskOS™ server. |
| `502` | Bad gateway | An upstream dependency failed. Retryable. |
| `503` | Service unavailable | RiskOS™ is temporarily unavailable. Retryable. |
| `504` | Gateway timeout | An upstream dependency timed out. Retryable. |

See [Errors](https://help.socure.com/riskos/reference/errors) for the complete error response schema, error codes, and retry guidance.

## Evaluation response   [Skip link to Evaluation response](https://help.socure.com/riskos/reference/api-responses\#evaluation-response)

Every evaluation endpoint (`POST /api/evaluation`, `GET /api/evaluation/{eval_id}`, `PATCH /api/evaluation/{eval_id}`) returns the same JSON structure.

### Where to find what you need   [Skip link to Where to find what you need](https://help.socure.com/riskos/reference/api-responses\#where-to-find-what-you-need)

| If you need to... | Use these fields |
| --- | --- |
| Route application logic based on the outcome | `decision`, `score`, `tags` |
| Send a case to manual review | `review_queues`, `notes` |
| Correlate logs, webhooks, and support requests | `id`, `eval_id` |
| Identify which workflow version produced the result | `workflow`, `workflow_id`, `workflow_version` |
| Inspect enrichment outputs (risk scores, OTP status, device data) | `data_enrichments[]` |
| Track async evaluation progress | `eval_status`, `status`, `sub_status` |
| Measure latency and confirm environment | `eval_start_time`, `eval_end_time`, `environment_name` |

### Decision and routing   [Skip link to Decision and routing](https://help.socure.com/riskos/reference/api-responses\#decision-and-routing)

These are the primary control signals. Branch your application logic on `decision`.

| Field | Type | Description | Example |
| --- | --- | --- | --- |
| `decision` | String | Final evaluation outcome. Default values: `ACCEPT`, `REVIEW`, `REJECT`. Your workflow may define custom decision values. | `"REJECT"` |
| `decision_at` | String (date-time) | RFC 3339 UTC timestamp when the decision was finalized. | `"2025-12-11T17:49:28.930Z"` |
| `score` | Integer | Aggregate risk score across all workflow steps. Present when scoring is configured for the workflow. Use for risk banding, routing, or analytics alongside `decision`. | `91` |
| `tags` | Array of strings | Labels applied during workflow execution — routing choices, notable signals, or rule outcomes. Useful for reporting, segmentation, or UI highlighting in the RiskOS™ Dashboard. | `["High Risk", "Bad Device"]` |
| `review_queues` | Array of strings | Manual review queues the evaluation was assigned to. Empty when the case was auto-resolved. | `["Default Queue"]` |
| `notes` | String | Freeform text for analyst or system comments. Often captures manual review rationale or investigation context. | `""` |

> 📘
>
> **Note**:
>
> `decision` values are workflow-specific and may differ from the defaults shown here. Contact Socure to configure custom decision values for your integration.

### Identifiers and traceability   [Skip link to Identifiers and traceability](https://help.socure.com/riskos/reference/api-responses\#identifiers-and-traceability)

Persist these fields to correlate API calls, logs, webhooks, and support cases.

| Field | Type | Description | Example |
| --- | --- | --- | --- |
| `id` | String | Your customer-defined identifier, echoed back from the request. | `"onb-12345"` |
| `eval_id` | String (UUID) | RiskOS™-generated unique identifier for this evaluation. Use this for `GET` and `PATCH` operations. | `"6dc8f39c-ecc3-4fe0-9283-fc8e5f99e816"` |
| `workflow` | String | Name of the workflow that was executed. | `"consumer_onboarding"` |
| `workflow_id` | String (UUID) | Unique identifier of the workflow definition. | `"472288ff-b3a8-4e69-89dd-069d5e2bcb41"` |
| `workflow_version` | String | Version of the executed workflow. | `"3.7.0"` |

### Evaluation lifecycle   [Skip link to Evaluation lifecycle](https://help.socure.com/riskos/reference/api-responses\#evaluation-lifecycle)

Use these fields for monitoring and async workflow tracking.

> 📘
>
> **Important**:
>
> Do not branch business logic on `eval_status` or `status`. Use `decision` for routing decisions.

| Field | Type | Description | Example |
| --- | --- | --- | --- |
| `eval_status` | String | Evaluation lifecycle state. Values: `evaluation_completed`, `evaluation_paused`, `evaluation_in_progress`. | `"evaluation_completed"` |
| `status` | String | Case-level status. Values: `OPEN`, `ON_HOLD`, `CLOSED`. | `"CLOSED"` |
| `sub_status` | String | Additional status detail. Values vary by workflow (for example, `Under Review`, `Pending Verification`, `Accept`, `Reject`). | `"Reject"` |

### Execution context   [Skip link to Execution context](https://help.socure.com/riskos/reference/api-responses\#execution-context)

Observability metadata for latency tracking, environment validation, and source attribution.

| Field | Type | Description | Example |
| --- | --- | --- | --- |
| `eval_source` | String | Where the evaluation was initiated. Values: `API`, `Dashboard`. | `"API"` |
| `eval_start_time` | String (date-time) | RFC 3339 UTC timestamp when processing started. | `"2025-01-15T10:28:24.456Z"` |
| `eval_end_time` | String (date-time) | RFC 3339 UTC timestamp when processing finished. Pair with `eval_start_time` to compute total latency. | `"2025-01-15T10:29:10.999Z"` |
| `environment_name` | String | Environment the evaluation ran in. Values: `Sandbox`, `Production`. | `"Sandbox"` |

### Extended fields   [Skip link to Extended fields](https://help.socure.com/riskos/reference/api-responses\#extended-fields)

These fields appear under specific conditions.

| Field | Type | Condition | Description |
| --- | --- | --- | --- |
| `input` | Object | Returned when `include_input=true` is set in the request query string. | Original input data. Contains `data` (as submitted) and `updated_data` (after workflow transformations). |
| `computed` | Object | Disabled by default. Contact Socure to enable. | Derived and aggregated results computed during workflow execution. |
| `aggregations` | Object | Disabled by default. Contact Socure to enable. | Historical aggregation data across prior evaluations for this identity. |
| `group_id` | String | Present when evaluations are linked. | Identifier linking related evaluations in a group. |
| `redirect_uri` | String | Present for Hosted UX (Capture App) workflows. | URL to redirect the end user to the Socure-hosted capture experience. |

## Enrichment results   [Skip link to Enrichment results](https://help.socure.com/riskos/reference/api-responses\#enrichment-results)

The `data_enrichments` array contains one object per enrichment module executed in the workflow. The array order matches the execution sequence.

### Enrichment object fields   [Skip link to Enrichment object fields](https://help.socure.com/riskos/reference/api-responses\#enrichment-object-fields)

| Field | Type | Description |
| --- | --- | --- |
| `enrichment_name` | String | Name of the enrichment module (for example, `"Socure Email Risk"`, `"Deliver OTP SMS"`). |
| `enrichment_provider` | String | Provider that executed the enrichment (for example, `"Socure"`, `"SocureOTP"`, `"SocureCNam"`). |
| `enrichment_endpoint` | String | API endpoint called for this enrichment. |
| `status_code` | Integer | HTTP status code returned by the enrichment provider. |
| `request` | Object | Payload sent to the provider. Useful for debugging integration issues. |
| `response` | Object | Normalized response from the provider. Socure enrichments always include a `referenceId`. |
| `is_source_cache` | Boolean | `true` if the response was served from cache instead of a live provider call. |
| `total_attempts` | Number | Total API call attempts, including retries. |
| `error_message` | String | Error details if the enrichment call failed. Empty on success. |

### Provider response shapes   [Skip link to Provider response shapes](https://help.socure.com/riskos/reference/api-responses\#provider-response-shapes)

The `response` object structure varies by enrichment provider. Expand each section for the schema and field descriptions.

Risk score enrichments (Address, Email, Phone)

Risk score enrichments return a consistent structure. The top-level key matches the module name: `addressRisk`, `emailRisk`, or `phoneRisk`.

JSON

```json
{
  "referenceId": "4ca693ee-af2a-45ef-9688-834683ac1b34",
  "addressRisk": {
    "reasonCodes": ["I704", "I705", "I708"],
    "score": 0.01,
    "scores": [\
      {\
        "name": "addressrisk_cus1",\
        "score": 0.01,\
        "version": "10.0"\
      }\
    ]
  }
}
```

| Field | Type | Description |
| --- | --- | --- |
| `referenceId` | String (UUID) | Unique identifier for this enrichment result. |
| `{module}.reasonCodes` | Array of strings | Reason codes that explain the score. |
| `{module}.score` | Number | Primary risk score for this module. |
| `{module}.scores` | Array of objects | Score model variants, each with `name`, `score`, and `version`. |

OTP enrichments (Deliver and Verify)

OTP enrichments handle one-time password delivery and verification across two separate steps.

**Deliver OTP response:**

JSON

```json
{
  "verificationId": "5ac71c12-32df-4fb2-ab76-5493444f3f97",
  "error": ""
}
```

**Verify OTP response:**

JSON

```json
{
  "verificationId": "5ac71c12-32df-4fb2-ab76-5493444f3f97",
  "status": "approved",
  "attemptCount": 1,
  "error": ""
}
```

| Field | Type | Present in | Description |
| --- | --- | --- | --- |
| `verificationId` | String (UUID) | Deliver, Verify | Identifier linking the delivery and verification steps. |
| `status` | String | Verify only | Verification result (for example, `"approved"`). |
| `attemptCount` | Integer | Verify only | Number of OTP entry attempts. |
| `error` | String | Deliver, Verify | Error message if the operation failed. Empty on success. |

CNAM enrichment

CNAM (Caller Name) enrichments return phone number ownership data.

JSON

```json
{
  "callerName": "Jane Smith",
  "callerType": "CONSUMER",
  "countryCode": "US",
  "phoneNumber": "+13125551234",
  "valid": true
}
```

| Field | Type | Description |
| --- | --- | --- |
| `callerName` | String | Registered name associated with the phone number. |
| `callerType` | String | Owner type (for example, `"CONSUMER"`, `"BUSINESS"`). |
| `countryCode` | String | Two-letter ISO country code. |
| `phoneNumber` | String | The queried phone number in E.164 format. |
| `valid` | Boolean | Whether the phone number is valid and active. |

Digital Intelligence enrichment

Digital Intelligence returns device fingerprinting, network analysis, behavioral data, and entity profiling. This is the largest enrichment response.

JSON

```json
{
  "referenceId": "7b3c2c04-0e7e-46e4-afe8-b905cdf91833",
  "digitalIntelligence": {
    "device": {
      "id": "234ac3ff-3ed1-42de-8f33-8f332febfa54",
      "globalDeviceId": "aecddd42-f223-3333-940c-87baab4c6645",
      "sessionCreatedAt": "2025-01-15T18:06:52.248Z",
      "deviceCapturedAt": "2025-01-15T18:09:12.735Z",
      "computed": {
        "statisticalId": "9349d69fef75cd356744293487462f8cd912",
        "isVirtualMachine": false,
        "isTamperedAndroidBuild": true,
        "sessionAgeMinutes": 45,
        "deviceNetworkTimezoneOffsetDiffMinutes": 60
      },
      "network": {
        "connectionIp": "38.48.122.126",
        "realIp": "38.48.122.126",
        "isTor": true,
        "isProxy": true,
        "isVpn": true,
        "isp": "comcast",
        "networkLocation": {
          "countryCode": "US",
          "region": "WA",
          "city": "Tacoma",
          "postalCode": "98401"
        }
      },
      "attributes": {
        "platform": "iOS",
        "os": "iOS",
        "osVersion": 17,
        "deviceModel": "iphone14,7",
        "deviceType": "phone",
        "isEmulator": true
      },
      "history": {
        "firstSeen": "2023-10-24T15:55:16.368Z",
        "lastSeen": "2025-01-15T18:09:12.735Z",
        "daysSeen": ["2023-10-24", "2025-01-15"]
      }
    },
    "behavioral": {
      "sessionId": "d34304a6-a726-4dec-b1cd-9c4a3c192a0d",
      "duration": 120910,
      "aggregations": {
        "totalEventCount": 26,
        "inputChangeCount": 6,
        "pasteCount": 0,
        "clickCount": 3,
        "submissionCount": 1
      }
    },
    "entityProfiler": [\
      {\
        "entity": "12223334444",\
        "entityType": "phone",\
        "profile": {\
          "seenCount": 2,\
          "firstSeen": "2024-08-24T14:15:22Z",\
          "lastSeen": "2025-01-15T18:09:12Z",\
          "deviceTypes": ["phone", "tablet"],\
          "networkLocationStates": ["ca", "az"]\
        }\
      }\
    ],
    "velocityMetrics": {
      "historicalCount": {
        "email": {
          "uniqueCount": 2,
          "uniqueSharePercent": 87
        },
        "mobileNumber": {
          "uniqueCount": 1,
          "uniqueSharePercent": 100
        }
      }
    }
  },
  "customerProfile": {
    "customerUserId": "129",
    "userId": "u8JpWn4QsF3R7tA2"
  }
}
```

**Key sections:**

| Section | Description |
| --- | --- |
| `device.computed` | Derived signals: `isVirtualMachine`, `isTamperedAndroidBuild`, `sessionAgeMinutes`, `statisticalId`, timezone offset differences. |
| `device.network` | Network analysis: IP addresses, VPN/proxy/Tor detection, ISP details, geolocation (`networkLocation`). |
| `device.attributes` | Device metadata: platform, OS version, device model, screen dimensions, battery state, timezone, language, emulator detection. Platform-specific data in `androidAttributes`, `iOSAttributes`, or `webAttributes`. |
| `device.history` | Historical device activity: first and last seen dates, IP history, ISP history, location history. |
| `behavioral` | Session behavior: event counts (clicks, pastes, form input changes, submissions), session duration, source URL. |
| `entityProfiler` | Cross-device entity profiles by phone, email, or national ID — historical device types, ISPs, timezones, and locations associated with each entity. |
| `velocityMetrics` | Velocity checks on PII fields: unique count and share percentage for first name, surname, email, and phone number. |

## Example responses   [Skip link to Example responses](https://help.socure.com/riskos/reference/api-responses\#example-responses)

### Completed evaluation (200 OK)   [Skip link to Completed evaluation (200 OK)](https://help.socure.com/riskos/reference/api-responses\#completed-evaluation-200-ok)

A synchronous evaluation that ran to completion with a final decision and enrichment results.

JSON

```json
{
  "id": "onb-12345",
  "eval_id": "6dc8f39c-ecc3-4fe0-9283-fc8e5f99e816",
  "workflow": "consumer_onboarding",
  "workflow_id": "472288ff-b3a8-4e69-89dd-069d5e2bcb41",
  "workflow_version": "3.7.0",
  "eval_status": "evaluation_completed",
  "decision": "REJECT",
  "decision_at": "2025-01-15T10:29:10.999Z",
  "score": 146,
  "status": "CLOSED",
  "sub_status": "Reject",
  "eval_source": "API",
  "eval_start_time": "2025-01-15T10:28:24.456Z",
  "eval_end_time": "2025-01-15T10:29:10.999Z",
  "tags": ["High Risk", "Bad Device"],
  "notes": "",
  "review_queues": [],
  "data_enrichments": [\
    {\
      "enrichment_name": "Socure Email Risk",\
      "enrichment_provider": "Socure",\
      "enrichment_endpoint": "https://sandbox.socure.com/api/3.0/EmailAuthScore",\
      "status_code": 200,\
      "request": {\
        "modules": ["emailrisk"],\
        "email": "jsmith@example.com"\
      },\
      "response": {\
        "referenceId": "92201637-1ec8-46b4-9537-236971eb6f9b",\
        "emailRisk": {\
          "reasonCodes": ["I520", "I555"],\
          "score": 0.01,\
          "scores": [\
            {\
              "name": "email_risk_cus1",\
              "score": 0.01,\
              "version": "10.0"\
            }\
          ]\
        }\
      },\
      "is_source_cache": false,\
      "total_attempts": 1,\
      "error_message": ""\
    },\
    {\
      "enrichment_name": "Socure Address risk",\
      "enrichment_provider": "Socure",\
      "enrichment_endpoint": "https://sandbox.socure.com/api/3.0/EmailAuthScore",\
      "status_code": 200,\
      "request": {\
        "modules": ["addressrisk"],\
        "city": "bakersfield",\
        "country": "US",\
        "email": "jsmith@example.com"\
      },\
      "response": {\
        "referenceId": "4ca693ee-af2a-45ef-9688-834683ac1b34",\
        "addressRisk": {\
          "reasonCodes": ["I704", "I705", "I708"],\
          "score": 0.01,\
          "scores": [\
            {\
              "name": "addressrisk_cus1",\
              "score": 0.01,\
              "version": "10.0"\
            }\
          ]\
        }\
      },\
      "is_source_cache": false,\
      "total_attempts": 1,\
      "error_message": ""\
    }\
  ],
  "environment_name": "Sandbox"
}
```

### Asynchronous evaluation (201 Created)   [Skip link to Asynchronous evaluation (201 Created)](https://help.socure.com/riskos/reference/api-responses\#asynchronous-evaluation-201-created)

An evaluation that paused to wait for async input. The `eval_end_time`, `decision_at`, `score`, and `tags` fields may be absent because the evaluation has not yet completed.

Poll with `GET /api/evaluation/{eval_id}` or subscribe to webhooks to receive a notification when the evaluation finishes.

JSON

```json
{
  "id": "onb-67890",
  "eval_id": "a3f2b91c-17d4-4e8a-b5c2-9f1e3a7d6c08",
  "workflow": "consumer_onboarding",
  "workflow_id": "472288ff-b3a8-4e69-89dd-069d5e2bcb41",
  "workflow_version": "3.7.0",
  "eval_status": "evaluation_paused",
  "decision": "REVIEW",
  "status": "OPEN",
  "sub_status": "Pending Verification",
  "eval_source": "API",
  "eval_start_time": "2025-01-15T10:30:24.456Z",
  "data_enrichments": [\
    {\
      "enrichment_name": "Deliver OTP SMS",\
      "enrichment_provider": "SocureOTP",\
      "enrichment_endpoint": "https://idplus.socure.com/api/1.0/otp/send",\
      "status_code": 200,\
      "request": {\
        "channel": "sms",\
        "destination": "+13125551234"\
      },\
      "response": {\
        "verificationId": "5ac71c12-32df-4fb2-ab76-5493444f3f97",\
        "error": ""\
      },\
      "is_source_cache": false,\
      "total_attempts": 1,\
      "error_message": ""\
    }\
  ]
}
```

## Error responses   [Skip link to Error responses](https://help.socure.com/riskos/reference/api-responses\#error-responses)

When a request fails, RiskOS™ returns a structured JSON error:

JSON

```json
{
  "error": "Workflow not found",
  "code": "WORKFLOW_NOT_FOUND",
  "message": "No workflow exists with the specified name",
  "invalid_args": []
}
```

| Field | Type | Description |
| --- | --- | --- |
| `error` | String | Customer-facing error message. Always present. |
| `code` | String | Machine-readable error code for programmatic handling (for example, `INVALID_REQUEST`, `AUTHENTICATION_FAILED`). |
| `message` | String | Additional diagnostic detail. May be absent on some error types. |
| `details` | Object | Structured metadata about the error (for example, size limits, constraints). Optional. |
| `invalid_args` | Array | Field-level validation errors, each with `field`, `value`, and `tag` properties. Present on `400` responses with validation failures. |

For the complete list of error codes, troubleshooting steps, and retry guidance, see [Errors](https://help.socure.com/riskos/reference/errors).

Updated 2 days ago

* * *

Did this page help you?

Yes

No

Updated 2 days ago

* * *

Did this page help you?

Yes

No