POST
/
liveness
/
verify-document
curl --request POST \
  --url https://api.sandbox.verisoul.ai/liveness/verify-document \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '{
  "session_id": "00009588-9835-4fb4-8173-5bf9017d945c"
}'
{
  "metadata": {
    "project_id": "00000000-0000-0000-0000-000000000001",
    "session_id": "00009588-9835-4fb4-8173-5bf9017d945c",
    "account_id": "example-account-id",
    "referring_session_id": "example-referring-session-id",
    "request_id": "c702ef50-6d8e-4276-ac68-69940d9ec002",
    "timestamp": "2025-03-16T20:17:54.460Z"
  },
  "decision": "Fake",
  "risk_score": 100,
  "risk_flags": [
    "proxy_detected",
    "datacenter_detected",
    "low_id_face_match_score",
    "repeat_id"
  ],
  "document_signals": {
    "id_age": 28,
    "face_age_estimate": "over25",
    "id_face_match_score": 0,
    "id_barcode_status": "no_barcode_specified_by_template",
    "id_face_status": "likely_original_face",
    "id_text_status": "likely_original_text",
    "is_id_digital_spoof": "likely_physical_id",
    "is_full_id_captured": "full_id_detected",
    "id_validity": "likely_authentic_id"
  },
  "device_network_signals": {
    "ip_document_country_mismatch": false,
    "device_risk": false,
    "proxy": true,
    "vpn": false,
    "datacenter": true,
    "tor": false,
    "spoofed_ip": false,
    "recent_fraud_ip": false,
    "device_network_mismatch": true
  },
  "referring_session_signals": {
    "impossible_travel": false,
    "ip_mismatch": false,
    "user_agent_mismatch": false
  },
  "document_data": {
    "template_info": {
      "document_country_code": "US",
      "document_country": "United States of America",
      "document_state": null,
      "template_type": "passport"
    },
    "user_data": {
      "first_name": "David",
      "last_name": "Williams",
      "date_of_birth": "1997-10-26",
      "date_of_expiration": "2034-01-15",
      "date_of_issue": "2024-01-16",
      "id_number": "1234567890",
      "id_number2": null,
      "address": null
    },
    "photo_urls": {
      "face": "https://storage.googleapis.com/facematch-prod/00009588...",
      "id_scan_front": "https://storage.googleapis.com/facematch-prod/00009588..."
    }
  },
  "session_data": {
    "network": {
      "ip_address": "2a09:bac3:ac1d:15e1::22e:34",
      "service_provider": "Cloudflare, Inc.",
      "connection_type": "private_relay"
    },
    "location": {
      "continent": "NA",
      "country_code": "US",
      "state": "Oklahoma",
      "city": "Vinita",
      "zip_code": "74301",
      "timezone": "America/Chicago",
      "latitude": 36.627,
      "longitude": -95.1504
    },
    "browser": {
      "type": "Mobile Safari",
      "version": "18.1.1",
      "language": "en-US",
      "user_agent": "Mozilla/5.0 (iPhone; CPU iPhone OS 18_1_1 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/18.1.1 Mobile/15E148 Safari/604.1",
      "timezone": "America/Chicago"
    },
    "device": {
      "category": "mobile",
      "type": "iPhone",
      "os": "iOS 18.1.1",
      "cpu_cores": 4,
      "memory": 0,
      "gpu": "Apple GPU"
    }
  },
  "matches": {
    "num_accounts_linked": 2,
    "accounts_linked": [
      {
        "account_id": "example-account-id-1",
        "match_types": [
          "document_name"
        ]
      },
      {
        "account_id": "example-account-id-2",
        "match_types": [
          "document_name",
          "document_number",
          "face"
        ]
      }
    ]
  }
}

Authorizations

​
x-api-key
string
header
required

API key authentication

Body

application/json
​
session_id
string
required

The session ID obtained from the /liveness/session endpoint

Response

200 - application/json
Document verification completed
​
metadata
object
​
decision
string

Overall decision (e.g., 'Fake', 'Authentic')

​
risk_score
integer

Risk score from 0 to 100, where higher values indicate higher risk

Required range: 0 <= x <= 100
​
risk_flags
string[]

See Risk Flags for more information.

​
document_signals
object

See Document Signals for more information.

​
device_network_signals
object

See Device Network Signals for more information.

​
referring_session_signals
object

See Referring Session Signals for more information.

​
document_data
object
​
session_data
object
​
matches
object

See Multi-Accounting for more information.