DocV Direct API Integration

Use the SDK path when you want to embed Socure's document capture UI directly in your app — most mobile and web onboarding flows. Your app launches the SDK with a docvTransactionToken from the evaluation response, and the SDK guides the consumer through document and selfie capture.

This guide covers the SDK path end to end. For the fully hosted, no-SDK alternative, see Integrate DocV with Hosted Flows.

📘

Your workflow sets the path:

You select the SDK path by calling a workflow configured for the SDK — not by a request field. That workflow returns the docvTransactionToken your app passes to the SDK.

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.

Step 1: Create the 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 and authentication

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

Include your API key as a Bearer token:

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": {
            "use_case_key": "your-use-case-key",
            "document_type": "license",
            "language": "en-us"
          }
        }
      }
    }
  }'

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

Configure by DocV product

DocV supports four flow types. They share the same PII fields described earlier in this topic, but each requires different docv configuration, and the result returns a different enrichment object. You select the flow with the use_case_key from your published Capture App flow — the rest of the request changes as shown in the following tabs.

// ...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"
    }
  }
}

📘

The result enrichment object varies by flow:

The final decision payload nests the DocV result under a flow-specific key — documentVerification, secondaryDocument, selfieIntelligence, or selfieReverification. Parse the object that matches the flow you ran. See Receive DocV Results.

Request fields

Minimum required for DocV: given_name, family_name, phone_number (E.164), and address.country. Add date_of_birth, email, and the remaining address fields for the highest match accuracy.

Top-level fields (path: root request object)

Individual fields (path: data.individual)

Address fields (path: data.individual.address)

Predictive 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:

📘

Note:

For the complete field schema, see the Evaluation API Reference.

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.

📘

This response is non-terminal:

The REVIEW decision is not the final outcome — the evaluation resumes automatically after capture and resolves to ACCEPT or REJECT. Do not route the consumer on this response.

{
  "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"
        },
        "referenceId": "3639f9ad-e1fe-4e3e-9202-18faf20ace56"
      }
    }
  ]
}

These fields confirm the workflow is waiting for capture:

The launch asset for the SDK path is the docvTransactionToken:

📘

Persist the launch asset and the eval_id:

Store the eval_id in your backend to match the result webhook to this evaluation. Also store the docvTransactionToken to launch capture. For tracking and reconciliation, persist id, eval_id, decision, status, eval_status, and workflow.

Step 3: Launch the SDK

For consumers capturing on a device with a camera — most mobile and web onboarding flows — embed a DocV SDK. Socure offers native SDKs for iOS, Android, and React Native, plus a Web SDK for browser-based flows. Each renders Socure's built-in capture UI, guides the consumer through document and selfie capture, and handles image upload. RiskOS™ then resumes the paused evaluation automatically.

At launch, pass the SDK two values:

• 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 for each platform, see the DocV SDK documentation.

📘

The SDK does not return a decision:

The SDK is a client-side handoff step only. Your backend still creates the evaluation and receives the final decision by webhook. Once capture launches, the consumer completes it without further backend interaction — RiskOS™ automatically resumes the paused evaluation when capture finishes or the session expires.

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

Document Verification runs once per evaluation. If the capture session does not reach SESSION_COMPLETE — it expires, the consumer declines consent, or DocV returns reject or resubmit — the evaluation resolves to REJECT. To retry Document Verification, create a new evaluation.

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.

FAQs

Related

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