Integration Guide

Socure Address Risk API integration guide

This guide walks you through how to integrate with Socure’s /api/evaluation endpoint using the Address Risk enrichment. You’ll learn how to send identity data with address inputs, parse the risk and correlation results, and apply decision logic to support onboarding, trust and safety, account integrity, and fraud prevention 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 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

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"
          ],
          "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.

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

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.

The range of possible values can be interpreted 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.999that 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.

👍

Tip:

When multiple risk scores are returned, we recommend following these guidelines:

• Evaluate each model's performance individually, considering metrics such as fraud capture rate, false positive rate, AUC, etc., to gauge accuracy.
• Understand the specific use cases and goals optimized in each model, as differently tuned models can yield varied scores.
• Scrutinize the input data and algorithms employed, recognizing that models utilizing distinct techniques or data may produce diverse results.
• Align scores with risk strategies and thresholds, contemplating the optimal utilization of multiple outputs for decision-making.
• Investigate substantial score discrepancies, as conflicting scores may indicate an unusual case that warrants further review.
• Refer to documentation outlining the design and purpose of each model to guide the interpretation of scores. Reach out to your Technical Account Manager to inquire about these documents.

In cases of significant score conflicts, prioritize the model with superior performance based on metrics like the fraud capture rate to serve as the tie-breaker.

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 (e.g., ≥0.97 for auto-fail) to balance fraud capture vs. false positives.
• Log reason codes for auditability and continuous improvement.

Validation checklist