API Integration

Socure Predictive Document Verification API integration guide

This guide walks you through how to integrate with Socure’s /api/evaluation endpoint using any of the following Predictive Document Verification enrichments:

• Document Verification
• Secondary Document Capture
• Selfie Intelligence
• Selfie Reverification

When you call the /api/evaluation endpoint, RiskOS™ will initiate the request through your configured workflow. When the workflow reaches the Document Request step, RiskOS™ pauses the workflow execution and returns a verification link, QR code, or token for launching the Capture App. After the user completes capture, the workflow continues automatically to Document Verification and subsequent enrichment steps.

Before you start

Make sure your RiskOS™ environment is provisioned with:

Postman Collection

The following Postman collection can be used to test the DocV enrichment with the Evaluation endpoint.

Choose your environment

Start with Sandbox for development and testing, then move to Production for live applications.

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

Get an API key

How it works

1. Send a POST request to the /api/evaluation endpoint with the required identity data and a device session token (from the Digital Intelligence SDK).
2. Socure runs the request through your configured RiskOS™ workflow with the DocV enrichment. The system generates a transaction and provides a link or token for the user to complete the document and selfie capture process via the DocV Capture App (web or mobile).
3. The user is guided through capturing and uploading images of their government-issued ID and a selfie. The Capture App validates image quality and uploads the images to Socure for verification.
4. DocV is asynchronous. You must either poll the evaluation status using the PATCH Evaluation API or subscribe to webhook notifications to receive real-time updates when the DocV step is completed (e.g., ACCEPT, REJECT, or additional action required).
5. Once verification is complete, you receive the final evaluation result, including the DocV decision and any enriched identity data. Use this information to approve, decline, or further review the user, and to auto-populate forms or accelerate your onboarding workflow.

Start a new evaluation

Endpoint

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

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

Authentication and headers

Include your API key in the Authorization header as a Bearer token, along 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

{
  "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": {
          "document_type": "license",
          "send_message": true,
          "language": "en-us",
          "redirect": {
            "method": "POST",
            "url": "https://example.com/docv"
          }
        }
      }
    }
  }
}

curl --location --request POST 'https://riskos.sandbox.socure.com/api/evaluation' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --data-raw '{
    "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": {
            "document_type": "license",
            "send_message": true,
            "language": "en-us",
            "redirect": {
              "method": "POST",
              "url": "https://example.com/docv"
            }
          }
        }
      }
    }
  }'

Request schema

Top-level fields

individual fields

While not required, including personally identifiable information (PII) is strongly encouraged. Providing PII supports consent audits and consumer data requests, and it also improves match accuracy and overall verification performance.

address fields

docv fields

additional_context fields

1. Workflow paused — Handoff details

Example Response

This response is returned when the workflow reaches Document Request. Use the URL/QR/token to launch the Capture App and hand the user off to DocV.

📘

How it works*:

• data_enrichments.response.data.url → Capture App link
• data_enrichments.response.data.qrCode → Base64 PNG for QR handoff
• data_enrichments.response.data.docvTransactionToken → transaction token (store for later correlation)
• status: "ON_HOLD" / eval_status: "evaluation_paused" → the workflow is paused waiting for user capture

{
  "id": "APP-123456",
  "workflow": "consumer_onboarding",
  "workflow_id": "7164c67b-293d-44cb-816d-8f5478ea070c",
  "workflow_version": "2.10.0",
  "eval_source": "API",
  "eval_id": "d48bcc0e-ab3c-43a4-b03e-67208458ec62",
  "eval_start_time": "2025-08-25T18:55:25.061977405Z",
  "eval_end_time": "2025-08-25T18:55:25.687337879Z",
  "decision": "REVIEW",
  "decision_at": "2025-08-25T18:55:25.687347933Z",
  "status": "ON_HOLD",
  "sub_status": "",
  "tags": [],
  "notes": "",
  "review_queues": ["Default Queue"],
  "data_enrichments": [
    {
      "enrichment_name": "Socure Document Request - Default Flow",
      "enrichment_endpoint": "https://service.socure.com/api/5.0/documents/request",
      "enrichment_provider": "SocureDocRequest",
      "status_code": 200,
      "request": {
        "city": "New York City",
        "config": {
          "documentType": "license",
          "language": "en-us",
          "redirect": {
            "method": "POST",
            "url": "https://example.com/docv"
          },
          "sendMessage": true
        },
        "country": "US",
        "dob": "1989-05-07",
        "firstName": "John",
        "mobileNumber": "+1999888777",
        "physicalAddress": "1234 N College Ave",
        "state": "NY",
        "surName": "Smith",
        "zip": "10001"
      },
      "response": {
        "data": {
          "docvTransactionToken": "1e89eec0-f7a3-4210-b74b-a76bc9556c50",
          "eventId": "1e89eec0-f7a3-4210-b74b-a76bc9556c50",
          "qrCode": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAZoAAAGaCAIAAAC5ZBI0AAALlklE... (truncated)",
          "url": "https://verify.socure.com/#/dv/1e89eec0-f7a3-4210-b74b-a76bc9556c50"
        },
        "referenceId": "3639f9ad-e1fe-4e3e-9202-18faf20ace56"
      },
      "is_source_cache": false,
      "total_attempts": 1
    }
  ],
  "eval_status": "evaluation_paused",
  "environment_name": "Sandbox"
}

