Verisoul Session API
The Session API from Verisoul — 4 operation(s) for session.
OpenAPI Specification
openapi: 3.0.1
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:
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)
SessionResponse_2:
type: object
properties:
account_ids:
type: array
items:
type: string
description: List of account IDs associated with this session
request_id:
type: string
description: The ID of the request
project_id:
type: string
description: The ID of the project
session_id:
type: string
description: The ID of the session
start_time:
type: string
format: date-time
description: Timestamp when the session started
true_country_code:
type: string
description: The true country code of the session
device_id:
type: string
description: Device identifier from the session
network:
type: object
properties:
ip_address:
type: string
description: IP address of the session
service_provider:
type: string
description: Internet service provider
connection_type:
type: string
description: Type of network connection
location:
type: object
properties:
continent:
type: string
description: Continent code
country_code:
type: string
description: Country code
state:
type: string
description: State or region
city:
type: string
description: City name
zip_code:
type: string
description: Postal/ZIP code
timezone:
type: string
description: Timezone of the location
latitude:
type: number
format: float
description: Latitude coordinate
longitude:
type: number
format: float
description: Longitude coordinate
browser:
type: object
properties:
type:
type: string
description: Browser type
version:
type: string
description: Browser version
language:
type: string
description: Browser language setting
user_agent:
type: string
description: User agent string
timezone:
type: string
description: Browser timezone setting
device:
type: object
properties:
category:
type: string
enum:
- desktop
- mobile
- tablet
- console
- smarttv
- wearable
- embedded
- other
description: Device category. See [Device Categories](/signals-scores/device#device-categories) for details.
type:
type: string
description: Device type
os:
type: string
description: Operating system
cpu_cores:
type: integer
description: Number of CPU cores
memory:
type: integer
description: Amount of memory in GB
gpu:
type: string
description: GPU information
screen_height:
type: number
description: Screen height in pixels
screen_width:
type: number
description: Screen width in pixels
bot:
type: object
properties:
mouse_num_events:
type: integer
description: Number of mouse events
click_num_events:
type: integer
description: Number of click events
keyboard_num_events:
type: integer
description: Number of keyboard events
touch_num_events:
type: integer
description: Number of touch events
clipboard_num_events:
type: i
# --- 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