Integrate eCBSV

Before you start

Make sure your RiskOS™ environment is provisioned with:

• A workflow configured for the eCBSV enrichment.
• Regional support coverage for the eCBSV enrichment.

Choose your environment

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

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

• No real customer data
• Free testing environment
• Unlimited API calls

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

• Real customer data
• API usage charges apply
• Connects to live data services

Get an API key

1. In the Sandbox RiskOS™ Dashboard, go to Developer Workbench > API Keys.

2. Copy your API key securely.

3. In the Production RiskOS™ Dashboard, go to Developer Workbench > API Keys.

4. Copy your API key securely

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

SandboxProduction

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.