DocV API Integration

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 retrieve the evaluation result using a GET request to /api/evaluation/{eval_id} or subscribe to webhook notifications to receive real-time updates when the DocV step is completed (for example, 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, reject, 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 finishes all remaining steps. You can receive it in two ways:

• Webhook (recommended) — subscribe to the evaluation_completed event. RiskOS™ pushes the result to your endpoint as soon as verification finishes. See DocV Webhooks for payload examples and setup instructions.
• GET request — poll or fetch the result on demand using the evaluation ID returned in the initial response.

Retrieve results with a GET request

Send a GET request to /api/evaluation/{eval_id} with your API key:

curl -X GET "https://riskos.socure.com/api/evaluation/{eval_id}" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json"

Replace {eval_id} with the eval_id value from the initial POST response (see section 1). The response contains the DocV enrichment with reason codes, extracted data, and the DocV decision.

📘

Key fields in the response:

• 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

⚠️

Important:

The documentType fields (type, country, or state) may return "Unknown" instead of a specific value. This occurs when the uploaded document type isn't supported or when the system is unable to confidently extract or classify the document information from the submitted images. Design your integration to handle "Unknown" values and avoid assuming these fields always contain a recognized document type or region.

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

Socure Pass enrichment results

Enrichment outputs are returned in the data_enrichments array. The response shape depends on which path the user took:

• Socure Pass path: A single SocurePass enrichment containing the stored verified identity data.
• Standard DocV path: Two enrichments: SocureDocRequest (session metadata) and Socure (document verification results).

📘

Important: The webhook payload differs depending on which path the user takes. If the user selects "Verify with Socure Pass," the enrichment comes from the SocurePass provider. If the user selects "Continue with Standard Verification," the enrichment comes from the standard Document Verification provider. Your integration must handle both response shapes.

How to determine which path the user took

Check the tags array or enrichment_provider field:

Socure Pass enrichment (reuse path)

Example Socure Pass webhook payload

{
  "enrichment_name": "Socure Pass",
  "enrichment_endpoint": "https://reusable-id-sandbox.webapps.us-east-1.prod.socure.link/api/proof",
  "enrichment_provider": "SocurePass",
  "status_code": 200,
  "request": {
    "account_id": "acc-ucrmplxHmx",
    "consent_id": "01KR4PQH6MRJ3RFXAHFF4MVECW",
    "eval_id": "2b74fe41-bf69-484a-82c7-4630f5846fa6"
  },
  "response": {
    "individual": {
      "address": {
        "city": "Port Spencer",
        "country": "USA",
        "line_1": "463 Mertz Motorway",
        "postal_code": "65036",
        "state": "OH"
      },
      "date_of_birth": "2000-05-01",
      "family_name": "Doe",
      "given_name": "Jane",
      "identification_documents": {
        "expiry_date": "2099-01-01",
        "issued_date": "2015-01-01",
        "issuing_country": "USA",
        "issuing_state": "NY",
        "number": "123456789",
        "type": "Drivers License"
      }
    },
    "request_id": "59762fc4-302b-9458-9b1b-2844f4c92791"
  },
  "is_source_cache": false,
  "total_attempts": 1
}

Enrichment request fields

The Socure Pass enrichment sends three identifiers to retrieve the user's verified claims.

Enrichment response fields

response.individual fields

address fields (Socure Pass)

identification_documents fields

Supported document types

Below are the document types you may encounter in identification_documents.type. Coverage and acceptance may vary by country and program.

data.custom fields

The data.custom object contains Socure Pass session identifiers for traceability and audit.

Socure Pass tags

RiskOS™ evaluations involving Socure Pass include these tags for filtering and reporting: