Protect your products and services by verifying customer identities with our powerful person verification API. We don't just take input – we validate and cross-reference against reliable web sources to ensure legitimacy. Verify age, tax ID, and more to confidently onboard customers.
Choose Your Verification Method:
Highly Recommended: Verify for enhanced security.
Verify for offline use cases where trusted selfies are available.
See the detailed steps for each option below.
Person Verification with Liveness Check
Overview
This feature enhances person and associated person verification by requiring a real-time selfie capture, ensuring the individual is physically present. This significantly reduces the risk of fraudulent submissions and improves verification accuracy.
Steps
1. Initiate Verification Request
Send a POST request to the verification endpoint, {$host}/identity/workflow/person
Include the necessary person or associated person data
Leave the liveness_check parameter set to true
Request Body
Parameter
Type
Requirement
Description
first_name
String
Required
last_name
String
Required
middle_name
String
Optional
liveness_check
Boolean
Optional
Default value is true
media
String
Required if liveness_check is false
Value returned in the selfie field on the asset-upload endpoint
gov_id
String
Required if liveness_check is false
Value returned in the gov_id field on the asset-upload endpoint
email
String
Optional
phone_number
String
Optional
date_of_birth
String
Optional
Format: 'YYYY-MM-DD'
address
Map
Optional
See address structure below
job_title
String
Optional
webhook_url
String
Optional
URI where verification status changes are sent
demo
Map
Optional
See demo structure below
Address Structure
Field
Type
Description
country_code
String
state_code
String
city
String
street_address1
String
street_address2
String
zip_code
String
Accepts a zip or postal code
Demo Structure
Field
Type
Description
status
Boolean
flag
Boolean
The demo field indicates that this business verification is for test purposes only. No cost is incurred.
Note: Do not include this field in your request body for live verifications.
Send the liveness_link to the person being verified via email or SMS
Inform them that they will need a camera-enabled device
Until the user completes the liveness check, the status of the verification will be AwaitingLivenessCheck. A business verification will not run to completion until all associated persons have completed their liveness check.
4. User Completes Liveness Check
The user opens the link and follows the on-screen instructions to capture their selfie
If a government ID was already provided in the initial request, the user will not be asked to upload it again
The user has up to 5 attempts to provide an acceptable selfie
The system automatically detects spoofs presented to the camera (such as printed photos, digital photos, digital videos, or 3D masks) as well as spoofs that bypass the camera (such as pre-recorded or deepfake videos)
Note: The status of a liveness object can either be "Pending" or "Completed"
5. Verification Result
After the user completes the liveness check, the verification will run and the results will be sent to your webhook endpoint
This result will contain information about the success or failure of the liveness check and the overall verification status
Sample Webhook Response Body:
{
"data": {
"id": "01961049-ba0e-7217-a77d-011d02ffff39",
"input": {
"first_name": "John",
"middle_name": "",
"last_name": "Doe"
},
"status": "Completed",
"final_result": {
"result": "false",
"confidence": 99,
"reasoning": "We are 99.00% confident that this identity is false. Based on multiple indicators of potential fraud, we assess this identity as 99.00% likely to be false."
},
"details": [
{
"name": "Name",
"result": "true",
"confidence": 99,
"reasoning": "The name was confirmed through verification against supporting documents and trusted third-party sources"
},
{
"name": "Address",
"result": "true",
"confidence": 99,
"reasoning": "The address was confirmed through verification against information provided in the application, and multiple trusted third-party sources."
},
{
"name": "Selfie",
"result": "false",
"confidence": 99,
"reasoning": "The face liveness check was unsuccessful after multiple attempts, raising concerns about potential misrepresentation and identity theft"
},
{
"name": "Government ID",
"result": "false",
"confidence": 99,
"reasoning": "The face liveness image did not match with the government ID raising significant concerns about identity theft."
},
{
"name": "Liveness Check",
"result": true,
"confidence": null,
"status": "Completed"
}
],
"is_demo": false,
"created_at": "2025-03-28T08:17:54.944703Z"
},
"event": "verification.completed"
}
Person Verification without a Liveness Check
Overview:
You can verify a person or an associated person's identity without using the liveness check feature. To do this, you must have already acquired a trusted selfie and a government ID document. It is strongly recommended to use the liveness check feature for enhanced security and fraud prevention.
Prerequisites:
Steps:
1
Obtain Document Filenames
Retrieve the filenames of the uploaded documents from the document upload response.
2
Prepare Verification Request
Construct a POST request to the verification endpoint (/identity/workflow/person).
Include the document filenames in the appropriate fields (e.g, government_id_filename, selfie_filename).
Provide all other required information (e.g, name, date of birth).
Set the liveness_check field to false.
3
Send Verification Request
Send the POST request to the verification endpoint.
The response status will be “Running” while your request is being processed. Depending on the complexity of the request, it might take a few minutes to a few hours to get a response.
// Some code
{
"id": "01958a08-564e-7169-8e32-1196d5bf230e",
"status": "Running"
}
4
Receive Verification Response
The API will send the verification result to the provided webhook url
The final result will be one of (True, False or Unknown)
// Sample webhook data
{
"event": "verification.completed",
"data": {
"id": "01961049-ba0e-7217-a77d-011d02ffff39",
"input": {
"first_name": "John",
"middle_name": "",
"last_name": "Doe"
},
"status": "Completed",
"final_result": {
"result": false,
"confidence": 99,
"reasoning": "We are 99.00% confident that this identity is false. Based on multiple indicators of potential fraud, we assess this identity as 99.00% likely to be false."
},
"details": [
{
"name": "Name",
"result": "true",
"confidence": 99,
"reasoning": "The name was confirmed through verification against supporting documents and trusted third-party sources"
},
{
"name": "Address",
"result": "true",
"confidence": 99,
"reasoning": "The address was confirmed through verification against information provided in the application, and multiple trusted third-party sources."
},
{
"name": "Selfie",
"result": "false",
"confidence": 99,
"reasoning": "The face liveness check was unsuccessful after multiple attempts, raising concerns about potential misrepresentation and identity theft"
},
{
"name": "Government ID",
"result": "false",
"confidence": 99,
"reasoning": "The face liveness image did not match with the government ID raising significant concerns about identity theft."
}
],
"created_at": "2025-03-28T08:17:54.944703Z"
}
}
Security Considerations:
Bypassing liveness check increases the risk of fraudulent verifications.
Ensure that the uploaded documents are from trusted sources.
Handle the user data with the utmost security.
We strongly recommend enabling the liveness check feature to bolster security and mitigate fraud. Bypassing liveness checks can significantly increase the risk of accepting fraudulent identities.
You must have already uploaded the required documents (e.g., government ID, selfie) using the document upload endpoint. Refer to the for instructions.
