DocV Hosted Flows Integration

Use Hosted Flows when you want a no-SDK integration. Instead of embedding a capture UI, your app redirects the consumer to Socure's hosted Capture App in a browser. The evaluation response returns a top-level redirect_uri — you send the consumer there to start capture.

This guide covers the Hosted Flows path end to end. To embed the capture UI in your own app instead, see DocV Direct API Integration.

📘

Your workflow sets the path:

You select Hosted Flows by calling a workflow configured for Socure's hosted experience (for example, docv_socure_pass) — not by a request field. That workflow returns the top-level redirect_uri you redirect the consumer to.

Before you start

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 redirect_uri you send the consumer to.

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. To bring the consumer back to your app after capture, set your callback URL in data.individual.custom.redirect_uri. Optionally set docv.config.send_message: true to text the consumer the Capture App link.

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": "docv_socure_pass",
    "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"
        },
        "custom": {
          "redirect_uri": "https://yourapp.com/callback"
        },
        "docv": {
          "config": {
            "use_case_key": "your-use-case-key",
            "document_type": "license",
            "send_message": true,
            "language": "en-us"
          }
        }
      }
    }
  }'

{
  "id": "APP-123456",
  "timestamp": "2025-07-31T15:00:10.761Z",
  "workflow": "docv_socure_pass",
  "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"
      },
      "custom": {
        "redirect_uri": "https://yourapp.com/callback"
      },
      "docv": {
        "config": {
          "use_case_key": "your-use-case-key",
          "document_type": "license",
          "send_message": true,
          "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" },
  "custom": { "redirect_uri": "https://yourapp.com/callback" },
  "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 launch asset is a top-level redirect_uri — there is no docvTransactionToken on this path.

📘

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": "docv_socure_pass",
  "eval_id": "6c3e1165-1617-4417-b759-92176c75c6e5",
  "decision": "REVIEW",
  "status": "ON_HOLD",
  "eval_status": "evaluation_paused",
  "redirect_uri": "https://riskos.sandbox.socure.com/hosted/xyz"
}

These fields confirm the workflow is waiting for capture:

The launch asset for the Hosted Flows path is the top-level redirect_uri:

📘

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 redirect_uri to launch capture. For tracking and reconciliation, persist id, eval_id, decision, status, eval_status, and workflow.

Step 3: Launch by redirecting the consumer

Send the consumer to the top-level redirect_uri to start Socure's hosted Capture App. RiskOS™ resumes the paused evaluation automatically when capture finishes.

function handleStepUp(evaluationResponse: EvaluationResponse) {
  // Hosted Flows returns a top-level redirect_uri — send the consumer there
  window.location.href = evaluationResponse.redirect_uri;

  // SMS is sent automatically when send_message is true in docv.config
}

Return the consumer to your app after capture

The callback URL you set in data.individual.custom.redirect_uri (Step 1) is where RiskOS™ sends the consumer after the Capture App completes or is canceled. Use it to return the consumer to your app's "verification in progress" screen — the final decision still arrives through the webhook, not the redirect.

For a fully hosted, no-SDK web experience, see the Hosted Flows integration guide.

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.

Related

• DocV Integration Overview
• Socure Hosted UX (Capture App)
• Language options
• Hosted Flows integration guide
• Receive DocV Results
• Evaluation API Reference