Submit Data for DocV + Watchlist

Before you start

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

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

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

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

Document Verification settings

The following fields are nested under data.individual.docv.config. Use these optional fields to customize document verification behavior.

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:

• Extract the docvTransactionToken and eval_id.
• Persist both values for webhook correlation.
• Launch the DocV Capture App.

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