## Before you start

Make sure your RiskOS™ environment is provisioned with:

- [A workflow configured](https://help.socure.com/riskos/docs/phone-risk-riskos-setup) for the **Phone Risk** and **Phone Risk with SIM Swap** enrichment.
- [Regional support coverage](https://help.socure.com/riskos/docs/phone-risk-usage-scope) for the **Phone Risk** and **Phone Risk with SIM Swap** enrichment.

> 📘  
> **Global Support**:  
> For a full list of supported countries, ISO codes, and dial patterns, see [Phone Risk Usage Scope](https://help.socure.com/riskos/docs/phone-risk-usage-scope).

### Choose your environment

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

```undefined
  https://riskos.sandbox.socure.com/api/evaluation
```

- **No real customer data**  
- **Free testing environment**  
- **Unlimited API calls**

```undefined
  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**](https://riskos.sandbox.socure.com/developers/api-keys).
2. Copy your API key securely.

1. In the Production RiskOS™ Dashboard, go to [**Developer Workbench > API Keys**](https://riskos.sandbox.socure.com/developers/api-keys).
2. 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

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

```http
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:

```http
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

```json
{
  "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
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.<br>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. <br>**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.

```json
{
  "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.<br>Possible values:<br>• `ACCEPT`<br>• `REVIEW`<br>• `REJECT`<br>**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

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