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

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

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 for the complete error response schema, error codes, and retry guidance.

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

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

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"]`
`decision_tags`	Array of strings	Subset of `tags` contributed only by the workflow's terminal decision or manual review step. Use this field when you need the tags that directly explain the final `decision`.	`["High Risk"]`
`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.

To trace a REJECT or REVIEW back to the enrichment scores and reason codes that drove it, see Interpret a Decline.

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

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

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

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.
`customer_metadata`	Object	Present when submitted on the request.	Opaque, caller-owned JSON echoed back from the original evaluation request. See Customer Metadata.

Enrichment results

The data_enrichments array contains one object per enrichment module executed in the workflow. The array order matches the execution sequence. Each enrichment returns a score and a reasonCodes array — to read what those codes mean and how they relate to the decision, see Reason Codes & Score Interpretation.

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.
`request_url_params`	Object	Query string parameters sent to the provider, for enrichments called via URL parameters rather than a request body.
`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

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.

{
  "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:

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

Verify OTP response:

{
  "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.

{
  "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.

{
  "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

Completed evaluation (200 OK)

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

{
  "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": "[email protected]"
      },
      "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": "[email protected]"
      },
      "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)

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.

{
  "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

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

{
  "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.