Business Verification

Overview

This endpoint allows you to verify a business identity, including the identities of any associated persons. Business verification requires a business registration document or a bank account statement. Associated person verification requires a liveness check or upload of a trusted selfie and government ID.

Prerequisites

You must have uploaded the required business documents and associated person documents using the Asset Upload Guide.

Steps

1. Obtain Document Filenames

Retrieve the filenames of the uploaded business documents and associated person documents from the asset upload response.

2. Prepare Business Verification Request

Construct a POST request to the business verification endpoint.
Include the business document filename in the appropriate field (e.g., business_registration_filename, bank_statement_filename).
Include the business details (e.g., business name, address).
Include an array of associated person objects, each containing their document filenames and person details.

Request Body Parameters

Parameter

Type

Description

Required

name

String

The business name

Yes

String

Business email address

Yes

website

String

Business website URL

phone_number

String

Business phone number

document

Object

Document information

Yes

document.type

String

Document type: account-statement or business-registration

Yes

document.url

String

Filename returned in the asset upload endpoint

Yes

address

Object

Business address information

Yes

address.country_code

String

Country code

address.state_code

String

State/province code

address.city

String

City name

address.street_address1

String

Primary street address

address.street_address2

String

Secondary street address

address.zip_code

String

ZIP or postal code

associated_persons

Array

Array of person(s) related to the business

Yes

liveness_check

Bool

The default is true This indicates whether liveness check is required for each associated person

webhook_url

String

URI where verification status changes are sent

demo

Object

Testing configuration (omit for live verifications)

demo.status

Boolean

Demo status flag

demo.flag

Boolean

Demo flag

advanced_check

Boolean

default is true

The demo field indicates that this business verification is for testing purposes only. No cost is incurred. Do not include this field in your request body for live verifications.

Sample Request

curl -X POST "https://api.bive.ai/identity/workflow/business" \
  -H "Content-Type: application/json" \
  -H "Api-Key: YOUR_BIVE_API_KEY" \
  -d '{
  "name": "company name",
  "email": "[email protected]",
  "website": "https://examplecompany.com",
  "phone_number": "+17123456789",
  "address": {
    "country_code": "US",
    "state_code": "Virginia",
    "city": "Norfolk",
    "zip_code": "23513",
    "street_address1": "1244 Norview Avenue",
    "street_address2": ""
  },
  "document" : {
    "type" : "business-registration",
    "url" : "biz-reg-0195dbd4-3efc-76c6-9aa3-18cf9581cd03.pdf"
  },
  "associated_persons" : [{
    "first_name": "John",
    "last_name": "Doe",
    "middle_name": "",
    "media": "selfie-0195dbd4-3efc-76c6-9aa3-18cf9581cd03.jpg",
    "gov_id" : "gov-id-0195dbd4-3efc-76c6-9aa3-18cf9581cd03.jpg"
    }
  ],
  "liveness_check": true,
  "webhook_url" : "https:/webhook-site.com"
}'

Sample Response

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

3. Receive Liveness Check Links for Associated Persons

The API will generate unique liveness check links for all associated persons requiring liveness check. While the liveness check links for all associated persons are being generated, the status of the verification will be “GeneratingLivenessCheck”. The links will be delivered via a webhook to your specified endpoint. This might take a few seconds. The webhook will contain liveness check links for all associated persons.

Example Webhook Response

{
  "data": [
    {
      "completed_at": null,
      "created_at": "2025-04-15T11:01:14.264533994Z",
      "id": "0196391c-3cbd-7b78-98eb-5cb5a445b870",
      "liveness_id": "0196391c-5ae8-7834-8669-1b309dfb89a5",
      "liveness_link": "https://liveness.dev.bive.ai/?id=0196391c-5ae8-7834-8669-1b309dfb89a5&sessionId=0196391c-5ae8-76bb-bbe6-cd814b990b75",
      "name": "John Doe",
      "status": "AwaitingLivenessCheck"
    },
    {
      "completed_at": null,
      "created_at": "2025-04-15T11:01:14.264533994Z",
      "id": "0196391c-3cbd-7b78-98eb-5cb5a445b870",
      "liveness_id": "0196391c-5ae9-7299-9c60-9d594678e669",
      "liveness_link": "https://liveness.dev.bive.ai/?id=0196391c-5ae9-7299-9c60-9d594678e669&sessionId=0196391c-5ae8-7dac-80cf-a1db4861461c",
      "name": "Jane Doe",
      "status": "AwaitingLivenessCheck"
    }
  ],
  "event": "verification.liveness_check.awaiting"
}

4. Receive Liveness Check Status for Associated Person

You will receive a webhook notification when all associated persons have completed their liveness checks. You can get the liveness check status of an individual or associated person by calling the liveness endpoint.

Sample Request

// Some code
curl -X GET "https://api.bive.ai/identity/workflow/liveness/{workflow_id}" \
  -H "Content-Type: application/json" \
  -H "Api-Key: YOUR_BIVE_API_KEY"

Sample Response