Response schema

Top-level fields

data_enrichments fields

request fields

response fields

2. Post‑verification — completed with DocV results

This response is returned after the user completes the Capture App process and the workflow completes all remaining steps. This response can be received through the evaluation_complete webhook or through a GET request to the /api/evaluation endpoint. You’ll see the DocV enrichment with reason codes, extracted data, and the DocV decision.

📘

How it works:

• data_enrichments.response.documentVerification.decision.value → DocV result (accept, review, resubmit, reject)
• data_enrichments.response.documentVerification.reasonCodes → explanations/flags
• data_enrichments.response.documentVerification.documentData → extracted fields (e.g., DOB, document number)
• Top‑level decision + routing metadata → use for your workflow handling and for the overall workflow decision

Example response

When you call the Evaluation API, RiskOS™ returns a JSON payload that includes the final decision, evaluation metadata, and enrichment-specific results.

{
  "id": "APP-123456",
  "eval_id": "6dc8f39c-ecc3-4fe0-9283-fc8e5f99e816",
  "decision": "REVIEW",
  "tags": [],
  "review_queues": [],
  "data_enrichments": [
    {
      "enrichment_name": "Socure DocV",
      "enrichment_endpoint": "https://sandbox.dev.socure.com/api/3.0/EmailAuthScore",
      "enrichment_provider": "Socure",
      "status_code": 200,
      "request": { ... },
      "response": {
        "referenceId": "a1234b56-e789-0123-4fga-56b7c890d123",
        "documentVerification": {
          "reasonCodes": [
            "I834",
            "I823",
            "I826",
            "I845",
            "I820",
            "R831",
            "I838",
            "R836",
            "I824",
            "I822"
          ],
          "documentType": {
            "type": "Drivers License",
            "country": "USA",
            "state": "NY"
          },
          "decision": {
            "name": "standard",
            "value": "reject"
          },
          "documentData": {
            "firstName": "John",
            "surName": "Smith",
            "fullName": "John Smith",
            "address": "32194 N College Ave, New York City, NY 10001",
            "parsedAddress": {
              "physicalAddress": "32194 N College Ave",
              "physicalAddress2": "New York City NY 10001",
              "city": "New York City",
              "state": "NY",
              "country": "US",
              "zip": "10001"
            },
            "documentNumber": "00000000",
            "dob": "1989-05-07",
            "issueDate": "2021-01-12",
            "expirationDate": "2029-05-07",
            "barcode": {
              "firstName": "John",
              "surName": "Smith",
              "complianceType": "F",
              "licenseClass": "C"
            }
          }
        }
      }
    }
  ]
}

Key response fields

RiskOS™ returns a consistent set of top-level fields that describe the outcome of an evaluation, along with enrichment-specific results that depend on your workflow configuration.

Where to find specific results

Decision and routing (primary control signals)

Use these fields to determine what action your application should take.

decision values are workflow-specific and may differ from the examples shown in this guide.

Evaluation lifecycle and status

These fields describe where the evaluation is in its lifecycle and are useful for monitoring and asynchronous workflows.

Identifiers and traceability

Use these fields to correlate requests, logs, webhooks, and support cases.

Execution context

These fields provide timing and environment context for the evaluation.

Enrichment results

Enrichment outputs are returned in the data_enrichments array.

documentVerification fields

👍

Tip:

reasonCodes are machine-readable flags that explain why a decision occurred (e.g., data mismatches, capture issues, authenticity checks). They appear under the DocV enrichment response and are intended for routing, UX, and review workflows.

Where you’ll see them

• data_enrichments.response.documentVerification.reasonCodes

How to use them

• Drive resubmission UX (e.g., prompt for glare removal if an image quality code is present).
• Route to manual review when authenticity or data consistency codes indicate risk.
• Log for audit and analytics.

The full catalog of reason codes and their descriptions is available in your Socure documentation/console or in the reason code list.

documentType

Supported document types

Below are the document types you may encounter in documentVerification.documentType and when configuring capture flows. Coverage and acceptance may vary by country and program.

decision

📘

Note:

DocV responses are recommendations only. They are intended to inform your decisioning process and should be integrated into your organization’s broader risk strategy.

documentData

The documentData object contains the extracted data from OCR, barcode, or MRZ.

📘

Note:

If DocV cannot extract sufficient information due to poor image quality or unreadable fields, the documentData object will not be present, and the decision will be resubmit.

parsedAddress fields

barcode fields