## Before you start

Make sure your RiskOS™ environment is provisioned with:

- [A workflow configured](https://help.socure.com/riskos/docs/login-authentication-riskos-setup) for the **Login and Authentication** solution.
- Verified [global support coverage](https://help.socure.com/riskos/docs/login-authentication-usage-scope) for the **Login and Authentication** solution.

### 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.socure.com/developers/api-keys).
2. Copy your API key securely.

## How it works

1. Send a `POST /api/evaluation` request with login event, identity, and device data.
2. RiskOS™ evaluates the request using your Login and Authentication workflow.
3. You receive a decision (`APPROVE`, `REVIEW`, or `REJECT`).
4. Apply the decision to allow access, require step-up verification, or block the login attempt.

> 📘  
> **Note**:  
> The `decision` values shown in this guide (`APPROVE`, `REVIEW`, `REJECT`) reflect a customized Login and Authentication workflow.
> Your environment may use different default decision values depending on how your workflow is configured.

## Start a new evaluation

### Endpoint

Sandbox  
Production

```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: application/json required

```json
{
  "id": "ato-78901",
  "timestamp": "2023-12-01T15:45:12.678Z",
  "workflow": "account_takeover",
  "data": {
    "event_type": "address_update",
    "event_category": "update",
    "ip_address": "203.0.113.10",
    "individual": {
      "id": "ind-9876543",
      "given_name": "Jane",
      "family_name": "Smith",
      "national_id": "123456789",
      "date_of_birth": "1990-05-15",
      "email": "jane.smith@example.com",
      "phone_number": "+1-312-555-1234",
      "address": {
        "line_1": "742 Evergreen Terrace",
        "line_2": "Apt 12B",
        "locality": "Springfield",
        "major_admin_division": "IL",
        "country": "US",
        "postal_code": "62704"
      },
      "di_session_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzUxMiJ...PiUsws9D6O3DjSjNDCbIJKciX44s"
    },
    "event_details": {
      "previous": {
        "address": {
          "line_1": "123 Main Street",
          "line_2": "Suite 100",
          "locality": "Brooklyn",
          "major_admin_division": "NY",
          "country": "US",
          "postal_code": "11201"
        }
      }
    },
    "custom": {}
  }
}
```

```curl
curl --location 'https://riskos.sandbox.socure.com/api/evaluation' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer YOUR_API_KEY' \
--data-raw '{\n  "id": "ato-78901",\n  "timestamp": "2023-12-01T15:45:12.678Z",\n  "workflow": "account_takeover",\n  "data": {\n    "event_type": "address_update",\n    "event_category": "update",\n    "ip_address": "203.0.113.10",\n    "individual": {\n      "id": "ind-9876543",\n      "given_name": "Jane",\n      "family_name": "Smith",\n      "national_id": "123456789",\n      "date_of_birth": "1990-05-15",\n      "email": "jane.smith@example.com",\n      "phone_number": "+1-312-555-1234",\n      "address": {\n        "line_1": "742 Evergreen Terrace",\n        "line_2": "Apt 12B",\n        "locality": "Springfield",\n        "major_admin_division": "IL",\n        "country": "US",\n        "postal_code": "62704"\n      },\n      "di_session_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzUxMiJ...PiUsws9D6O3DjSjNDCbIJKciX44s"\n    },\n    "event_details": {\n      "previous": {\n        "address": {\n          "line_1": "123 Main Street",\n          "line_2": "Suite 100",\n          "locality": "Brooklyn",\n          "major_admin_division": "NY",\n          "country": "US",\n          "postal_code": "11201"\n        }\n      }\n    },\n    "custom": {}\n  }\n}'
```

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