Submit Data for DocV + Watchlist

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 must collect the required fields before initiating the workflow.

Collect required input

Minimum required

Recommended (highest match accuracy)

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

Step 2: Create an evaluation

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

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

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 '{\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  }'

{
  "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. Defaults to en-us. en-us
use_case_key String Optional Deploys a specific Capture App flow 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.
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
/complete
redirect.method String (Enum: GET \ POST) Conditional HTTP method used for the redirect. Required if redirect is provided.

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:

For step-up handling and SDK integration, see Handle document verification.