For AI agents: visit https://help.socure.com/llms.txt for an index of all pages formatted in Markdown and endpoints in OpenAPI.

Use the **SDK** path when you want to embed Socure's document capture UI directly in your app — most mobile and web onboarding flows. Your app launches the SDK with a `docvTransactionToken` from the evaluation response, and the SDK guides the consumer through document and selfie capture.

This guide covers the SDK path end to end. For the fully hosted flow, see [Integrate DocV with Hosted Flows](https://help.socure.com/riskos/docs/docv-hosted-flows-integration).

## Before you start

[Publish a workflow](https://help.socure.com/riskos/docs/workflows) configured for the SDK that includes a **Document Request** step, with decision logic that routes on the workflow decision (`ACCEPT`, `REVIEW`, `REJECT`).

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. The SDK path needs both.

Publish a [Capture App flow](https://help.socure.com/riskos/docs/capture-app-setup) for your flow type.

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

## Test with Postman

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

## Step 1: Create the evaluation

Submit consumer data to the RiskOS™ Evaluation API. Because your workflow contains a Document Request step, RiskOS™ pauses the evaluation and returns the `docvTransactionToken` your app uses to launch capture.

### Endpoint and authentication

Start with **Sandbox** for development and testing, then move to **Production** for live applications.

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

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

Include your API key as a Bearer token:

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

Send the consumer's PII and your `docv.config` capture settings. The SDK path does **not** use `data.individual.custom.redirect_uri` — that field is for Hosted Flows.

```json
{
  "id": "APP-123456",
  "timestamp": "2025-07-31T15:00:10.761Z",
  "workflow": "consumer_onboarding",
  "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": {
          "use_case_key": "your-use-case-key",
          "document_type": "license",
          "language": "en-us"
        }
      }
    }
  }
}
```

### Configure by DocV product

DocV supports four [flow types](https://help.socure.com/riskos/docs/docv-integration-guide#supported-flow-types). They share the same PII fields described earlier in this topic, but each requires different `docv` configuration, and the result returns a different enrichment object. You select the flow with the `use_case_key` from your published [Capture App flow](https://help.socure.com/riskos/docs/capture-app-setup) — the rest of the request changes as shown in the following tabs.

| Flow type | Distinguishing request fields | Result enrichment object |
| --- | --- | --- |
| **[Document Verification](https://help.socure.com/riskos/docs/document-verification-setup)** | `config.document_type` (`license` \| `passport`) to skip the selection screen | `documentVerification` |
| **[Secondary Document Capture](https://help.socure.com/riskos/docs/secondary-doc-setup)** | `config.use_case_key` for a secondary-document flow; no `document_type` | `secondaryDocument` |
| **[Selfie Intelligence](https://help.socure.com/riskos/docs/selfie-intelligence-setup)** | `config.use_case_key` for a selfie flow; no `document_type` | `selfieIntelligence` |
| **[Selfie Reverification](https://help.socure.com/riskos/docs/selfie-reverification-setup)** | `config.use_case_key` **and**`additional_context.previous_reference_id` | `selfieReverification` |

Captures a government-issued ID and a selfie. Set `document_type` to skip the document-selection screen, or omit it to let the consumer choose.

Captures supporting documents such as utility bills or bank statements (JPEG, PNG, or PDF). No selfie or facial match. Select the flow with `use_case_key` and omit `document_type`.

Captures a live selfie for age, liveness, and trust checks. Select the flow with `use_case_key` and omit `document_type`.

Captures a live selfie and compares it to a prior DocV headshot. **Requires**`additional_context.previous_reference_id` — the reference ID of the earlier evaluation that holds the headshot.

### Request fields

**Minimum required for DocV:**`given_name`, `family_name`, `phone_number` (E.164), and `address.country`. Add `date_of_birth`, `email`, and the remaining address fields for the highest match accuracy.

**Top-level fields** (path: root request object)

| Field | Type | Required | Description | Example |
| --- | --- | --- | --- | --- |
| `id` | String | Required | Customer-defined unique identifier for the request. Must be unique per evaluation — reusing an ID causes RiskOS™ to treat the request as a re-run and can affect results. | `"APP-123456"` |
| `timestamp` | String `<Date-Time>` | Required | RFC 3339 timestamp indicating when the evaluation request was initiated. | `"2025-07-31T15:00:10.761Z"` |
| `workflow` | String | Required | Environment-specific workflow identifier from RiskOS™. Must identify a single active workflow. | `"consumer_onboarding"` |
| `data.ip_address` | String | Optional | Client IP address (IPv4/IPv6). Used for device intelligence. | `"1.2.3.4"` |

**Individual fields** (path: `data.individual`)

| Field | Type | Required | Description | Example |
| --- | --- | --- | --- | --- |
| `transaction_token` | String | Conditional | Used to link an evaluation to an existing Document Request session. Use when you already have a DocV transaction and want the Evaluation call to continue or associate with that existing DocV flow, rather than starting from scratch. | `"1e89eec0-f7a3-4210-b74b-a76bc9556c50"` |
| `given_name` | String | Required | Consumer's first/given name. | `"John"` |
| `family_name` | String | Required | Consumer's last/family name. | `"Smith"` |
| `date_of_birth` | String | Optional | Date of birth in ISO 8601 format (`YYYY-MM-DD`). | `"1989-05-07"` |
| `phone_number` | String | Required | Phone number. The API expects **E.164 format** but tolerates hyphens and spaces. | `"+19998887777"` |
| `email` | String | Optional | Consumer's email address. | `"john.smith@example.com"` |
| `additional_context` | Object | Optional | Passes additional data required by specific Socure products. | `{ "previous_reference_id": "…" }` |

**Address fields** (path: `data.individual.address`)

| Field | Type | Required | Description | Example |
| --- | --- | --- | --- | --- |
| `line_1` | String | Optional | The first line of the consumer's address. | `"1234 N College Ave"` |
| `line_2` | String | Optional | An optional second line, such as apartment or suite number. | `"Apt 4B"` |
| `locality` | String | Optional | City, town, or village where the consumer resides. | `"New York City"` |
| `major_admin_division` | String | Optional | State, province, or region (ISO 3166-2). | `"NY"` |
| `postal_code` | String | Optional | ZIP, postal code, or equivalent regional identifier. | `"10001"` |
| `country` | String | Required | Country in **ISO 3166-1 alpha-2 country code** format. | `"US"` |

**Predictive DocV fields** (path: `data.individual.docv`)

DocV behavior is configured server-side through the `docv` object and its nested `config` object. All fields are optional or conditional:

| Field | Type | Required | Description | Example |
| --- | --- | --- | --- | --- |
| `transaction_token` | String | Conditional | Transaction token from the Document Request API response (v5). Use this if integrated with Socure's DocV solution. | `"1e89eec0-f7a3-4210-b74b-a76bc9556c50"` |
| `config` | Object | Optional | Configuration options controlling Capture App behavior and the document verification flow. | `{ "document_type": "license" }` |
| `config.document_type` | String (`license` \| `passport`) | Optional | Restrict capture to a single type to skip the document selection screen. | `"license"` |
| `config.use_case_key` | String | Optional | Deploy a specific [Capture App flow](https://help.socure.com/riskos/docs/capture-app-setup). Defaults to your account's default flow. | `"your-use-case-key"` |
| `config.send_message` | Boolean | Optional | Set to `true` to send the consumer an SMS with the document request URL. Defaults to `false`. Sent from short code 33436 in the US & Canada; from +1 (510) 330-19xx in other countries. | `false` |
| `config.language` | String | Optional | Capture App [UI language](https://help.socure.com/riskos/docs/language-options). Defaults to `en-us`. | `"en-us"` |
| `config.redirect.url` | String (URL) | Conditional | Destination URL the Capture App sends the consumer to after capture completes or is canceled. Required if `redirect` is provided. | `"https://www.example.com"` |
| `config.redirect.method` | String (`GET` \| `POST`) | Conditional | HTTP method for the redirect. Required if `redirect` is provided. | `"GET"` |
| `config.transaction_token` | String | Conditional | Used primarily in Sandbox testing to indicate the expected decision outcome. Required when simulating test results. See [Test Your Integration](https://help.socure.com/riskos/docs/docv-test-integration). | `"SOC32671365"` |

#### Additional context fields

Path: `data.individual.additional_context`

The `additional_context` object passes extra data required by specific Socure products and flows:

| Field | Type | Required | Description | Example |
| --- | --- | --- | --- | --- |
| `driver_license` | String | Optional | Driver's license number. | `"000000000"` |
| `driver_license_state` | String | Optional | Two-letter issuing state code. | `"NY"` |
| `previous_reference_id` | String (UUID) | Conditional | Reference to a prior evaluation. Required when using the Selfie Reverification enrichment. | `"3639f9ad-e1fe-4e3e-9202-18faf20ace56"` |

## Step 2: Handle the paused response

When the workflow reaches the Document Request step, RiskOS™ pauses the evaluation and returns `decision: "REVIEW"`, `status: "ON_HOLD"`, and `eval_status: "evaluation_paused"`. The `docvTransactionToken` is returned inside `data_enrichments`, under the `SocureDocRequest` enrichment.

### Request fields

```json
{
  "id": "APP-123456",
  "workflow": "consumer_onboarding",
  "eval_id": "d48bcc0e-ab3c-43a4-b03e-67208458ec62",
  "decision": "REVIEW",
  "status": "ON_HOLD",
  "eval_status": "evaluation_paused",
  "data_enrichments": [
    {
      "enrichment_provider": "SocureDocRequest",
      "status_code": 200,
      "response": {
        "data": {
          "docvTransactionToken": "1e89eec0-f7a3-4210-b74b-a76bc9556c50"
        },
        "referenceId": "3639f9ad-e1fe-4e3e-9202-18faf20ace56"
      }
    }
  ]
}
```

These fields confirm the workflow is waiting for capture:

| Field | Value | Meaning |
| --- | --- | --- |
| `eval_id` | UUID | The evaluation identifier. **Persist this** — you need it to correlate the result webhook. |
| `decision` | `REVIEW` | The workflow is paused, not finished. Do not treat this as a final decision. |
| `status` | `ON_HOLD` | The evaluation is held, waiting for the consumer to complete capture. |
| `eval_status` | `evaluation_paused` | Confirms the pause at the Document Request step. |

The launch asset for the SDK path is the `docvTransactionToken`:

| Field | Location | Description |
| --- | --- | --- |
| `docvTransactionToken` | `data_enrichments[n].response.data` (`SocureDocRequest`) | Pass this to the SDK with your SDK key to start capture. |

## Step 3: Launch the SDK

For consumers capturing on a device with a camera — most mobile and web onboarding flows — embed a DocV SDK. Socure offers native SDKs for iOS, Android, and React Native, plus a Web SDK for browser-based flows. Each renders Socure's built-in capture UI, guides the consumer through document and selfie capture, and handles image upload. RiskOS™ then resumes the paused evaluation automatically.

At launch, pass the SDK two values:

- `docvTransactionToken` — from the evaluation response (`data_enrichments[n].response.data.docvTransactionToken`).
- Your **SDK key** — from the [RiskOS™ Dashboard](https://riskos.sandbox.socure.com/developers/key-management).

## Step 4: Receive the result

Once capture finishes, RiskOS™ resumes the evaluation and delivers the final `ACCEPT`, `REVIEW`, or `REJECT` decision through the `evaluation_completed` webhook. You can also retrieve the result with a GET request using the `eval_id` you persisted in Step 2.

## Retry behavior

Document Verification runs **once per evaluation**. If the capture session does not reach `SESSION_COMPLETE` — it expires, the consumer declines consent, or DocV returns `reject` or `resubmit` — the evaluation resolves to `REJECT`. To retry Document Verification, create a new evaluation.