DocV Integration

Before you start

Test with Postman

Use this Postman collection to send sample requests to the Evaluation API and validate your Direct API integration in Sandbox.

Run in Postman

Step 1: Start an 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

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

Authentication

Include your API key in the Authorization header as a Bearer token, with standard JSON headers:

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.

curl --request POST \
  --url https://riskos.sandbox.socure.com/api/evaluation \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "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": {
            "send_message": false,
            "language": "en",
            "redirect": {
              "method": "GET",
              "url": "https://www.socure.com",
            },
          }
        }
      }
    }
  }'

import os
import requests

url = "https://riskos.sandbox.socure.com/api/evaluation"
headers = {
    "Authorization": f"Bearer {os.getenv('YOUR_API_KEY')}",
    "Content-Type": "application/json"
}
payload = {
    "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"
                }
            }
        }
    }
}

response = requests.post(url, headers=headers, json=payload)
data = response.json()

// ...excerpt of the full request body — data.individual shown
"individual": {
  "given_name": "John",
  "family_name": "Smith",
  "phone_number": "+19998887777",
  "address": {
    "country": "US"
  },
  "docv": {
    "config": {
      "document_type": "license",
      "language": "en-us",
      "send_message": false,
      "redirect": {
        "method": "GET",
        "url": "https://www.socure.com"
      }
    }
  }
}

// ...excerpt of the full request body — data.individual shown
"individual": {
  "given_name": "John",
  "family_name": "Smith",
  "phone_number": "+19998887777",
  "address": {
    "country": "US"
  },
  "docv": {
    "config": {
      "use_case_key": "YOUR_SECONDARY_DOC_FLOW",
      "language": "en-us"
    }
  }
}

// ...excerpt of the full request body — data.individual shown
"individual": {
  "given_name": "John",
  "family_name": "Smith",
  "phone_number": "+19998887777",
  "address": {
    "country": "US"
  },
  "docv": {
    "config": {
      "use_case_key": "YOUR_SELFIE_FLOW",
      "language": "en-us"
    }
  }
}

// ...excerpt of the full request body — data.individual shown
"individual": {
  "given_name": "John",
  "family_name": "Smith",
  "phone_number": "+19998887777",
  "address": {
    "country": "US"
  },
  "additional_context": {
    "previous_reference_id": "3639f9ad-e1fe-4e3e-9202-18faf20ace56"
  },
  "docv": {
    "config": {
      "use_case_key": "YOUR_REVERIFICATION_FLOW",
      "language": "en-us"
    }
  }
}

Request fields

Validation rules & accuracy guidance

These rules ensure RiskOS™ has enough information to run Document Verification.

Top-level fields

Path: root request object

Individual fields

Path: data.individual

Address fields

Path: data.individual.address

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:

Additional context fields

Path: data.individual.additional_context

The additional_context object passes extra data required by specific Socure products and flows:

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.

{
  "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",
          "eventId": "bfc890ee-e999-4445-9a5f-d3ec1dd7a6d5",
          "qrCode": "data:image/png;base64, iVBOR...",
          "url": "https://verify.socure.com/#/dv/bfc890ee-e999-4445-9a5f-3ec1dd7a6d5"
        },
        "referenceId": "3639f9ad-e1fe-4e3e-9202-18faf20ace56"
      }
    }
  ]
}

These fields confirm the workflow is waiting for capture:

Response field definitions:

Step 3: Launch the Capture App

For consumers completing verification, launch DocV using the integration method that best fits your experience:

• SDK: Embed a DocV SDK in your iOS, Android, React Native, or web application. The Socure SDKs provide the built-in capture experience, guide the consumer through document and selfie capture, and handle image upload.
• Web: Redirect the consumer to a Socure-hosted verification URL to complete capture in a mobile browser. This can also be used for QR code or SMS handoff, allowing consumers to start verification on one device and complete capture on a camera-enabled mobile device.

For SDK and web integrations, RiskOS™ automatically resumes the paused evaluation when capture is completed or the session expires.

For SDK integrations, pass the following values when initializing capture:

• docvTransactionToken — from the evaluation response (data_enrichments[n].response.data.docvTransactionToken).
• Your SDK key — from the RiskOS™ Dashboard.

For installation, initialization, platform-specific setup, supported devices, and the full launch API, go to the page for your platform:

• iOS SDK
• Android SDK
• React Native SDK
• Web SDK

To compare the SDK families first, see the DocV SDK documentation.

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.

For the webhook payload, the enrichment objects returned per flow type, and how to retrieve results, see Receive DocV Results.

Retry behavior

A capture session runs once. If it does not reach SESSION_COMPLETE — it expires, the consumer declines consent, or DocV returns reject or resubmit — the evaluation resolves to REJECT. To give the consumer another attempt, both of these approaches are valid:

• Create a new evaluation (recommended). Start a fresh evaluation with a new docvTransactionToken. Each attempt is self-contained, which makes it easier to manage. To tie attempts back to the same business record, include your own external transaction ID in the id field.
• Mint a fresh docvTransactionToken within the same evaluation. Configure your workflow to re-attempt on a resubmit decision or a Session Expired event, which preserves the evaluation context and avoids re-running upstream enrichments. See Automate terminal handling.

These workflow re-attempts are separate from the targeted retakes the Capture App prompts inside a single session when an image fails a quality check. See Predictive DocV SDK FAQs.

To decide what to tell the consumer after a failure, resolve the returned reasonCodes against the reason code catalog rather than hard-coding individual values. See Reason Codes.

Error handling

If the API returns an HTTP error (4xx or 5xx), handle it before processing any evaluation logic:

For the full error schema and all error codes, see the Errors Reference.

Troubleshooting

SDK fails to start or returns "launch failed"

Invalid or expired docvTransactionToken

• Initialize the SDK with a current, unused token.
• Regenerate a new token if the previous one expired, you consumed it, or you invalidated it. A token from a completed or expired evaluation can't be reused — create a new evaluation.

Network or firewall restrictions

• The SDK must reach Socure backend services over HTTPS. Review corporate firewall and proxy rules to allow outbound HTTPS traffic.
• Ask the consumer to temporarily disable ad-blockers, VPNs, or content filters that might block SDK scripts or domains.

Verify a barcode in a single call

To verify a document barcode — the encoded data on the back of a driver's license or state ID — send the barcode payload as a base64-encoded string in the barcode_payload field on the individual's docv data. RiskOS™ verifies the barcode as part of the evaluation and returns the decision in the same response. This is the standard, recommended method for barcode verification: one call, with no separate upload step and no capture handoff, so you skip the following Steps 2–4.

This option is optional and additive — your existing two-call flow keeps working, so you can adopt the single call when convenient.

{
  "id": "APP-123456",
  "timestamp": "2025-07-31T15:00:10.761Z",
  "workflow": "consumer_onboarding",
  "data": {
    "individual": {
      "docv": {
        "barcode_payload": "<base64-encoded barcode payload>"
      }
    }
  }
}

Provide the barcode payload as a base64-encoded string — typically 300–500 bytes. Don't send image data in this field. Front, back, and selfie images are unaffected and continue through the capture flow described earlier in this topic.

FAQs

Related

• DocV Integration Overview
• Socure Hosted UX (Capture App)
• Workflows
• Choose a DocV SDK
• Receive DocV Results
• Evaluation API Reference