Integrate Email Risk

Before you start

Make sure your RiskOS™ environment is provisioned with:

• A workflow configured for the Email Risk enrichment.
• Regional support coverage for the Email Risk 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 at least an email address.
2. Socure runs the request through the configured RiskOS™ workflow and applies the Email Risk enrichment.
3. Receive a decision (ACCEPT, REVIEW, or REJECT) and supporting metadata.
4. Apply your routing logic based on thresholds, correlation levels, and risk signals.

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-123456",
  "timestamp": "2025-08-27T06:10:54.298Z",
  "workflow": "consumer_onboarding",
  "data": {
    "individual": {
      "given_name": "Guillermo",
      "family_name": "McNeil",
      "email": "guillermo.mcneil@example.com",
      "address": {
        "country": "US"
      }
    }
  }
}

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-123456",
    "timestamp": "2025-08-27T06:10:54.298Z",
    "workflow": "consumer_onboarding",
    "data": {
      "individual": {
        "given_name": "Guillermo",
        "family_name": "McNeil",
        "email": "guillermo.mcneil@example.com",
        "address": {
          "country": "US"
        }
      }
    }
  }'

Request schema

Top-level fields

📘

Note:

Email Risk requires only data.individual.email to return a risk score, but for improved score accuracy we recommend including the optional fields for Email Risk in the request.

individual fields

address 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-123456",
  "eval_id": "6dc8f39c-ecc3-4fe0-9283-fc8e5f99e816",
  "decision": "REVIEW",
  "data_enrichments": [
    {
      "enrichment_name": "Socure Email Risk",
      "enrichment_provider": "Socure",
      "status_code": 200,
      "request": {
        "email": "guillermo.mcneil@example.com",
        "given_name": "Guillermo",
        "family_name": "McNeil",
        "address": {
          "country": "US"
        },
        "modules": [
          "emailrisk"
        ]
      },
      "response": {
        "referenceId": "f3863a33-69ca-43c2-90e0-8b4344a41a09",
        "nameEmailCorrelation": {
          "reasonCodes": [
            "I557",
            "R551"
          ],
          "score": 0.99
        },
        "emailRisk": {
          "reasonCodes": [
            "I520",
            "R563"
          ],
          "score": 0.887,
          "scores": [
            {
              "name": "Email Risk Model (US) Norm",
              "version": "7.0",
              "score": 0.887
            }
          ]
        }
      }
    }
  ]
}

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)

Use these fields to determine what action your application should take.

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.

request fields

response fields

nameEmailCorrelation fields

The email correlation value is a number between 0.01 and 0.99 that indicates the strength of the relationship between the email address and the consumer's given_name and family_name.

emailRisk fields