Person Verification

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:

1. Highly Recommended: Verify with Liveness Check for enhanced security.

2. Verify without Liveness Check 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

• 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
advanced_check	Bool	Optional	Default is true

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.

Example Request

curl -X POST "https://api.bive.ai/identity/workflow/person" \
  -H "Content-Type: application/json" \
  -H "Api-Key: YOUR_BIVE_API_KEY" \
  -d '{
    "first_name": "John",
    "last_name": "Doe",
    "middle_name": "Michael",
    "gov_id":  "gov-id-f5c0800f-c02b-4b9f-b5b5-64f8b99d1fb2.png",
    "email": "[email protected]",
    "phone_number": "[phone]",
    "date_of_birth": "1985-07-15",
    "address": {
      "country_code": "US",
      "state_code": "CA",
      "city": "San Francisco",
      "street_address1": "123 Main Street",
      "street_address2": "Apt 4B",
      "zip_code": "94107"
    },
    "job_title": "Software Engineer",
    "webhook_url": "https://your-webhook-endpoint.com",
    "liveness_check": true
  }'

Sample Response Body

{
  "id": "01958a08-564e-7169-8e32-1196d5bf230e",
  "status": "Initiated"
}

2. Receive Liveness Check Link

• The API will generate a unique liveness check link. While the liveness check link is being generated, the status of the verification will be “GeneratingLivenessCheck”

• This link will be delivered via a webhook to your specified endpoint

Example Webhook Response:

{
  "data": [
    {
      "completed_at": null,
      "created_at": "2025-04-15T10:40:40.572092223Z",
      "id": "01963909-691f-711e-92c4-f7dcf2f5232a",
      "liveness_id": "52d83f0f-56c1-4ba4-93cb-1a9d50b549cf",
      "liveness_link": "https://liveness.dev.bive.ai/?id=52d83f0f-56c1-4ba4-93cb-1a9d50b549cf&sessionId=01963909-691f-711e-92c4-f7dcf2f5232a",
      "name": "John Doe",
      "status": "AwaitingLivenessCheck"
    }
  ],
  "event": "verification.liveness_check.awaiting"
}

3. Send Liveness Check Link to the User

• 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)

• A webhook will be sent to your specified endpoint

Example Webhook Response:

{
  "data": [
    {
      "id": "01963909-691f-711e-92c4-f7dcf2f5232a",
      "name": "John Doe",
      "liveness_link": "https://liveness.dev.bive.ai/?id=52d83f0f-56c1-4ba4-93cb-1a9d50b549cf&sessionId=01963909-691f-711e-92c4-f7dcf2f5232a",
      "liveness_id": "52d83f0f-56c1-4ba4-93cb-1a9d50b549cf",
      "status": "Completed",
      "created_at": "2025-04-15T10:40:40.572092223Z",
      "completed_at": "2025-04-15T10:44:40.572092223Z"
    }
  ],
  "event": "verification.liveness_check.completed"
}

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:

Using the asset-upload endpoint, you must have already uploaded the required documents (e.g., government ID, selfie). Refer to the Asset Upload Guide for instructions.

Steps:

1

Obtain Document Filenames

Retrieve the filenames of the uploaded documents from the asset upload response.

2

Prepare Verification Request

• Construct a POST request to the verification endpoint.

• 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 “Initiated” 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.

Sample Request

curl -X POST "https://api.bive.ai/identity/workflow/person" \
  -H "Content-Type: application/json" \
  -H "Api-Key: YOUR_BIVE_API_KEY" \
  -d '{
    "first_name": "John",
    "last_name": "Doe",
    "middle_name": "Michael",
    "media": “selfie-b2354384-8c8a-4900-89ec-1ebbd9bd88b7.png”,
    "gov_id":  "gov-id-f5c0800f-c02b-4b9f-b5b5-64f8b99d1fb2.png",
    "email": "[email protected]",
    "phone_number": "[phone]",
    "date_of_birth": "1985-07-15",
    "address": {
      "country_code": "US",
      "state_code": "CA",
      "city": "San Francisco",
      "street_address1": "123 Main Street",
      "street_address2": "Apt 4B",
      "zip_code": "94107"
  },
    "job_title": "Software Engineer",
    "webhook_url": "https://your-webhook-endpoint.com",
    "liveness_check": false
  }'

Sample Response

{
	"id": "01958a08-564e-7169-8e32-1196d5bf230e",
	"status": "Initiated"
}

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.