Sandbox Testing

Use Sandbox to simulate Predictive Document Verification (DocV) outcomes without using production data. You can optionally pass a transaction_token in your Evaluation request to force specific DocV decisions and reason codes.

📘

What this covers:

• How to call the Evaluation API in Sandbox (with or without a transaction_token) • Ready-to-use test tokens that map to specific decisions and reason codes

🚧

How Sandbox works

• Sandbox returns predefined DocV results; it does not run full production models.
• If you do not pass a transaction_token, DocV returns Accept with static fields/reason codes, regardless of the images scanned in the Capture App.
• To retrieve images in Sandbox, include the Socure Image Request enrichment and add a WAIT (10 seconds) transformation step (details below). Without the wait, downloads often return 400 "No Documents Found".

1. Get Started

RiskOS Sandbox

• Dashboard & API base: https://riskos.sandbox.socure.com
• Evaluation endpoint: https://riskos.sandbox.socure.com/api/evaluation
• Download documents: https://riskos.sandbox.socure.com/api/evaluation/{evaluation_id}/documents

Before you test, confirm your setup:

• Workflow steps (in order): Input → Document Request → Document Verification → Image Request → Decision Logic → Decision
• Flow configuration & setup: document types, selfie settings, link validity, attempts, etc. See Flow Configuration & Setup.
• Decision logic: route on documentVerification.decision.value (accept/reject/review/resubmit) and/or reason codes.
• Branding & copy: configure in Sandbox, then publish to Production. See Customize UI & Branding.

📘

Required for Sandbox image retrieval

Add a WAIT transformation (recommended 10 seconds) before the Image Request step. Without it, images may not be available yet and downloads will return 400 "No Documents Found".

2. Call the Evaluation endpoint

For the full request schema, required fields, PII recommendations, and DocV config options, see API Integration: Calling the Evaluation Endpoint.

A. Default behavior (no token)

If you omit transaction_token in Sandbox:

• DocV returns accept with static reason codes and static documentData.
• Outcome is the same regardless of uploaded images.

Minimal cURL (no token)

curl --request POST 'https://riskos.sandbox.socure.com/api/evaluation' \
  --header 'Authorization: Bearer <SANDBOX_API_KEY>' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "id": "sandbox-test-001",
    "timestamp": "2025-07-22T18:04:56Z",
    "workflow": "trust_and_safety",
    "data": {
      "individual": {
        "given_name": "Test",
        "family_name": "User",
        "date_of_birth": "1990-01-01",
        "phone_number": "+15555550123",
        "docv": {
          "config": {
            "send_message": true,
            "language": "en-us"
          }
        }
      }
    }
  }'

B. Force outcomes with transaction_token

Pass a transaction_token to simulate specific DocV decisions and reason codes.

Where to put it: data.individual.docv.transaction_token

Example (with token)

curl --request POST 'https://riskos.sandbox.socure.com/api/evaluation' \
  --header 'Authorization: Bearer <SANDBOX_API_KEY>' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "id": "sandbox-test-001",
    "timestamp": "2025-07-22T18:04:56Z",
    "workflow": "trust_and_safety",
    "data": {
      "individual": {
        "given_name": "Test",
        "family_name": "User",
        "date_of_birth": "1990-01-01",
        "phone_number": "+15555550123",
        "docv": {
          "transaction_token": "SOC75235600"
          "config": {
            "send_message": true,
            "language": "en-us"
          }
        }
      }
    }
  }'

3. Complete the Capture App steps

From the Document Request enrichment response, launch the Capture App using the URL, QR code (Base64), or the SMS (if send_message: true). Complete front/back document capture and selfie (if required by your flow).

📘

Note:

In Sandbox, image content does not change the default outcome unless you sent a transaction_token.

4. View or Retrieve Results

• Dashboard: open the evaluation in RiskOS Sandbox.

• Webhooks: subscribe to:

  • case_notes_added (DocV event webhooks) — capture progress
  • evaluation_completed — full results available See DocV Webhooks.

• Documents ZIP: GET /api/evaluation/{evaluation_id}/documents (requires WAIT 10s step + Socure Image Request enrichment).

Test Tokens (Sandbox)

Use any token below in data.individual.docv.transaction_token to simulate the listed outcome:

📘

Need more scenarios? Your Socure team can add custom Sandbox tokens for edge cases. Contact your Solutions Consultant team for more information.

What to expect in responses

• Workflow paused (handoff): At Document Request, you receive url, qrCode (Base64), and docvTransactionToken. Workflow status is ON_HOLD / evaluation_paused until capture completes.

• After capture (DocV results): The workflow continues to Document Verification:

  • documentVerification.decision.value → accept | review | resubmit | reject
  • documentVerification.reasonCodes → machine-readable flags
  • documentVerification.documentData → extracted OCR/barcode/MRZ
  • Optional digitalIntelligence (device/network), when present

• Documents ZIP: With WAIT 10s + Socure Image Request, the ZIP may include:

  • user_uploaded/document_verification/documentfrontDoc_Front_1_blob.jpg
  • user_uploaded/document_verification/documentbackDoc_Back_1_blob.jpg
  • user_uploaded/document_verification/Doc_Selfie_1_blob.jpg

Recommended Sandbox workflow (simplified)

1. Document Request → (handoff to Capture App)
2. Document Verification
3. Transformation: WAIT (10s) (Sandbox only)
4. Image Request
5. Decision / routing

Tips and troubleshooting

• 401/403: Use your Sandbox RiskOS key and Sandbox base URL.
• Always Accept: That’s expected if you omitted transaction_token. Add one from the table to simulate other outcomes.
• 400 “No Documents Found” (download): Ensure Socure Image Request enrichment exists and add the WAIT (10s) step before it. Confirm you’re hitting the Sandbox download endpoint with the correct evaluation_id.
• Workflow never completes: Verify DocV steps are present and error handling returns resubmit or cancel (tag these for easy filtering).