API Responses

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

HTTP status codes Skip link to HTTP status codes

Success Skip link to Success

Errors Skip link to Errors

See Errors for the complete error response schema, error codes, and retry guidance.

Evaluation response Skip link to 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

Decision and routing Skip link to Decision and routing

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

📘

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

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

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

Execution context Skip link to Execution context

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

Extended fields Skip link to Extended fields

These fields appear under specific conditions.

Enrichment results Skip link to 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

Provider response shapes Skip link to 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

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

OTP enrichments (Deliver and Verify)

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

Deliver OTP response:

JSON

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

Verify OTP response:

JSON

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

CNAM enrichment

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

JSON

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

Digital Intelligence enrichment

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

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:

Example responses Skip link to Example responses

Completed evaluation (200 OK) Skip link to Completed evaluation (200 OK)

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

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)

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

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

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

JSON

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

For the complete list of error codes, troubleshooting steps, and retry guidance, see Errors.

Updated 2 days ago

Did this page help you?

Yes

No

Updated 2 days ago

Did this page help you?

Yes

No