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.

Before you start

Publish a workflow configured for Socure's hosted experience that includes a Document Request step, with decision logic that routes on the workflow decision (ACCEPT, REVIEW, REJECT).

Get your API key from the API & SDK Keys page in the RiskOS™ Dashboard. Hosted Flows needs no SDK key.

Publish a Capture App flow for your flow type.

Register a webhook endpoint to receive evaluation\_completed events for asynchronous decisions and optional case\_notes\_added events for status updates.

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.

SandboxProduction

POST https://riskos.sandbox.socure.com/api/evaluation

POST https://riskos.socure.com/api/evaluation

Include your API key as a Bearer token:

HTTP

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.

Captures a government-issued ID and a selfie. Set document_type to skip the document-selection screen, or omit it to let the consumer choose.

JSON

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

Captures supporting documents such as utility bills or bank statements (JPEG, PNG, or PDF). No selfie or facial match. Select the flow with use_case_key and omit document_type.

JSON

// ...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": {
      "use_case_key": "YOUR_SECONDARY_DOC_FLOW",
      "language": "en-us"
    }
  }
}

Captures a live selfie for age, liveness, and trust checks. Select the flow with use_case_key and omit document_type.

JSON

// ...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": {
      "use_case_key": "YOUR_SELFIE_FLOW",
      "language": "en-us"
    }
  }
}

Captures a live selfie and compares it to a prior DocV headshot. Requiresadditional_context.previous_reference_id — the reference ID of the earlier evaluation that holds the headshot.

JSON

// ...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" },
  "additional_context": {
    "previous_reference_id": "3639f9ad-e1fe-4e3e-9202-18faf20ace56"
  },
  "docv": {
    "config": {
      "use_case_key": "YOUR_REVERIFICATION_FLOW",
      "language": "en-us"
    }
  }
}

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:

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.

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

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.

TypeScript

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.

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:

Additional resources

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

Updated about 1 month ago