Integration Guide

eCBSV API Integration Guide

This guide walks you through how to integrate with Socure’s /api/evaluation endpoint using the eCBSV enrichments. You’ll learn how to send identity data, parse the response, and apply decision logic to support onboarding, trust and safety, fraud prevention, or compliance workflows.

Before you start

Make sure your RiskOS™ environment is provisioned with:

Choose your environment

Start with Sandbox for development and testing, then move to Production for live applications.

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

Get an API key

How it works

1. Send a POST request to /api/evaluation with identity data.
2. Socure runs the request through configured RiskOS™ workflow with tailored enrichments.
3. Receive a decision (ACCEPT, REVIEW, or REJECT) and supporting metadata.
4. Apply your routing logic based on the result.

Example frontend input form (mapped to /api/evaluation payload)

This example screen shows how a mobile app might capture user information during onboarding before triggering a RiskOS™ /api/evaluation request.

Each field maps to required parameters in the data.individual object:

• First Name → given_name
• Last Name → family_name
• Date of Birth → date_of_birth
• National ID → national_id

You can configure which fields are required per workflow by adjusting module-level match logic in RiskOS™.

Start a new Risk 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

{
  "id": "APP-987654",
  "timestamp": "2025-08-13T06:10:54.298Z",
  "workflow": "consumer_onboarding",
  "data": {
    "individual": {
      "given_name": "Shannon",
      "family_name": "Zhao",
      "date_of_birth": "1973-06-20",
      "national_id": "136582341",
      "country": "US",
      "additional_context": {
        "user_consent": true,
        "consent_timestamp": "2025-08-19T18:24:00.000Z"
      }
    }
  }
}

curl --location --request POST '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": "APP-987654",
    "timestamp": "2025-08-13T06:10:54.298Z",
    "workflow": "consumer_onboarding",
    "data": {
      "individual": {
        "given_name": "Shannon",
        "family_name": "Zhao",
        "date_of_birth": "1973-06-20",
        "national_id": "136582341",
        "country": "US",
        "additional_context": {
          "user_consent": true,
          "consent_timestamp": "2025-08-19T18:24:00.000Z"
        }
      }
    }
  }'

Request schema

Top-level fields

individual fields

Example response

When you call the Evaluation API, RiskOS™ returns a JSON payload that includes the final decision, evaluation metadata, and enrichment-specific results.

{
  "id": "APP-987654",
  "eval_id": "c9e53a0f-35f4-4d18-bf26-ec1788c9f47a",
  "decision": "REVIEW",
  "tags": [
    "low_id_coverage",
    "manual_review_required"
  ],
  "review_queues": [
    "kyc-us"
  ],
  "data_enrichments": [
    {
      "enrichment_name": "eCBSV",
      "enrichment_endpoint": "https://sandbox.dev.socure.com/api/3.0/EmailAuthScore",
      "enrichment_provider": "Socure",
      "status_code": 200,
      "request": {
        "country": "US",
        "firstName": "Shannon",
        "surName": "Zhao",
        "dob": "1973-06-20",
        "nationalId": "136582341",
        "userConsent": true,
        "consentTimestamp": "2025-08-19T18:24:00.000Z"
      },
      "response": {
        "referenceId": "f3863a33-69ca-43c2-90e0-8b4344a41a09",
        "socureId": "ab06216f-b88b-4be8-8075-933bb5c2303c",
        "ecbsv": {
          "reasonCodes": [
            "I998",
            "I999"
          ]
        }
      }
    }
  ]
}

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

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.

Evaluation lifecycle and status

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

Identifiers and traceability

Use these fields to correlate requests, logs, webhooks, and support cases.

Execution context

These fields provide timing and environment context for the evaluation.

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.

request fields

response fields

Apply routing logic

Apply the decision parameter to your application:

if response.get("decision") == "PASS":
    proceed_with_onboarding()
elif response.get("decision") == "REVIEW":
    trigger_manual_review(queue=response.get("review_queues", ["Default"])[0])
elif response.get("decision") == "FAIL":
    reject_application(reason="Identity verification failed")
else:
    log_warning("Unknown decision value", response.get("decision"))

Use RiskOS™ logs to trace enrichment execution and reason code evaluation logic. For auditability, log the full response payload and decision scores per field.

Test in Sandbox

You can simulate almost any identity scenario using our Test Personas JSON file. Each entry includes a realistic, sandbox-only identity and a ready-to-use API request payload. Many entries also include the expected response to help you validate your /api/evaluation integration before going live.

• Endpoint: POST /api/evaluation
• Base URL (Sandbox): https://riskos.sandbox.socure.com/api/evaluation
• Auth: Authorization: Bearer YOUR_SANDBOX_KEY

APPROVE response

{
  "decision": "APPROVE",
  "data_enrichments": [
    {
      "status_code": 200,
      "response": {
        "referenceId": "f3863a33-69ca-43c2-90e0-8b4344a41a09",
        "socureId": "ab06216f-b88b-4be8-8075-933bb5c2303c",
        "eCBSV": {
          "reasonCodes": [
            "I998",  "I999"
          ]
        }
      }
    }
  ]
}

REVIEW response

{
  "decision": "REVIEW",
  "data_enrichments": [
    {
      "status_code": 200,
      "response": {
        "referenceId": "f3863a33-69ca-43c2-90e0-8b4344a41a09",
        "socureId": "ab06216f-b88b-4be8-8075-933bb5c2303c",
        "eCBSV": {
          "reasonCodes": [
            "R998","R992", "I993", "I994" 
          ]
        }
      }
    }
  ]
}

DECLINE response

{
  "decision": "DECLINE",
  "data_enrichments": [
    {
      "status_code": 200,
      "response": {
        "referenceId": "f3863a33-69ca-43c2-90e0-8b4344a41a09",
        "socureId": "ab06216f-b88b-4be8-8075-933bb5c2303c",
        "eCBSV": {
          "reasonCodes": [
            "R998","R992", "R993", "R994" 
          ]
        }
      }
    }
  ]
}

Best practices for integration and maintenance

• Always validate API inputs against the expected schema.
• Use sandbox mode and known test identities during QA.
• Enable and monitor reasonCodes for transparency and auditability.
• Use decision, tags, and review_queues to drive routing logic in your RiskOS™ workflow.
• Log and store evaluation payloads and responses for compliance, dispute resolution, and improvement.

Other relevant API endpoints exposed via RiskOS™

RiskOS™ supports a range of identity verification use cases through modular API endpoints. These modules can be configured independently or combined within workflows to meet regional compliance requirements, fraud detection strategies, and onboarding needs.

Validation checklist

Test coverage

Schema and error handling

Logging and observability

Exception routing