Verisoul Session API
The Session API from Verisoul — 4 operation(s) for session.
Work with this as data
Every API here is available over the APIs.io API and to AI agents over MCP.
MCP server
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
Tools for apis
7 MCP tools reach this
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.
Call it yourself
curl for this page
This API
curl "https://apis.io/api/v1/apis/verisoul-session-api"
All apis
curl "https://apis.io/api/v1/apis?limit=25"Discovery needs no key. Ratings and market analysis are Pro.
OpenAPI Specification
openapi: 3.2.0
info:
title: Verisoul Account Session API
description: The Verisoul API is used to integrate Verisoul into your application.
license:
name: MIT
version: 1.0.0
servers:
- url: https://api.sandbox.verisoul.ai
security:
- apiKeyAuth: []
tags:
- name: Session
paths:
/liveness/session:
get:
summary: Get Face Match Session
description: Get a new session for Face Match verification. This is the first step in the Face Match workflow.
operationId: createFaceMatchSession
tags:
- Session
parameters:
- name: referring_session_id
in: query
description: ID of a referring session, if applicable
required: false
schema:
type: string
format: uuid
- name: simulate
in: query
description: See [Simulate Face Match](/verifications/face-match/resources/simulate-face-match) for more information
required: false
schema:
type: string
responses:
'200':
description: Session created successfully
content:
application/json:
schema:
$ref: '#/components/schemas/SessionResponse'
example:
request_id: db4ad346-e8f1-46cc-922d-f89ca8fb7ac7
session_id: 00022912-cbaa-4239-a3ec-51c32fcc0fc1
'400':
description: Bad request - groups enabled on project
content:
application/json:
schema:
type: object
properties:
request_id:
type: string
format: uuid
description: Unique identifier for the request
success:
type: boolean
description: Indicates whether the request was successful
error:
type: string
enum:
- groups_enabled
description: Error code indicating the reason for failure
example:
request_id: e6f078a5-7931-4c41-ad53-1ef35a4ca762
success: false
error: groups_enabled
/session/{session_id}:
get:
description: Returns detailed information about a specific session
parameters:
- name: session_id
in: path
description: ID of the session to retrieve
required: true
schema:
type: string
responses:
'200':
description: Session information response
content:
application/json:
schema:
$ref: '#/components/schemas/SessionResponse_2'
example:
account_ids:
- john-doe
request_id: 7c1fb7c5-8e5f-43f0-b35e-56b9698dac0f
project_id: 00000000-0000-0000-0000-000000000001
session_id: 56f9a065-1583-48af-a5c4-cd5921b21a12
start_time: '2025-06-10T16:45:21.822Z'
true_country_code: US
device_id: 6yONB4zT6k2i7SXvWkwC9s
network:
ip_address: 2600:1700:261:b810:8828:f0b6:3b95:667c
service_provider: AT&T Enterprises, LLC
connection_type: isp
location:
continent: NA
country_code: US
state: Texas
city: Austin
zip_code: '78729'
timezone: America/Chicago
latitude: 30.4521
longitude: -97.7688
browser:
type: Chrome
version: 137.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/137.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)'
screen_height: 1329
screen_width: 2056
bot:
mouse_num_events: 84
click_num_events: 2
keyboard_num_events: 0
touch_num_events: 0
clipboard_num_events: 1
risk_signals:
device_risk: false
proxy: false
vpn: false
tor: false
spoofed_ip: false
datacenter: false
recent_fraud_ip: false
impossible_travel: false
device_network_mismatch: false
location_spoofing: false
risk_signal_scores:
device_risk: 0.3971
proxy: 0
vpn: 0
tor: 0
datacenter: 0
recent_fraud_ip: 0
impossible_travel: 0
device_network_mismatch: 0.0001
location_spoofing: 0
'400':
description: Session not found
content:
application/json:
schema:
$ref: '#/components/schemas/SessionError'
example:
statusCode: 400
message: Session ID not found
tags:
- Session
/session/authenticate:
post:
description: Authenticates a session with an account
parameters:
- name: accounts_linked
in: query
description: Whether to include linked accounts in the response
required: false
schema:
type: boolean
requestBody:
description: Session authentication information
content:
application/json:
schema:
$ref: '#/components/schemas/SessionAuthenticateRequest'
required: true
responses:
'200':
description: Session authentication response
content:
application/json:
schema:
$ref: '#/components/schemas/SessionAuthenticateResponse'
examples:
default:
summary: Session authentication response
value:
project_id: 00000000-0000-0000-0000-000000000001
session_id: 7fd9d3e5-a5d3-4e47-9c2a-69fd8f0e0bd7
account_id: john-doe
request_id: 055ce1fc-0219-4909-9cb4-091be9d374d6
decision: Real
account_score: 0.17
bot: 0
multiple_accounts: 0
risk_signals: 0.17
accounts_linked: 0
lists:
- us_users
session:
start_time: '2025-06-10T16:35:22.184Z'
true_country_code: US
device_id: 6yONB4zT6k2i7SXvWkwC9s
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: '78729'
timezone: America/Chicago
latitude: 30.3773
longitude: -97.71
browser:
type: Chrome
version: 137.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/137.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)'
screen_height: 1329
screen_width: 2056
bot:
mouse_num_events: 0
click_num_events: 0
keyboard_num_events: 0
touch_num_events: 0
clipboard_num_events: 0
risk_signals:
device_risk: false
proxy: false
vpn: false
tor: false
spoofed_ip: false
datacenter: false
recent_fraud_ip: false
impossible_travel: false
device_network_mismatch: false
location_spoofing: false
risk_signal_scores:
device_risk: 0.1431
proxy: 0
vpn: 0
tor: 0
datacenter: 0
recent_fraud_ip: 0
impossible_travel: 0
device_network_mismatch: 0.0001
location_spoofing: 0
account:
account:
id: john-doe
email: johndoe.example@gmail.com
metadata: {}
group: ''
num_sessions: 3
first_seen: '2025-06-10T16:35:22.184Z'
last_seen: '2025-06-10T16:35:52.018Z'
last_session: 7fd9d3e5-a5d3-4e47-9c2a-69fd8f0e0bd7
country: US
countries:
- US
unique_devices:
1_day: 1
7_day: 1
unique_networks:
1_day: 1
7_day: 1
email:
email: johndoe.example@gmail.com
disposable: false
personal: true
valid: true
domain_type: personal
email_score: 0
trust_signals:
- email_age_greater_than_5_years
- email_known_online_history
risk_signals:
- email_alias
num_account_from_domain: 156
risk_signal_average:
device_risk: 0.2266
proxy: 0
vpn: 0
tor: 0
spoofed_ip: 0
datacenter: 0
recent_fraud_ip: 0
impossible_travel: 0
device_network_mismatch: 0.0001
location_spoofing: 0
with accounts_linked:
summary: Session authentication response with linked accounts
value:
project_id: 00000000-0000-0000-0000-000000000001
session_id: 7fd9d3e5-a5d3-4e47-9c2a-69fd8f0e0bd7
account_id: john-doe-2
request_id: 055ce1fc-0219-4909-9cb4-091be9d374d6
decision: Real
account_score: 0.17
bot: 0
multiple_accounts: 0
risk_signals: 0.17
accounts_linked: 0
lists:
- us_users
session:
start_time: '2025-06-10T16:35:22.184Z'
true_country_code: US
device_id: 6yONB4zT6k2i7SXvWkwC9s
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: '78729'
timezone: America/Chicago
latitude: 30.3773
longitude: -97.71
browser:
type: Chrome
version: 137.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/137.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)'
screen_height: 1329
screen_width: 2056
bot:
mouse_num_events: 0
click_num_events: 0
keyboard_num_events: 0
touch_num_events: 0
clipboard_num_events: 0
risk_signals:
device_risk: false
proxy: false
vpn: false
tor: false
spoofed_ip: false
datacenter: false
recent_fraud_ip: false
impossible_travel: false
device_network_mismatch: false
location_spoofing: false
risk_signal_scores:
device_risk: 0.1431
proxy: 0
vpn: 0
tor: 0
datacenter: 0
recent_fraud_ip: 0
impossible_travel: 0
device_network_mismatch: 0.0001
location_spoofing: 0
account:
account:
id: john-doe
email: johndoe.example@gmail.com
metadata: {}
group: ''
num_sessions: 3
first_seen: '2025-06-10T16:35:22.184Z'
last_seen: '2025-06-10T16:35:52.018Z'
last_session: 7fd9d3e5-a5d3-4e47-9c2a-69fd8f0e0bd7
country: US
countries:
- US
unique_devices:
1_day: 1
7_day: 1
unique_networks:
1_day: 1
7_day: 1
email:
email: johndoe.example@gmail.com
disposable: false
personal: true
valid: true
domain_type: personal
email_score: 0
trust_signals:
- email_age_greater_than_5_years
- email_known_online_history
risk_signals:
- email_alias
num_account_from_domain: 156
risk_signal_average:
device_risk: 0.2266
proxy: 0
vpn: 0
tor: 0
spoofed_ip: 0
datacenter: 0
recent_fraud_ip: 0
impossible_travel: 0
device_network_mismatch: 0.0001
location_spoofing: 0
linked_accounts:
- account_id: john-doe-2
score: 1
email: john.doe2@example.com
phone: '+14155550123'
first_name: Jane
last_name: Doe
username: jane.doe
expected_countries:
- US
- CA
match_type:
- browser
- network
- email
- phone
- username
lists:
- us_users
metadata: {}
- account_id: alice-2
score: 0.17
email: alice.2@example.com
phone: '+14155550123'
first_name: Jane
last_name: Doe
username: jane.doe
expected_countries:
- US
- CA
match_type:
- network
lists:
- us_users
metadata: {}
'400':
description: Session not found or invalid request
content:
application/json:
schema:
$ref: '#/components/schemas/SessionAuthenticateError'
example:
statusCode: 400
message: Session ID not found
tags:
- Session
/session/unauthenticated:
post:
description: Evaluates a session without authentication
parameters:
- name: accounts_linked
in: query
description: Whether to include linked accounts in the response
required: false
schema:
type: boolean
requestBody:
description: Session information
content:
application/json:
schema:
$ref: '#/components/schemas/SessionUnauthenticatedRequest'
required: true
responses:
'200':
description: Session evaluation response
content:
application/json:
schema:
$ref: '#/components/schemas/SessionUnauthenticatedResponse'
examples:
default:
summary: Session evaluation response
value:
project_id: 00000000-0000-0000-0000-000000000001
session_id: 56f9a065-1583-48af-a5c4-cd5921b21a12
request_id: f1ebfd0d-334d-450e-88e8-4705dba7d611
decision: Real
account_score: 0.2233
bot: 0
multiple_accounts: 0.2053
risk_signals: 0.3018
accounts_linked: 2
lists:
- us_users
session:
start_time: '2025-06-10T16:45:21.822Z'
true_country_code: US
device_id: 6yONB4zT6k2i7SXvWkwC9s
network:
ip_address: 2600:1700:261:b810:8828:f0b6:3b95:667c
service_provider: AT&T Enterprises, LLC
connection_type: isp
location:
continent: NA
country_code: US
state: Texas
city: Austin
zip_code: '78729'
timezone: America/Chicago
latitude: 30.4521
longitude: -97.7688
browser:
type: Chrome
version: 137.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/137.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)'
screen_height: 1329
screen_width: 2056
bot:
mouse_num_events: 0
click_num_events: 0
keyboard_num_events: 0
touch_num_events: 0
clipboard_num_events: 0
risk_signals:
device_risk: false
proxy: false
vpn: false
tor: false
spoofed_ip: false
datacenter: false
recent_fraud_ip: false
impossible_travel: false
device_network_mismatch: false
location_spoofing: false
risk_signal_scores:
device_risk: 0.4024
proxy: 0
vpn: 0
tor: 0
datacenter: 0
recent_fraud_ip: 0
impossible_travel: 0
device_network_mismatch: 0.0001
location_spoofing: 0
with accounts_linked:
summary: Session evaluation response with linked accounts
value:
project_id: 00000000-0000-0000-0000-000000000001
session_id: 56f9a065-1583-48af-a5c4-cd5921b21a12
request_id: f1ebfd0d-334d-450e-88e8-4705dba7d611
decision: Real
account_score: 0.2233
bot: 0
multiple_accounts: 0.2053
risk_signals: 0.3018
accounts_linked: 2
lists:
- us_users
session:
start_time: '2025-06-10T16:45:21.822Z'
true_country_code: US
device_id: 6yONB4zT6k2i7SXvWkwC9s
network:
ip_address: 2600:1700:261:b810:8828:f0b6:3b95:667c
service_provider: AT&T Enterprises, LLC
connection_type: isp
location:
continent: NA
country_code: US
state: Texas
city: Austin
zip_code: '78729'
timezone: America/Chicago
latitude: 30.4521
longitude: -97.7688
browser:
type: Chrome
version: 137.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/137.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)'
screen_height: 1329
screen_width: 2056
bot:
mouse_num_events: 0
click_num_events: 0
keyboard_num_events: 0
touch_num_events: 0
clipboard_num_events: 0
risk_signals:
device_risk: false
proxy: false
vpn: false
tor: false
spoofed_ip: false
datacenter: false
recent_fraud_ip: false
impossible_travel: false
device_network_mismatch: false
location_spoofing: false
risk_signal_scores:
device_risk: 0.4024
proxy: 0
vpn: 0
tor: 0
datacenter: 0
recent_fraud_ip: 0
impossible_travel: 0
device_network_mismatch: 0.0001
location_spoofing: 0
linked_accounts:
- account_id: john-doe-2
score: 1
email: john.doe2@example.com
phone: '+14155550123'
first_name: Jane
last_name: Doe
username: jane.doe
expected_countries:
- US
- CA
match_type:
- browser
- network
- email
- phone
- username
lists:
- us_users
metadata: {}
- account_id: alice-2
score: 0.17
email: alice.2@example.com
phone: '+14155550123'
first_name: Jane
last_name: Doe
username: jane.doe
expected_countries:
- US
- CA
match_type:
- network
lists:
- us_users
metadata: {}
'400':
description: Session not found or invalid request
content:
application/json:
schema:
$ref: '#/components/schemas/SessionAuthenticateError'
example:
statusCode: 400
message: Session ID not found
tags:
- Session
components:
schemas:
SessionAuthenticateRequest:
type: object
required:
- account
- session_id
properties:
account:
type: object
description: The account to authenticate. See [Account Object](/api-reference/types/account) for more information.
required:
- id
properties:
id:
type: string
description: The account identifier
email:
type: string
description: The email associated with the account
phone:
type: string
maxLength: 32
description: The phone number on file for the account in E.164 format (e.g. +14155550123). Used for multi-accounting phone matching.
first_name:
type: string
maxLength: 256
description: The account holder's first name. Combined with last_name for multi-accounting name matching.
last_name:
type: string
maxLength: 256
description: The account holder's last name. Combined with first_name for multi-accounting name matching.
username:
type: string
maxLength: 256
description: The username associated with the account. Used for multi-accounting username matching.
expected_countries:
type: array
items:
type: string
minLength: 2
maxLength: 2
description: Countries the account is expected to legitimately operate from, as ISO 3166-1 alpha-2 codes (e.g. ["US", "CA"]). A non-empty list replaces the stored list; an empty or omitted list leaves the stored list unchanged.
metadata:
type: object
additionalProperties: true
description: Additional metadata about the account
group:
type: string
description: Groups must be enabled for the project to use this field. See [Multi Accounting Groups](/integration/advanced/multi-accounting-groups) for more information.
lists:
type: array
items:
type: string
description: Array of list names to add the account to during authentication. Lists will be automatically created if they don't exist. See [Lists](/action/lists) for more information.
session_id:
type: string
description: The ID of the session to authenticate
SessionUnauthenticatedResponse:
type: object
properties:
project_id:
type: string
description: The ID of the project
session_id:
type: string
description: The ID of the session
request_id:
type: string
description: The ID of the request
decision:
type: string
description: Decision about the authenticity (Real/Fake)
account_score:
type: number
format: float
description: Overall account risk score
bot:
type: number
format: float
description: Bot detection score
multiple_accounts:
type: number
format: float
description: Multiple accounts detection score
risk_signals:
type: number
format: float
description: Risk signals score
accounts_linked:
type: integer
description: Number of accounts linked to this session
lists:
type: array
items:
type: string
description: Lists the session belongs to
session:
$ref: '#/components/schemas/SessionDetails'
linked_accounts:
type: array
items:
$ref: '#/components/schemas/LinkedAccount'
description: List of accounts linked to this session (only included when accounts_linked=true)
SessionAuthenticateError:
type: object
properties:
statusCode:
type: integer
description: HTTP status code
message:
type: string
description: Error message
SessionAuthenticateResponse:
type: object
properties:
project_id:
type: string
description: The ID of the project
session_id:
type: string
description: The ID of the session
account_id:
type: string
description: The ID of the account
request_id:
type: string
description: The ID of the request
decision:
type: string
description: Decision about the authenticity (Real/Fake)
account_score:
type: number
format: float
description: Overall account risk score
bot:
type: number
format: float
description: Bot detection score
multiple_accounts:
type: number
format: float
description: Multiple accounts detection score
risk_signals:
type: number
format: float
description: Risk signals score
accounts_linked:
type: integer
description: Number of accounts linked to this account
lists:
type: array
items:
type: string
description: Lists the account belongs to
session:
$ref: '#/components/schemas/SessionDetails'
account:
$ref: '#/components/schemas/AccountDetails'
linked_accounts:
type: array
items:
$ref: '#/components/schema
# --- truncated at 32 KB (52 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/verisoul/refs/heads/main/openapi/verisoul-session-api-openapi.yml