## Before you start

Make sure your RiskOS™ environment is provisioned with:

- [A workflow configured](https://help.socure.com/riskos/docs/ecbsv-riskos-setup#/) for the **eCBSV enrichment**.
- [Regional support coverage](https://help.socure.com/riskos/docs/verify-overview#/) for the **eCBSV 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.

* * *

## Example frontend input form (mapped to `/api/evaluation` payload)

This example screen shows how a mobile app might capture user information during onboarding before triggering a RiskOS™ `/api/evaluation` request.

Each field maps to required parameters in the `data.individual` object:

- First Name → `given_name`
- Last Name → `family_name`
- Date of Birth → `date_of_birth`
- National ID → `national_id`

You can configure which fields are required per workflow by adjusting module-level match logic in RiskOS™.

* * *

## 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-987654",
  "timestamp": "2025-08-13T06:10:54.298Z",
  "workflow": "consumer_onboarding",
  "data": {
    "individual": {
      "given_name": "Shannon",
      "family_name": "Zhao",
      "date_of_birth": "1973-06-20",
      "national_id": "136582341",
      "country": "US",
      "additional_context": {
        "user_consent": true,
        "consent_timestamp": "2025-08-19T18:24:00.000Z"
      }
    }
  }
}
```

```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-987654",
    "timestamp": "2025-08-13T06:10:54.298Z",
    "workflow": "consumer_onboarding",
    "data": {
      "individual": {
        "given_name": "Shannon",
        "family_name": "Zhao",
        "date_of_birth": "1973-06-20",
        "national_id": "136582341",
        "country": "US",
        "additional_context": {
          "user_consent": true,
          "consent_timestamp": "2025-08-19T18:24:00.000Z"
        }
      }
    }
  }'
```

### 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-987654" |
| `timestamp` | String | Required | Timestamp when evaluation was initiated. | "2025-08-13T06:10:54.298Z" |
| `workflow` | String | Required | RiskOS™ workflow name. <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 | Primary request payload container. |  |
| →`individual` | Object | Required | Primary identity object containing account information. | See `individual` schema below. |

#### `individual` fields

| Field | Type | Required | Description | Example |
| --- | --- | --- | --- | --- |
| `given_name` | String | Required | Individual’s first or given name. | "Shannon" |
| `family_name` | String | Required | Individual’s last or family name. | "Zhao" |
| `national_id` | String | Required | Government-issued ID. | "136582341" |
| `date_of_birth` | String | Required | Individual’s date of birth, formatted as `YYYY-MM-DD`. | "1973-06-20" |
| `country` | String | Required | ISO 3166-1 alpha-2 code representing the individual’s country of residence. | "US" |
| `additional_context` | object | Required | Use this field to pass additional data required by specific Socure products. |  |
| →`user_consent` | Boolean | Required | Indicates whether the individual explicitly provided consent for verification. | `true` |
| →`consent_timestamp` | String `<Date-Time>` | Required | Date and time (RFC 3339 format) when consent was recorded. | "2025-08-19T18:24:00.000Z" |

## 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-987654",
  "eval_id": "c9e53a0f-35f4-4d18-bf26-ec1788c9f47a",
  "decision": "REVIEW",
  "tags": ["low_id_coverage","manual_review_required"],
  "review_queues": ["kyc-us"],
  "data_enrichments": [
    {
      "enrichment_name": "eCBSV",
      "enrichment_endpoint": "https://sandbox.dev.socure.com/api/3.0/EmailAuthScore",
      "enrichment_provider": "Socure",
      "status_code": 200,
      "request": {
        "country": "US",
        "firstName": "Shannon",
        "surName": "Zhao",
        "dob": "1973-06-20",
        "nationalId": "136582341",
        "userConsent": true,
        "consentTimestamp": "2025-08-19T18:24:00.000Z"
      },
      "response": {
        "referenceId": "f3863a33-69ca-43c2-90e0-8b4344a41a09",
        "socureId": "ab06216f-b88b-4be8-8075-933bb5c2303c",
        "ecbsv": {
          "reasonCodes": ["I998","I999"]
        }
      }
    }
  ]
}
```

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

#### Where to find specific results

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

These fields describe the outcome of an evaluation and any routing applied by the workflow.

| 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-08-19T18:24:32.114Z" |
| `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.42` |
| `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. | `["low_id_coverage", "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. | `[