## Before you start

Make sure your RiskOS™ environment is provisioned with:

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

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

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

The Sigma Synthetic product makes use of multiple input fields to determine both the score and reason codes. **For the highest accuracy and performance all these fields should be collected and passed in the input**, however the product will still work when select fields are not provided. The table below lists all input 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 | RFC 3339 timestamp indicating when the evaluation was initiated. | `"2022-07-28T06: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. |
| → `ip_address` | String | Recommended | IP address from which the consumer is accessing your service. | `"10.10.10.10"` |

#### `individual` fields

| Field | Type | Required | Description | Example |
| --- | --- | --- | --- | --- |
| `given_name` | String | Required | Consumer’s first name. | `"Shannon"` |
| `family_name` | String | Required | Consumer’s last name. | `"Zhao"` |
| `national_id` | String | Optional (Recommended) | Consumer’s nine-digit SSN or ITIN. Hyphens are optional. | `"123456789"` |
| `date_of_birth` | String | Required <br>_If omitted, models may have reduced accuracy._ | Consumer’s date of birth in `YYYY-MM-DD`, `YYYY/MM/DD`, or `YYYYMMDD` format. | `"1958-01-31"` |
| `email` | String | Required if neither `phone_number` nor both `address.line_1` and `address.postal_code` are provided. | Consumer’s email address. | `"j.smith@example.com"` |
| `phone_number` | String | Required if neither `email` nor both `address.line_1` and `address.postal_code` are provided. | Consumer’s phone number in E.164 format. The API expects the standard E.164 format but tolerates hyphens and spaces for user convenience. | `"+13475551234"` |
| `address` | Object | Required if neither `email` nor `phone_number` is provided (must include `line_1` and `postal_code`). | Structured address object containing residence details. | See `address` schema below. |

#### `address` fields

| Field | Type | Required | Description | Example |
| --- | --- | --- | --- | --- |
| `line_1` | String | Required if neither `email` nor `phone_number` is provided and must be accompanied by `postal_code`. | The first line of the consumer’s address. | `"234 Main Street"` |
| `line_2` | String | Optional (Recommended) | The second line of the address (e.g., apartment, suite, or unit number). | `"Apt. 3C"` |
| `locality` | String | Optional (Recommended) | The city or locality where the consumer resides. | `"Jersey City"` |
| `major_admin_division` | String | Optional (Recommended) | The state, province, or region where the consumer resides, in ISO 3166-2 format. | `"NJ"` |
| `postal_code` | String | Required if neither `email` nor `phone_number` is provided and must be accompanied by `line_1`. | The consumer’s five- or nine-digit ZIP code. Hyphens and spaces are optional. | `"07307"` |
| `country` | String | Required | The country where the consumer resides, in ISO 3166-1 alpha-2 format. | `"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": "ACCEPT",
  "tags": [],
  "review_queues": [],
  "data_enrichments": [
    {
      "enrichment_name": "Socure Sigma Synthetic",
      "enrichment_endpoint": "https://service.socure.com/api/3.0/EmailAuthScore",
      "enrichment_provider": "Socure",
      "status_code": 200,
      "request": {},
      "response": {
        "referenceId": "f3863a33-69ca-43c2-90e0-8b4344a41a09",
        "synthetic": {
          "reasonCodes": [
            "I610",
            "I621",
            "I912",
            "I622",
            "I554",
            "I568",
            "I212",
            "R217",
            "I557",
            "I709",
            "I208",
            "I559"
          ],
          "scores": [
            {
              "name": "synthetic",
              "version": "4.0",
              "score": 0.684
            }
          ]
        }
      }
    }
  ]
}
```

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

### 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` | `"ACCEPT"` |
| `decision_at` | String `<Date-Time>` | RFC 3339 timestamp when the decision was finalized. | `"2025-09-12T16:42:08.513Z"` |
| `score` | Number | If configured for a workflow, provides an aggregate score of all steps. | `0.94` |
| `tags` | Array of Strings | Array of labels applied during the workflow | `[]` |
| `review_queues` | Array of Strings | Lists any manual review queues the evaluation was sent to. | `[]` |
| `notes` | String | Freeform text field for analyst or system comments about the evaluation. | `"Auto-approved after successful verification"` |

### Evaluation lifecycle and status

| Field | Type | Description | Example |
| --- | --- | --- | --- |
| `eval_status` | String (enum) | Current state of an evaluation in RiskOS™. | `"evaluation_completed"` |
| `status` | String (enum) | Current state of an evaluation or case. | `"CLOSED"` |
| `sub_status` | String | Additional detail about the evaluation status. | `"Accept"` |

### Identifiers and traceability

| Field | Type | Description | Example |
| --- | --- | --- | --- |
| `id` | String | Your evaluation identifier within RiskOS™. | `"APP-123456"` |
| `eval_id` | String | RiskOS™-generated unique identifier for the evaluation. | `"6dc8f39c-ecc3-4fe0-9283-fc8e5f99e816"` |
| `workflow` | String | Name of the workflow executed. | `"consumer_onboarding"` |
| `workflow_id` | String (UUID) | Unique identifier for the workflow run. | `"dc7f261e-b158-477e-9770-7e4eae066156"` |
| `workflow_version` | String | Version of the executed workflow. | `"28.16.0"` |

### Execution context

| Field | Type | Description | Example |
| --- | --- | --- | --- |
| `eval_source` | String enum | Indicates where the evaluation was initiated from. | `"API"` |
| `eval_start_time` | String `<Date-Time>` | RFC 3339 timestamp for when RiskOS™ started processing the evaluation. | `"2025-09-30T08:15:30.982Z"` |
| `eval_end_time` | String `<Date-Time>` | RFC 3339 timestamp for when RiskOS™ finished processing the evaluation. | `"2025-09-30T08:15:31.215Z"` |
| `environment_name` | String | Indicates which environment the evaluation ran in. | `"Sandbox"` |