## Before you start

Make sure your RiskOS™ environment is provisioned with:

[A workflow configured](https://help.socure.com/riskos/docs/sigma-identity-fraud-riskos-setup) for the **Sigma Identity Fraud** 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 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 the result.

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

> 📘
>
> **Note**:
>
> Do not pass **placeholder** or **dummy** values for any of these fields when you are not able to collect them from the end-user. Passing such values will lead to reduced accuracy and can impact future predictions. If you are not able to collect a field value from the consumer, pass `null` for that field.

```json
{
  "id": "APP-123456",
  "timestamp": "2022-07-28T06:10:54.298Z",
  "workflow": "consumer_onboarding",
  "data": {
    "individual": {
      "given_name": "Shannon",
      "family_name": "Zhao",
      "national_id": "123456789",
      "date_of_birth": "1958-01-31",
      "email": "j.smith@example.com",
      "phone_number": "+13475551234",
      "address": {
        "line_1": "234 Main Street",
        "line_2": "Apt. 3C",
        "locality": "Jersey City",
        "major_admin_division": "NJ",
        "country": "US",
        "postal_code": "07307"
      }
    },
    "ip_address": "10.10.10.10"
  }
}
```

```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": "2022-07-28T06:10:54.298Z",
    "workflow": "consumer_onboarding",
    "data": {
      "individual": {
        "given_name": "Shannon",
        "family_name": "Zhao",
        "national_id": "123456789",
        "date_of_birth": "1958-01-31",
        "email": "j.smith@example.com",
        "phone_number": "+13475551234",
        "address": {
          "line_1": "234 Main Street",
          "line_2": "Apt. 3C",
          "locality": "Jersey City",
          "major_admin_division": "NJ",
          "country": "US",
          "postal_code": "07307"
        }
      },
      "ip_address": "10.10.10.10"
    }
  }'
```

### Request schema

#### Top-level fields

| 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 | ISO 8601 timestamp indicating when the evaluation request was initiated. | `"2022-07-28T06:10:54.298Z"` |
| `workflow` | String | Required | Name of the RiskOS™ workflow 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 for evaluation. |  |
| → `individual` | Object | Required | Primary identity object containing personal and address details. | See `individual` schema below. |
| → `ip_address` | String | Optional (Recommended) | IP address from which the consumer is accessing your services. | `"10.10.10.10"` |

### 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",
  "tags": [],
  "review_queues": [],
  "data_enrichments": [
    {
      "enrichment_name": "Socure Sigma Identity Fraud",
      "enrichment_endpoint": "https://service.socure.com/api/3.0/EmailAuthScore",
      "enrichment_provider": "Socure",
      "status_code": 200,
      "request": {},
      "response": {
        "referenceId": "f3863a33-69ca-43c2-90e0-8b4344a41a09",
        "fraud": {
          "reasonCodes": [
            "R617",
            "R613",
            "I625",
            "R705",
            "I614",
            "R703",
            "R551",
            "R563",
            "R611"
          ],
          "scores": [
            {
              "name": "sigma",
              "version": "4.0",
              "score": 0.957
            }
          ]
        }
      }
    }
  ]
}
```

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