Submit Data for DocV

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 should collect the required fields based on your configured DocV workflow before initiating the evaluation.

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

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 API response returns a non-terminal decision (REVIEW) and pauses the evaluation 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 session must reach SESSION_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.

Retry behavior

Document Verification runs once per evaluation.

If the session does not reach SESSION_COMPLETE, expires, consent is declined, or DocV returns reject or resubmit, the evaluation results in REJECT.

To retry Document Verification, create a new evaluation.