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 ($host/identity/workflow/business).

• 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
email	String	Business email address	Yes
website	String	Business website URL	Yes
phone_number	String	Business phone number	No
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	No
address.state_code	String	State/province code	No
address.city	String	City name	No
address.street_address1	String	Primary street address	No
address.street_address2	String	Secondary street address	No
address.zip_code	String	ZIP or postal code	No
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	No
webhook_url	String	URI where verification status changes are sent	No
demo	Object	Testing configuration (omit for live verifications)	No
demo.status	Boolean	Demo status flag	No
demo.flag	Boolean	Demo flag	No

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": "[e-mail]",
  "website": "https://examplecompany.com",
  "phone_number": "[phone]",
  "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": "Running"
}

3. Receive Liveness Check Links for Associated Persons

The API will generate unique liveness check links for all associated persons requiring liveness check. 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 check the liveness check status of an individual or associated person by calling the {baseUrl}/identity/workflow/liveness/<workflow_id> endpoint.

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 Running 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.