List Verifications

Overview

This endpoint allows you to retrieve a list of your recent verification records. You can retrieve records from the past 30 days. Verification records older than 30 days are automatically deleted. You can also retrieve a specific verification record by providing its verification ID.

Steps

Make API Request:

1. Send a GET request to the verification records endpoint.

2. Include any optional query parameters to filter or retrieve a specific record.

Query Parameters

Parameter	Values/Type	Description
workflow_type	business | person	Type of verification
page_size	Integer (default: 20)	Number of records per page
next_page_token	String	Token returned for pagination
id	String (UUID)	The verification id
status	Initiated | GeneratingLivenessCheck | Completed | Running | Failed | AwaitingLivenessCheck	Status of verification
report_status	true | false	Report status
object_search_phrase	String	Phrase to filter results (e.g., business name, first/last name combinations, verification ID)

Sample Request:

// Some code
curl -X GET "https://api.bive.ai/identity/workflow" \
  -H "Api-Key:  YOUR_TOKEN_HERE"

Receive Verification Records

• The API will return a JSON response containing the verification records.

• If a specific ID was requested, it will return only that record.

• If no ID was requested, it will return an array of verification records.

Response Details

Successful Response (200 OK):

{
  "next_page_token": "eyJzdGFydF90aW1lIjoiMjAyNS0wNC0wMlQxMzo0ODo1My4wMjA3MjlaIiwiY2xvc2VfdGltZSI6IjAwMDEtMDEtMDFUMDA6MDA6MDBaIiwicnVuX2lkIjoxMjV9Cg==",
  "data": [
    {
      "id": "0195dbd4-eebc-7e4e-b2ee-80068ca1ed74f",
      "input": {
        "business_name": "company name",
        "doingBusinessAs": "",
        "website": "https://companysite.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_name": "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 (123 Maple Avenue Springfield, OH 45503) 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"
    }
  ]
}

Error Response (422 Unprocessable Entity):

{
  "message": "error listing verifications, please try again later"
}

Automatic Deletion

Verification records are automatically deleted after 30 days. This ensures data privacy and efficient storage management.

Error Handling

• 400 Bad Request: Invalid parameters.

• 404 Not Found: Verification record not found (when using verification_id).

• 500 Internal Server Error: Server-side error.

Use Cases

• Auditing and compliance

• Generating verification reports

• Providing customer support

• Tracking verification history