## Before you start

Get your **API key** and **SDK key** from the [API & SDK Keys](https://riskos.sandbox.socure.com/developers/key-management) page in the RiskOS™ Dashboard.

Use the Sandbox base URL `riskos.sandbox.socure.com` for all requests.

Register a [webhook endpoint](https://help.socure.com/riskos/docs/webhooks) to receive `evaluation_completed` events for asynchronous decisions.

## Test with Postman

Use this Postman collection to send sample requests to the Evaluation API and validate your API integration in Sandbox.

## Step 1: Collect and submit identity data

Your application must collect the required fields before initiating the workflow.

### Collect required input

**Minimum required**
- `given_name`
- `family_name`
- `phone_number` (E.164 format)
- `address.country`

**Recommended (highest match accuracy)**
> Include all minimum required fields in addition to the fields below.
- `date_of_birth` (must be in `YYYY-MM-DD` format)
- `email`
- `address.line_1`
- `address.locality` (city)
- `address.major_admin_division` (region/state)
- `address.postal_code`
> 👍
> **Tip**:
> Adding additional personally identifiable information (PII) can improve match accuracy.

## Step 2: Create an evaluation

Send a `POST` request to the [Evaluation endpoint](https://help.socure.com/riskos/reference/postevaluation) using your DocV + Watchlist workflow. This request starts the evaluation and triggers document verification.

### Endpoint
Start with **Sandbox** for development and testing, then move to **Production** for live applications.
SandboxProduction
```http
POST https://riskos.sandbox.socure.com/api/evaluation
```
```http
POST https://riskos.socure.com/api/evaluation
```

### Example request

```curl
curl --request POST \
  --url "https://riskos.sandbox.socure.com/api/evaluation" \
  --header "Accept: application/json" \
  --header "Content-Type: application/json" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --data '{\n    "id": "APP-123456",\n    "timestamp": "2025-07-31T15:00:10.761Z",\n    "workflow": "docv_watchlist",\n    "data": {\n      "individual": {\n        "given_name": "John",\n        "family_name": "Smith",\n        "date_of_birth": "1989-05-07",\n        "phone_number": "+19998887777",\n        "address": {\n          "line_1": "1234 N College Ave",\n          "locality": "New York City",\n          "major_admin_division": "NY",\n          "country": "US",\n          "postal_code": "10001"\n        },\n        "docv": {\n          "config": {\n            "document_type": "license",\n            "send_message": true,\n            "language": "en-us",\n            "redirect": {\n              "method": "POST",\n              "url": "https://example.com/docv"\n            }\n          }\n        }\n      }\n    }\n  }'
```

```json
{
  "id": "APP-123456",
  "timestamp": "2025-07-31T15:00:10.761Z",
  "workflow": "docv_watchlist",
  "data": {
    "individual": {
      "given_name": "John",
      "family_name": "Smith",
      "date_of_birth": "1989-05-07",
      "phone_number": "+19998887777",
      "address": {
        "line_1": "1234 N College Ave",
        "locality": "New York City",
        "major_admin_division": "NY",
        "country": "US",
        "postal_code": "10001"
      },
      "docv": {
        "config": {
          "document_type": "license",
          "send_message": true,
          "language": "en-us",
          "redirect": {
            "method": "POST",
            "url": "https://example.com/docv"
          }
        }
      }
    }
  }
}
```

### Field definitions

| Field | Type | Required | Description | Example |
| --- | --- | --- | --- | --- |
| `id` | String | Required | Customer-defined unique identifier for the request. Must be unique per evaluation. Reuse may cause re-run behavior and impact results. | `"fb428165-6a1c-4d36-afbc-c8a946c1287d"` |
| `timestamp` | String `<Date-Time>` | Required | RFC 3339 timestamp indicating when the evaluation request was initiated. | `"2026-02-17T14:22:06.628Z"` |
| `workflow` | String | Required | Environment-specific workflow identifier from RiskOS™. | `"docv_watchlist"` |
| `data` | Object | Required | Main payload containing consumer, device, and event data. |  |
| `data.individual` | Object | Required | Primary identity object containing individual’s information. |  |
| `data.individual.given_name` | String | Required | First name. | `"John"` |
| `data.individual.family_name` | String | Required | Last name. | `"Smith"` |
| `data.individual.date_of_birth` | String | Optional | Date of birth (`YYYY-MM-DD`). | `"1989-05-07"` |
| `data.individual.phone_number` | String | Required | Phone number in E.164 format (hyphens/spaces tolerated). | `"+19998887777"` |
| `data.individual.address` | Object | Required | Consumer address object. |  |
| `data.individual.address.line_1` | String | Optional | Street address line 1. | `"1234 N College Ave"` |
| `data.individual.address.line_2` | String | Optional | Street address line 2. | `"Apt 3C"` |
| `data.individual.address.locality` | String | Optional | City. | `"New York City"` |
| `data.individual.address.major_admin_division` | String | Optional | State/province or region. | `"NY"` |
| `data.individual.address.postal_code` | String | Optional | ZIP or postal code. | `"10001"` |
| `data.individual.address.country` | String | Required | ISO 3166-1 alpha-2 country code. | `"US"` |

#### Document Verification settings

The following fields are nested under `data.individual.docv.config`. Use these optional fields to customize document verification behavior.

| Field | Type | Required | Description | Example |
| --- | --- | --- | --- | --- |
| `send_message` | Boolean | Optional | Set to `true` to send an SMS to the provided phone number with the document request URL. Defaults to `false`. | `true` |
| `language` | String | Optional | Determines Capture App [UI language](https://help.socure.com/riskos/docs/language-options). Defaults to `en-us`. | `en-us` |
| `use_case_key` | String | Optional | Deploys a specific [Capture App flow](https://help.socure.com/riskos/docs/capture-app-setup) created in RiskOS™. | `default_docv_flow` |
| `document_type` | String (Enum: `license` \\| `passport`) | Optional | Restrict the flow to a single document type. When provided, users skip the document type selection screen. | `passport` |
| `redirect.url` | String (URL) | Conditional | Destination URL to send the consumer after capture. Required if `redirect` is provided. Can include query strings for transaction tracking. | `https://example.com`<br>`/complete` |
| `redirect.method` | String (Enum: `GET` \\| `POST`) | Conditional | HTTP method used for the redirect. Required if `redirect` is provided. | `POST` |

## Step 3: Handle paused evaluation

> 📘
> **Decision Model**:
> The initial response may include `decision = REVIEW`, which indicates the evaluation is paused for Document Verification.
> This is not a final decision. The evaluation resumes automatically, and the final outcome is always `ACCEPT` or `REJECT`.

After you create an evaluation, RiskOS™ returns a response with `eval_status: "evaluation_paused"` indicating that Document Verification is required before the evaluation can complete. The response includes a `docvTransactionToken` required to launch the Capture App.

Use the response to:
- Extract the `docvTransactionToken` and `eval_id`.
- Persist both values for webhook correlation.
- Launch the DocV Capture App.

For step-up handling and SDK integration, see [Handle document verification](https://help.socure.com/riskos/docs/document-verification-watchlist-screening-handle-additional-verification).