DocV Direct API Integration

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.

Before you start

Publish a workflow 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 page in the RiskOS™ Dashboard. The SDK path needs both.

Publish a Capture App flow for your flow type.

Register a webhook endpoint 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.

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

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

Include your API key as a Bearer token:

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.

{
  "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. 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 — the rest of the request changes as shown in the following tabs.

Flow type Distinguishing request fields Result enrichment object
Document Verification config.document_type (license | passport) to skip the selection screen documentVerification
Secondary Document Capture config.use_case_key for a secondary-document flow; no document_type secondaryDocument
Selfie Intelligence config.use_case_key for a selfie flow; no document_type selfieIntelligence
Selfie Reverification config.use_case_key andadditional_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. Requiresadditional_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. 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. 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. "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

{
  "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:

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.