## 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 should collect the required fields based on your configured DocV workflow before initiating the evaluation.

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

Sandbox

```http
POST https://riskos.sandbox.socure.com/api/evaluation
```

Production

```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 '{
    "id": "APP-123456",
    "timestamp": "2025-07-31T15:00:10.761Z",
    "workflow": "docv",
    "data": {
      "ip_address": "54.86.50.139",
      "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"
            }
          }
        }
      }
    }
  }'
```

```json
{
  "id": "APP-123456",
  "timestamp": "2025-07-31T15:00:10.761Z",
  "workflow": "docv",
  "data": {
    "ip_address": "54.86.50.139",
    "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"` |
| `data` | Object | Required | Main payload containing consumer, device, and event data. |  |
| `data.ip_address` | String | Optional | Client IP address in IPv4/IPv6 format. Used for device intelligence. | `"203.0.113.42"` |
| `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.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. Defaults to `en-us`. | `"en-us"` |
| `document_type` | String (Enum: `license` \| `passport`) | Optional | Restrict the flow to a single document type. | `"passport"` |
| `redirect.url` | String (URL) | Conditional | Destination URL to send the consumer after capture. | `"https://example.com"` |
| `redirect.method` | String (Enum: `GET` \| `POST`) | Conditional | HTTP method used for the redirect. | `"POST"` |

## Step 3: Handle paused evaluation

The initial API response returns a non-terminal decision (`REVIEW`) and pauses the evaluation for Document Verification. 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 session must reach `SESSION_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.