Integrate Address Risk

Overview

This guide shows you how to:

1. Gather the consumer's address (at minimum line_1 and country), plus optional name and phone, on your onboarding form.
2. Submit a POST /api/evaluation request from your backend with the collected data.
3. Act on the decision field (ACCEPT, REVIEW, or REJECT) in the response to route the consumer.
4. Use the Address Risk score, name–address correlation, and reason codes to refine your routing thresholds.

Before you start

Start an evaluation

Endpoint

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

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

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

Authentication

Include your API key in the Authorization header as a Bearer token, 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",
      "phone_number": "+13051234567",
      "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",
        "phone_number": "+13051234567",
        "address": {
          "line_1": "123 Main Street",
          "locality": "Miami",
          "major_admin_division": "FL",
          "postal_code": "33101",
          "country": "US"
        }
      }
    }
  }'

Request schema

Top-level fields

Path: root request object

individual fields

Path: data.individual

address fields

Path: data.individual.address

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",
        "customerProfile": {
          "userId": "usr_7f3a91bc",
          "customerUserId": "cust_00123456"
        },
        "nameAddressCorrelation": {
          "reasonCodes": [
            "R710",
            "I712"
          ],
          "score": 0.84
        },
        "addressRisk": {
          "reasonCodes": [
            "R705",
            "R720"
          ],
          "scores": [
            {
              "name": "Address Risk Model (US) Norm",
              "version": "3.2",
              "score": 0.921
            }
          ],
          "signals": {}
        }
      }
    }
  ]
}

Key response fields

RiskOS™ returns a consistent set of top-level fields that describe the outcome of an evaluation, 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.

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.

request fields

response fields

customerProfile fields

nameAddressCorrelation fields

The nameAddressCorrelation.score is a number between 0.01 and 0.99 that indicates the strength of the relationship between the physical address and the consumer's given_name and family_name.

You can interpret the range of possible values as follows:

• 0.95 - 0.99: Very high confidence. The full name match was verified by one or more sources.
• 0.85 - 0.94: High confidence. The partial name match (includes fuzzy matches and nicknames) was verified by one or more sources.
• 0.75 - 0.84: Medium-to-high confidence. The last name match was verified by one or more sources.
• 0.65 - 0.74: Low confidence. Partial name match only.
• 0.20 - 0.64: Correlation status is unknown. The Evaluation endpoint was unable to determine correlation.
• 0.01 - 0.19: Disconnected identity elements. No correlation found.

addressRisk fields

Each address risk score is a probabilistic value between 0.001 and 0.999 that represents the level of risk associated with an address. A higher score indicates a greater likelihood of fraud.

For example, a score of 0.800 means that the consumer is riskier than 80 percent of all consumers and less risky than 20 percent of consumers. In general, consumers with scores equal to or greater than 0.970 are considered high risk.

Best practices

• Always include given_name and family_name for stronger correlation.
• Use parallel model scoring to compare challenger vs. champion models.
• Investigate discrepancies between multiple model scores — they may indicate edge cases.
• Tune thresholds (for example, ≥0.97 for auto-fail) to balance fraud capture vs. false positives.
• Log reason codes for auditability and continuous improvement.

Validation checklist