Integrate Phone Risk

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

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

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 identity data.
  2. Socure runs the request through the 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.

Module Required Inputs Response
phonerisk phone_number + address.country phoneRisk reason codes and score + namePhoneCorrelation score.
phonerisk + SIM Swap phone_number + address.country + given_name, family_name phoneRisk reason codes and score + namePhoneCorrelation score + SIM Swap reason codes.

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

Field Type Required Description Example
id String Required Required, customer-defined unique identifier for the request.
This value must be unique for each evaluation. Reusing an ID causes RiskOS™ to treat the request as a re-run and can impact processing behavior, results, and downstream workflows.		 "APP-123456"
timestamp String Required RFC 3339 timestamp indicating when the evaluation was initiated. "2025-08-27T06:10:54.298Z"
workflow String Required RiskOS™ workflow name configured in your environment.
Note: The workflow name must be unique within your RiskOS™ environment. It is not scoped by use case and must identify a single active workflow for each Evaluation API request.		 "consumer_onboarding"
data Object Required Main payload for the RiskOS™ workflow containing all request details.
→ individual Object Required Individual identity object containing personal and address information. See individual schema below.

individual fields

Field Type Required Description Example
phone_number String Required Phone number in E.164 format (e.g., +14155551234). "+14155551234"
given_name String Optional First name. Improves correlation accuracy. "Guillermo"
family_name String Optional Last name. Improves correlation accuracy. "McNeil"
address Object Optional Individual address fields. See address schema below.

address fields

Field Type Required Description Example
line_1 String Optional Street address line 1. "742 Evergreen Terrace"
line_2 String Optional Street address line 2. "Apt 12B"
locality String Optional City or locality. "San Francisco"
major_admin_division String Optional State, province, or region (ISO 3166-2 format). "CA"
postal_code String Optional ZIP or postal code (hyphens optional). "94105"
country String Required Country in ISO 3166-1 alpha-2 format (e.g., US, CA). "US"

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

Field Type Description Example
decision String (enum) Final evaluation result.
Possible values:
• ACCEPT
• REVIEW
• REJECT
Note: The fields returned can be customized to fit your integration or business needs.		 "REVIEW"
decision_at String <Date-Time> RFC 3339 timestamp when the decision was finalized. "2025-10-15T11:27:42.908Z"
score Number If configured for a workflow, provides an aggregate score of all steps. This can be used for risk banding, additional routing, or analytics alongside the primary decision value. 0.57
tags Array of Strings Array of labels applied during the workflow to highlight routing choices, notable signals, or rule outcomes. Useful for reporting, segmentation, or UI highlighting in the RiskOS™ Dashboard. ["manual_review_required"]
review_queues Array of Strings Lists any manual review queues the evaluation was sent to. Empty when the case is fully auto-resolved without human review. ["kyc-us"]
notes String Freeform text field for analyst or system comments about the evaluation. Often used to capture manual review rationale or investigation context. "Review required due to elevated risk indicators"

Best practices