Integration Guide

Socure Phone Risk and SIM Swap API integration guide

This guide walks you through how to integrate with Socure’s /api/evaluation endpoint using the Phone Risk enrichment. You’ll learn how to send identity data with phone inputs, parse the risk and correlation results, and apply decision logic to support onboarding, trust & safety, account integrity, and fraud prevention workflows.

Before you start

Make sure your RiskOS™ environment is provisioned with:

📘

Global Support:

For a full list of supported countries, ISO codes, and dial patterns, see Phone Risk Usage Scope.

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 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 thresholds, correlation levels, and risk signals.

Common integration patterns

The table below outlines common integration patterns for Phone Risk and Phone Risk + SIM Swap, including typical input requirements and expected outcomes

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-123456",
  "timestamp": "2025-08-27T06:10:54.298Z",
  "workflow": "consumer_onboarding",
  "data": {
    "individual": {
      "given_name": "Guillermo",
      "family_name": "McNeil",
      "phone_number": "+14155551234",
      "address": {
        "country": "US",
        "locality": "San Francisco",
        "postal_code": "94105"
      }
    }
  }
}

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",
        "phone_number": "+14155551234",
        "address": {
          "country": "US",
          "locality": "San Francisco",
          "postal_code": "94105"
        }
      }
    }
  }'

Request schema

Top-level fields

📘

Note:

Phone Risk requires only data.individual.phone_number and data.individual.address.country to return risk scores, but for improved score accuracy we recommend including the optional fields for Phone 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 Phone Risk",
      "enrichment_provider": "Socure",
      "status_code": 200,
      "request": {
        "firstName": "Guillermo",
        "surName": "McNeil",
        "mobileNumber": "+14155551234",
        "city": "San Francisco",
        "zip": "94105",
        "country": "US",
        "modules": [
          "phonerisk"
        ]
      },
      "response": {
        "referenceId": "f3863a33-69ca-43c2-90e0-8b4344a41a09",
        "namePhoneCorrelation": {
          "reasonCodes": [
            "I621",
            "I622"
          ],
          "score": 0.92
        },
        "phoneRisk": {
          "reasonCodes": [
            "I620",
            "I609"
          ],
          "scores": [
            {
              "name": "Phone Risk Model (US) Norm",
              "version": "6.0",
              "score": 0.781
            }
          ]
        }
      }
    }
  ]
}

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.

👍

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.

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

namePhoneCorrelation fields

The phone correlation score value is a number between 0.01 and 0.99 that indicates the strength of the relationship between the phone number 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.

phoneRisk fields

Each phone risk score is a probabilistic value between 0.001 and 0.999 that represents the level of risk associated with a phone number. 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 name–phone correlation.
• Use parallel model scoring to compare performance of 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