## Before you start  
Make sure your RiskOS™ environment is provisioned with:

- [A workflow configured](https://help.socure.com/riskos/docs/address-risk-riskos-setup) for the **Address Risk** enrichment.
- [Regional support coverage](https://help.socure.com/riskos/docs/address-risk-usage-scope) for the **Address Risk** enrichment.

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

| 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-7891011"` |
| `timestamp` | String `<Date-Time>` | Required | RFC 3339 timestamp indicating when the evaluation was initiated. | `"2025-09-17T08:45:00.000Z"` |
| `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 containing individual and contextual information. |  |
| → `individual` | Object | Required | Primary identity object containing personal and address details. | See `individual` schema below. |

#### `individual` fields  
| Field | Type | Required | Description | Example |
| --- | --- | --- | --- | --- |
| `given_name` | String | Required | First name. Improves correlation accuracy. | `"Maria"` |
| `family_name` | String | Required | Last name. Improves correlation accuracy. | `"Lopez"` |
| `address` | Object | Required | Individual address fields. | See `address` schema below. |

#### `address` fields  
| Field | Type | Required | Description | Example |
| --- | --- | --- | --- | --- |
| `line_1` | String | Required | Street address line 1. | `"123 Main Street"` |
| `line_2` | String | Optional | Street address line 2. |  |
| `locality` | String | Optional | City or locality. | `"Miami"` |
| `major_admin_division` | String | Optional | State, province, or region (ISO 3166-2 format). | `"FL"` |
| `postal_code` | String | Optional | ZIP or postal code (hyphens optional). | `"33101"` |
| `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-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"
          ],
          "score": 0.921,
          "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.

| Area | Fields | How to use it |
| --- | --- | --- |
| **Decision and routing** | `decision`, `decision_at`, `tags`, `review_queues`, `notes`, `score` | **Primary control signals.** Branch application logic using `decision`. Use tags, queues, notes, and score for secondary routing, review, and explanation. |
| **Module results** | Module-specific fields (for example: `reasonCodes`, scores, extracted attributes) | Evidence and signals produced by workflow modules. Use for escalation, compliance review, investigation, and audit. |
| **Identifiers and traceability** | `id`, `eval_id` | Persist these identifiers to correlate API calls, logs, webhooks, GET requests, and support cases. |
| **Enrichment execution** | `data_enrichments[]` (`response`, `status_code`, `total_attempts`, `is_source_cache`) | Inspect enrichment outputs and detect provisioning issues, partial failures, retries, or cached responses. |
| **Workflow context** | `workflow`, `workflow_id`, `workflow_version` | Understand which workflow ran and which version produced the result. Useful for debugging and historical analysis. |
| **Evaluation lifecycle** | `eval_status`, `status`, `sub_status` | Execution and case state only. Useful for monitoring and asynchronous workflows. **Do not use for business decisions.** |
| **Execution context** | `eval_source`, `eval_start_time`, `eval_end_time`, `environment_name` | Observability and performance metadata for latency tracking, environment validation, and API vs Dashboard attribution. |

### Decision and routing (primary control signals)  
Use these fields to determine what action your application should take.

| 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-09-30T08:15:31.102Z"` |
| `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.58` |
| `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. | `[]` |
| `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. | `[]` |
| `notes` | String | Freeform text field for analyst or system comments about the evaluation. Often used to capture manual review rationale or investigation context. | `"Additional verification recommended"` |

### Evaluation lifecycle and status  
These fields describe where the evaluation is in its lifecycle and are useful for monitoring and asynchronous workflows.

| Field | Type | Description | Example |
| --- | --- | --- | --- |
| `eval_status` | String enum | Indicates the current state of an evaluation in RiskOS™.<br>Possible values:<br>• `evaluation_completed`<br>• `evaluation_paused`<br>• `evaluation_in_progress` | `"evaluation_completed"` |
| `status` | String enum | Indicates the current state of an evaluation or case.<br>Possible values:<br>• `OPEN`<br>• `CLOSED` | `"CLOSED"` |
| `sub_status` | String | Provides additional detail about the evaluation status.<br>Example values:<br>• `Under Review`<br>• `Pending Verification`<br>• `Accept`<br>• `Reject` | `"Under Review"` |

### Identifiers and traceability  
Use these fields to correlate requests, logs, webhooks, and support cases.

| Field | Type | Description | Example |
| --- | --- | --- | --- |
| `id` | String (UUID or custom string) | Your evaluation identifier within RiskOS™.<br>**Note**: This is _customer-generated_. | `"APP-7891011"` |
| `eval_id` | String (UUID) | RiskOS™-generated unique identifier for the evaluation. | `"8cfa9b52-5e6d-49ff-9d12-0c7f14f97c01"` |
| `workflow` | String | Name of the workflow executed. | `"consumer_onboarding"` |
| `workflow_id` | String (UUID) | Unique identifier for the workflow run. | `"9d2f4a3b-71c6-4e3f-9c82-8b7c5e4a6d01"` |
| `workflow_version` | String | Version of the executed workflow. | `"42.0.0"` |

### Execution context  
These fields provide timing and environment context for the evaluation.

| Field | Type | Description | Example |
| --- | --- | --- | --- |
| `eval_source` | String enum | Indicates where the evaluation was initiated from.<br>Possible values:<br>• `API`: Request submitted via the Evaluation API.<br>• `Dashboard`: Case created or evaluated through the RiskOS™ Dashboard. | `"API"` |
| `eval_start_time` | String `<Date-Time>` | RFC 3339 timestamp for when RiskOS™ started processing the evaluation. Useful for latency and performance monitoring. | `"2025-09-30T08:15:30.982Z"` |
| `eval_end_time` | String `<Date-Time>` | RFC 3339 timestamp for when RiskOS™ finished processing the evaluation. Can be paired with `eval_start_time` to compute total processing time. | `"2025-09-30T08:15:31.215Z"` |
| `environment_name` | String | Indicates which environment the evaluation ran in. Typically `Sandbox` for testing or `Production` for live traffic. | `"Sandbox"` |

### Enrichment results  
Enrichment outputs are returned in the `data_enrichments` array.

| Field | Type | Description | Example |
| --- | --- | --- | --- |
| `enrichment_name` | String | Product name. | `"Socure Address Risk"` |
| `enrichment_endpoint` | String (URL) | Endpoint invoked. |  |
| `enrichment_provider` | String | Provider. | `"Socure"` |
| `status_code` | Integer | HTTP status code. | `200` |
| `request` | Object | Payload sent to provider. | See `request` fields below. |
| `response` | Object | Payload returned by provider. | See `response` fields below. |
| `is_source_cache` | Boolean | Response served from cache. | `false` |
| `total_attempts` | Integer | Number of attempts. | `1` |

#### `request` fields  
| Field | Type | Description | Example |
| --- | --- | --- | --- |
| `mobileNumber` | String | Phone number of the individual in E.164 format. | `"+13051234567"` |
| `firstName` | String | First name of the individual submitting the information. | `"Maria"` |
| `surName` | String | Last name (surname) of the individual submitting the information. | `"Lopez"` |
| `physicalAddress` | String | Primary street address line 1 of the individual’s residence. | `"123 Main Street"` |
| `city` | String | City where the individual resides. | `"Miami"` |
| `state` | String | State, province, or region where the individual resides. | `"FL"` |
| `zip` | String | Postal or ZIP code associated with the individual’s address. | `"33101"` |
| `country` | String | Country code in ISO 3166-1 alpha-2 format. | `"US"` |
| `modules` | Array | List of enrichment modules requested for evaluation. | `[]` |

#### `response` fields  
| Field | Type | Description | Example |
| --- | --- | --- | --- |
| `referenceId` | String (UUID) | Unique identifier for the enrichment transaction. | `"a2c4ef01-b6a3-41af-9e82-df2c7db116d7"` |
| `nameAddressCorrelation` | Object | Correlation between the consumer’s name and address data. | See `nameAddressCorrelation` schema below. |
| `addressRisk` | Object | Risk assessment based on the provided address. | See `addressRisk` schema below. |

#### `nameAddressCorrelation` fields  
| Field | Type | Description | Example |
| --- | --- | --- | --- |
| `score` | Number | Correlation between physical address and provided `given_name` and `family_name`. | `0.84` |
| `reasonCodes` | Array of Strings | Factors influencing the correlation value | `[]` |

### `addressRisk` fields  
| Field | Type | Description | Example |
| --- | --- | --- | --- |
| `reasonCodes` | Array of Strings | List of reason codes indicating potential address-level risk factors. | `[]` |
| `score` | Number | Primary address risk score between `0.001–0.999`. A higher score indicates a greater likelihood of fraud. | `0.921` |
| `scores` | Array of Objects | Address risk model scores returned by the provider. |  |
| → `name` | String | Name of the scoring model used. | `"Address Risk Model (US) Norm"` |
| → `version` | String | Version of the scoring model. | `"3.2"` |
| → `score` | Number | Confidence score between `0.001` and `0.999`. | `0.921` |