Integrate Address Risk

Before you start

Make sure your RiskOS™ environment is provisioned with:

• A workflow configured for the Address Risk enrichment.
• Regional support coverage for the Address 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 address (line 1 and country).
2. Socure runs the request through the configured RiskOS™ workflow and applies the Address 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-7891011",
  "timestamp": "2025-09-17T08:45:00.000Z",
  "workflow": "consumer_onboarding",
  "data": {
    "individual": {
      "given_name": "Maria",
      "family_name": "Lopez",
      "address": {
        "line_1": "123 Main Street",
        "locality": "Miami",
        "major_admin_division": "FL",
        "postal_code": "33101",
        "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-7891011",
    "timestamp": "2025-09-17T08:45:00.000Z",
    "workflow": "consumer_onboarding",
    "data": {
      "individual": {
        "given_name": "Maria",
        "family_name": "Lopez",
        "address": {
          "line_1": "123 Main Street",
          "locality": "Miami",
          "major_admin_division": "FL",
          "postal_code": "33101",
          "country": "US"
        }
      }
    }
  }'

Request schema

Top-level fields

📘 Note: To improve the accuracy of the address risk score, we recommend including as many optional fields as possible 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-7891011",
  "eval_id": "8cfa9b52-5e6d-49ff-9d12-0c7f14f97c01",
  "decision": "REVIEW",
  "data_enrichments": [
    {
      "enrichment_name": "Socure Address Risk",
      "enrichment_provider": "Socure",
      "status_code": 200,
      "request": {
        "mobileNumber": "+13051234567",
        "firstName": "Maria",
        "surName": "Lopez",
        "physicalAddress": "123 Main Street",
        "city": "Miami",
        "state": "FL",
        "zip": "33101",
        "country": "US"
      },
      "response": {
        "referenceId": "a2c4ef01-b6a3-41af-9e82-df2c7db116d7",
        "nameAddressCorrelation": {
          "reasonCodes": [
            "R710",
            "I712"
          ],
          "score": 0.84
        },
        "addressRisk": {
          "reasonCodes": [
            "R705",
            "R720"
          ],
          "score": 0.921,
          "scores": [
            {
              "name": "Address Risk Model (US) Norm",
              "version": "3.2",
              "score": 0.921
            }
          ]
        }
      }
    }
  ]
}

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.

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

nameAddressCorrelation fields

addressRisk fields