Submit Data for DocV

Before you start

Get your API key and SDK key from the API & SDK Keys page in the RiskOS™ Dashboard.

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

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

Recommended (highest match accuracy)

Include all minimum required fields in addition to the fields below.

👍
Tip: Adding additional personally identifiable information (PII) can improve match accuracy.

Step 2: Create an evaluation

Send a POST request to the Evaluation endpoint 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

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

Production

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

Example request

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"
            }
          }
        }
      }
    }
  }'

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