DocV Webhook Payload Reference

This page documents the fields in the DocV webhook payloads delivered on evaluation_completed. Use it to look up a specific object — you don't need to read it end to end. For how to subscribe to webhooks and act on the decision, see Receive Results with DocV Webhooks.

Payload structure

Every evaluation_completed webhook wraps the evaluation in a four-key envelope. The evaluation details — including the final decision, tags, and enrichment results — are nested under data. The data.data_enrichments array holds the per-flow verification output documented in the rest of this page.

{
  "event_id": "336ccd2a-b3a8-49a8-b2cc-89a4ae90feeb",
  "event_at": "2025-08-27T16:16:23.104744158Z",
  "event_type": "evaluation_completed",
  "data": {
    "id": "test-1245",
    "workflow": "consumer_onboarding",
    "eval_id": "8770e076-f568-48a9-8201-dca13087e592",
    "decision": "ACCEPT",
    "status": "CLOSED",
    "sub_status": "Approved",
    "tags": ["DocV Accept"],
    "evaluation_status": "evaluation_completed",
    "review_queues": [],
    "data_enrichments": [
      { "...": "Per-flow verification output — see Enrichment results below." }
    ]
  }
}

Top-level fields

data fields

📘

Two decision values, two formats:

The envelope data.decision is the final routing decision in uppercase (ACCEPT, REJECT, REVIEW). The DocV enrichment result has its own decision.value in lowercase (accept, reject, resubmit, review) that describes only the document analysis. Route on data.decision.

data.custom fields

The data.custom object contains Socure Pass session identifiers for traceability and audit. It is present when the evaluation runs a Socure Pass flow.

data.tags

The data.tags array carries labels for filtering and reporting. Evaluations involving Socure Pass include the following tags:

Enrichment results

Enrichment outputs are returned in the data.data_enrichments array.

documentVerification fields

👍

Tip:

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

How to use them:

• Drive resubmission UX (for example, 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 the reason code list.

documentType fields

⚠️

Handle "Unknown" values:

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 cannot 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

These 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 fields

📘

Recommendations only:

DocV responses are recommendations only. They inform your decision-making process and fit into your organization's broader risk strategy.

documentData fields

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

📘

Missing documentData:

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

parsedAddress fields

barcode fields

Example standard Document Verification webhook payload

This example shows a complete evaluation_completed payload for the standard Document Verification path, with the documentVerification result nested under data.data_enrichments[].response.

{
  "event_id": "a4c92f1e-8b3d-4a17-9c5e-f2d8e7b61a03",
  "event_at": "2025-08-27T16:16:23.104744158Z",
  "event_type": "evaluation_completed",
  "data": {
    "id": "test-1245",
    "workflow": "consumer_onboarding",
    "eval_id": "8770e076-f568-48a9-8201-dca13087e592",
    "decision": "ACCEPT",
    "status": "CLOSED",
    "sub_status": "Approved",
    "tags": ["Document Verification Triggered", "DocV Accept"],
    "evaluation_status": "evaluation_completed",
    "review_queues": [],
    "data_enrichments": [
      {
        "enrichment_name": "Socure DocV",
        "enrichment_endpoint": "https://service.socure.com/api/5.0/documents/verify",
        "enrichment_provider": "Socure",
        "status_code": 200,
        "is_source_cache": false,
        "total_attempts": 1,
        "error_message": "",
        "request": {},
        "response": {
          "documentVerification": {
            "reasonCodes": ["<reason_code>", "<reason_code>"],
            "documentType": {
              "type": "Drivers License",
              "country": "US",
              "state": "NY"
            },
            "decision": {
              "name": "lenient",
              "value": "accept"
            },
            "documentData": {
              "firstName": "John",
              "surName": "Smith",
              "fullName": "John Smith",
              "dob": "1989-05-07",
              "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",
              "issueDate": "2021-01-12",
              "expirationDate": "2029-05-07"
            }
          }
        }
      }
    ]
  }
}

secondaryDocument fields

When the evaluation runs a Secondary Document Capture flow, the result is nested under data_enrichments[].response.secondaryDocument instead of documentVerification.

secondaryDocument.decision fields

documents fields

Each object in the documents array describes one uploaded file.

document fields

The document object contains parsed data extracted from a single secondary document.

document.userData fields

Socure Pass enrichment results

Enrichment outputs are returned in the data_enrichments array. The response shape depends on which path the consumer 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).

📘

Handle both response shapes:

The webhook payload differs depending on which path the consumer takes. If the consumer selects "Verify with Socure Pass," the enrichment comes from the SocurePass provider. If the consumer 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 consumer 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 consumer's verified claims.

Enrichment response fields

response.individual fields

address fields (Socure Pass)

identification_documents fields

identification_documents.type uses the same values listed under Supported document types in the documentType fields section. Socure Pass commonly returns Drivers License, Identification Card, Passport, or Passport Card.

The Socure Pass session identifiers (data.custom) and the Socure Pass tags (data.tags) are top-level data fields, documented under Payload structure.

Related references

• Receive Results with DocV Webhooks
• API Reference