[
  {
    "id": "01961f8c-2aa0-7bc6-8263-dd98a8d89518",
    "parent_verification_id": "01961f8c-0d11-783d-a002-27486da7d9a8",
    "client_id": "0975a0b0-2815-48a9-a1a7-a3dd452cf5ff",
    "client_name": " ",
    "status": "AwatingLivenessCheck",
    "entity_name": "John Doe",
    "has_government_id": true,
    "link_url": "https://liveness.dev.bive.ai/?id=57aacbbb-80d4-4cee-b781-8b52c2d352a5_25&sessionId=01961f8c-2aa0-7bc6-8263-dd98a8d89518",
    "retry_count": 5,
    "created_at": "2025-04-10T11:53:23.023601Z",
    "completed_at": null
  },
  {
    "id": "01961f8c-2aa1-7163-9c0d-79b0c1442f19",
    "parent_verification_id": "01961f8c-0d11-783d-a002-27486da7d9a8",
    "client_id": "0975a0b0-2815-48a9-a1a7-a3dd452cf5ff",
    "client_name": " ",
    "status": "AwatingLivenessCheck",
    "entity_name": "Jane Doe",
    "has_government_id": true,
    "link_url": "https://liveness.dev.bive.ai/?id=b6a43302-4215-448e-b63e-6044586bc05e_25&sessionId=01961f8c-2aa1-7163-9c0d-79b0c1442f19",
    "retry_count": 5,
    "created_at": "2025-04-10T11:53:23.156409Z",
    "completed_at": null
  }
]

5. Receive Verification Response

The API will return a JSON response with the verification status. If associated persons require liveness checks, their status will be AwaitingLivenessCheck. If not, the status will be Running, Completed or Failed. Once all associated persons complete liveness checks, the business verification process will continue to Completed or Failed.

Example AwaitingLivenessCheck Response

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

Example Completed Response

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

Example Failed Response

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

Sample Business Verification Object

{
  "id": "0195dbd4-eebc-7e4e-b2ee-80068ca1ed74f",
  "input": {
    "business_name": "company name",
    "website": "https://company-site.com"
  },
  "status": "Completed",
  "final_result": {
    "result": false,
    "confidence": 99,
    "reasoning": "We are 99% confident that this identity is false. Based on multiple indicators of potential fraud—including the business website, name, documents, and tax ID—we assess this identity as 99% likely to be false."
  },
  "associated_persons": [
    {
      "id": "0195f6c3-c6f0-78d0-a4d5-a261fc6e26cf",
      "first_name": "John",
      "Last_nam": "Doe",
      "result": "false"
    }
  ],
  "details": [
    {
      "name": "BusinessName",
      "result": "true",
      "confidence": 99,
      "reasoning": "The business name was confirmed through verification against supporting documents and multiple trusted third-party sources."
    },
    {
      "name": "Website",
      "result": "true",
      "confidence": 99,
      "reasoning": "We confirmed the website's legitimacy by verifying consistent business information—name, address, and contact details—across multiple trusted online sources."
    },
    {
      "name": "Email",
      "result": "false",
      "confidence": 99,
      "reasoning": "The provided customer support email address does not match the email address on the website or multiple trusted third-party platforms, raising concerns about potential misrepresentation."
    },
    {
      "name": "PhoneNumber",
      "result": "false",
      "confidence": 99,
      "reasoning": "The provided business phone number does not match the phone number on the website, raising concerns about potential misrepresentation."
    },
    {
      "name": "Document",
      "result": "true",
      "confidence": 99,
      "reasoning": "The business document was confirmed through verification against information provided in the application, and multiple trusted third-party sources."
    },
    {
      "name": "Address",
      "result": "false",
      "confidence": 99,
      "reasoning": "The business address (700 orange grove dublin California) does not match the address shown on the business document, raising concerns about potential misrepresentation."
    },
    {
      "name": "Association",
      "result": "false",
      "confidence": 99,
      "reasoning": "The identity of one or more associated persons was verified as false, raising concerns about potential misrepresentation and fraud."
    }
  ],
  "created_at": "2025-03-28T08:17:54.944703Z"
}

Example Webhook Request Body

{
  "event": "verification.completed",
  "data": BusinessVerficationObject
}

Response Details

Successful Response (200 OK)

JSON object with verification_status: completed.

Pending Response (200 OK)

JSON object with verification_status: AwaitingLivenessCheck.

Error Response

JSON object with an error field containing an error message and/or code.

Document Requirements

Business Document Requirements

Business registration document (PDF, JPG, PNG)
Bank account statement (PDF, JPG, PNG)

Associated Persons Requirements

We highly recommend that all associated persons complete a liveness check. Liveness check must be completed before the business verification can be completed.
The business verification status will remain AwaitingLivenessCheck until all associated person liveness checks are successful.
You can opt to upload verification documents instead of a liveness check:
- Government ID (PNG, JPG)
- Selfie (PNG, JPG)
The business verification status will be Running until it moves to Completed or Failed

Error Handling:

400 Bad Request: Invalid filenames, missing required fields, or invalid data.
404 Not Found: One or more specified files were not found.
500 Internal Server Error: Server-side error during verification.

PreviousPerson Verification NextBasic vs Advanced verification

Last updated 23 days ago

Was this helpful?