Verify Face

curl --request POST \
  --url https://api.sandbox.verisoul.ai/liveness/verify-face \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "session_id": "000fb9fc-3a12-4492-b825-6ec9916ffea7"
}
'

import requests

url = "https://api.sandbox.verisoul.ai/liveness/verify-face"

payload = { "session_id": "000fb9fc-3a12-4492-b825-6ec9916ffea7" }
headers = {
    "x-api-key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'x-api-key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({session_id: '000fb9fc-3a12-4492-b825-6ec9916ffea7'})
};

fetch('https://api.sandbox.verisoul.ai/liveness/verify-face', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.sandbox.verisoul.ai/liveness/verify-face",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'session_id' => '000fb9fc-3a12-4492-b825-6ec9916ffea7'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "x-api-key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.sandbox.verisoul.ai/liveness/verify-face"

	payload := strings.NewReader("{\n  \"session_id\": \"000fb9fc-3a12-4492-b825-6ec9916ffea7\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("x-api-key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.sandbox.verisoul.ai/liveness/verify-face")
  .header("x-api-key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"session_id\": \"000fb9fc-3a12-4492-b825-6ec9916ffea7\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.sandbox.verisoul.ai/liveness/verify-face")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["x-api-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"session_id\": \"000fb9fc-3a12-4492-b825-6ec9916ffea7\"\n}"

response = http.request(request)
puts response.read_body

{
  "metadata": {
    "project_id": "00000000-0000-0000-0000-000000000001",
    "session_id": "00022d22-0592-4c83-8f55-0ec8f277c668",
    "account_id": "john-doe-1",
    "referring_session_id": "623d80c5-5266-4787-a5b8-7cd578379de4",
    "request_id": "d4b414e2-5c18-4e8e-9426-a3b83564d6f1",
    "timestamp": "2025-05-04T22:11:51.645Z"
  },
  "decision": "Fake",
  "risk_score": 0.8,
  "risk_flags": [
    "repeat_face"
  ],
  "lists": [],
  "rules": [],
  "device_network_signals": {
    "device_risk": 0.2429,
    "proxy": 0,
    "vpn": 0,
    "datacenter": 0,
    "tor": 0,
    "spoofed_ip": 0,
    "recent_fraud_ip": 0,
    "device_network_mismatch": 0.0001,
    "location_spoofing": 0.0001
  },
  "referring_session_signals": {
    "impossible_travel": 0,
    "ip_mismatch": 0,
    "user_agent_mismatch": 0,
    "device_timezone_mismatch": 0.2501,
    "ip_timezone_mismatch": 0.0001
  },
  "photo_urls": {
    "face": "https://storage.googleapis.com/facematch-sandbox/00022d22-0592-4c83-8f55-0ec8f277c668/face.jpg"
  },
  "video_urls": [
    "https://storage.googleapis.com/facematch-sandbox/00022d22-0592-4c83-8f55-0ec8f277c668/session_video_1716500000000.webm?X-Goog-Signature=...",
    "https://storage.googleapis.com/facematch-sandbox/00022d22-0592-4c83-8f55-0ec8f277c668/session_video_1716500042000.webm?X-Goog-Signature=..."
  ],
  "session_data": {
    "true_country_code": "US",
    "network": {
      "ip_address": "107.209.253.92",
      "service_provider": "AT&T Internet",
      "connection_type": "isp"
    },
    "location": {
      "continent": "NA",
      "country_code": "US",
      "state": "Texas",
      "city": "Austin",
      "zip_code": "78758",
      "timezone": "America/Chicago",
      "latitude": 30.3773,
      "longitude": -97.71
    },
    "browser": {
      "type": "Chrome",
      "version": "135.0.0.0",
      "language": "en-US",
      "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/135.0.0.0 Safari/537.36",
      "timezone": "America/Chicago"
    },
    "device": {
      "category": "desktop",
      "type": "Mac",
      "os": "macOS 10.15.7",
      "cpu_cores": 16,
      "memory": 8,
      "gpu": "ANGLE (Apple, ANGLE Metal Renderer: Apple M4 Max, Unspecified Version)"
    }
  },
  "matches": {
    "num_accounts_linked": 1,
    "accounts_linked": [
      {
        "account_id": "john-doe-2",
        "match_types": [
          "face",
          "ip_address"
        ]
      }
    ]
  }
}

{
  "request_id": "8e3c7dd6-73e3-4e46-bbd2-a10c322f59d5",
  "success": false,
  "error": "session_not_found"
}

Authorizations

x-api-key

string

header

required

API key authentication

Body

application/json

session_id

string<uuid>

required

The session ID of a completed Face Match session

Response

Face Match completed successfully

metadata

object

Show child attributes

decision

enum<string>

Overall decision

Available options:

Fake,

Suspicious,

Real

risk_score

number<float>

Risk score where higher values indicate higher risk

Required range: 0 <= x <= 1

risk_flags

string[]

See Risk Flags for more information.

lists

string[]

Names of the lists the enrolled account is currently a member of. Membership is evaluated fresh on every call, so list changes are reflected immediately. Empty array for sessions not yet linked to an account. See Rules, Lists, and Verifications for more information.

rules

string[]

Names of the rules that have triggered for the enrolled account. Empty array for sessions not yet linked to an account.

device_network_signals

object

Show child attributes

referring_session_signals

object

Show child attributes

photo_urls

object

Show child attributes

video_urls

string<uri>[]

Signed URL to the session video

session_data

object

Show child attributes

matches

object

Show child attributes

Verify Face

curl --request POST \
  --url https://api.sandbox.verisoul.ai/liveness/verify-face \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "session_id": "000fb9fc-3a12-4492-b825-6ec9916ffea7"
}
'

import requests

url = "https://api.sandbox.verisoul.ai/liveness/verify-face"

payload = { "session_id": "000fb9fc-3a12-4492-b825-6ec9916ffea7" }
headers = {
    "x-api-key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'x-api-key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({session_id: '000fb9fc-3a12-4492-b825-6ec9916ffea7'})
};

fetch('https://api.sandbox.verisoul.ai/liveness/verify-face', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.sandbox.verisoul.ai/liveness/verify-face",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'session_id' => '000fb9fc-3a12-4492-b825-6ec9916ffea7'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "x-api-key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.sandbox.verisoul.ai/liveness/verify-face"

	payload := strings.NewReader("{\n  \"session_id\": \"000fb9fc-3a12-4492-b825-6ec9916ffea7\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("x-api-key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.sandbox.verisoul.ai/liveness/verify-face")
  .header("x-api-key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"session_id\": \"000fb9fc-3a12-4492-b825-6ec9916ffea7\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.sandbox.verisoul.ai/liveness/verify-face")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["x-api-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"session_id\": \"000fb9fc-3a12-4492-b825-6ec9916ffea7\"\n}"

response = http.request(request)
puts response.read_body

{
  "metadata": {
    "project_id": "00000000-0000-0000-0000-000000000001",
    "session_id": "00022d22-0592-4c83-8f55-0ec8f277c668",
    "account_id": "john-doe-1",
    "referring_session_id": "623d80c5-5266-4787-a5b8-7cd578379de4",
    "request_id": "d4b414e2-5c18-4e8e-9426-a3b83564d6f1",
    "timestamp": "2025-05-04T22:11:51.645Z"
  },
  "decision": "Fake",
  "risk_score": 0.8,
  "risk_flags": [
    "repeat_face"
  ],
  "lists": [],
  "rules": [],
  "device_network_signals": {
    "device_risk": 0.2429,
    "proxy": 0,
    "vpn": 0,
    "datacenter": 0,
    "tor": 0,
    "spoofed_ip": 0,
    "recent_fraud_ip": 0,
    "device_network_mismatch": 0.0001,
    "location_spoofing": 0.0001
  },
  "referring_session_signals": {
    "impossible_travel": 0,
    "ip_mismatch": 0,
    "user_agent_mismatch": 0,
    "device_timezone_mismatch": 0.2501,
    "ip_timezone_mismatch": 0.0001
  },
  "photo_urls": {
    "face": "https://storage.googleapis.com/facematch-sandbox/00022d22-0592-4c83-8f55-0ec8f277c668/face.jpg"
  },
  "video_urls": [
    "https://storage.googleapis.com/facematch-sandbox/00022d22-0592-4c83-8f55-0ec8f277c668/session_video_1716500000000.webm?X-Goog-Signature=...",
    "https://storage.googleapis.com/facematch-sandbox/00022d22-0592-4c83-8f55-0ec8f277c668/session_video_1716500042000.webm?X-Goog-Signature=..."
  ],
  "session_data": {
    "true_country_code": "US",
    "network": {
      "ip_address": "107.209.253.92",
      "service_provider": "AT&T Internet",
      "connection_type": "isp"
    },
    "location": {
      "continent": "NA",
      "country_code": "US",
      "state": "Texas",
      "city": "Austin",
      "zip_code": "78758",
      "timezone": "America/Chicago",
      "latitude": 30.3773,
      "longitude": -97.71
    },
    "browser": {
      "type": "Chrome",
      "version": "135.0.0.0",
      "language": "en-US",
      "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/135.0.0.0 Safari/537.36",
      "timezone": "America/Chicago"
    },
    "device": {
      "category": "desktop",
      "type": "Mac",
      "os": "macOS 10.15.7",
      "cpu_cores": 16,
      "memory": 8,
      "gpu": "ANGLE (Apple, ANGLE Metal Renderer: Apple M4 Max, Unspecified Version)"
    }
  },
  "matches": {
    "num_accounts_linked": 1,
    "accounts_linked": [
      {
        "account_id": "john-doe-2",
        "match_types": [
          "face",
          "ip_address"
        ]
      }
    ]
  }
}

{
  "request_id": "8e3c7dd6-73e3-4e46-bbd2-a10c322f59d5",
  "success": false,
  "error": "session_not_found"
}

API Documentation

Session

Account

Lists

Phone

Email Intelligence API

Face Match

ID Check

Types

Verify Face

Authorizations

Body

Response