> ## Documentation Index
> Fetch the complete documentation index at: https://docs.busha.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Verify Customer Identity

> Implement KYC verification for customers. Collect documents and verify identity information.

This guide provides a technical walkthrough on programmatically verifying a customer account using the Busha API.

<Tip>
  **What You'll Achieve:**

  1. Update customer profile with KYC/KYB documents.
  2. Successfully verify your customer identity.
  3. Monitor verification status changes.
</Tip>

## Prerequisites

Before you begin, ensure you have:

* A **Busha Business Account** and **Secret API Key** (from the [Quick Start Tutorial](/guides/getting-started/quick-start)).
* An understanding of **API Environments** (Sandbox vs. Production) and their base URLs (from the [Make Your First Request Guide](/guides/getting-started/make-first-request)).
* A customer account created (see [Create Individual Customer](/guides/customers/create-individual) or [Create Business Customer](/guides/customers/create-business)).

## Verifying Customer Identity (KYC/KYB)

<Steps>
  <Step title="Submit Customer KYC/KYB Documents">
    <Warning>
      Skip this step if verification documents were attached when creating the
      customer.
    </Warning>

    The core requirement for verifying a customer is the completed upload of identification documents.

    <Note>
      Files uploaded for KYC/KYB must be in Base64 format and have a file size less than 4MB.
    </Note>

    **Individual customer**

    For individual customers, you must provide ONE of the following combinations in the `identifying_information` array:

    **Option 1: Passport + Selfie**

    ```json theme={null}
    "identifying_information": [
      {
        "type": "passport",
        "number": "A12345678",
        "country": "NG",
        "image_front": "{{base64 encoded passport image}}"
      },
      {
        "type": "selfie",
        "image_front": "{{base64 encoded selfie image}}",
        "number": "",
        "country": "NG"
      }
    ]
    ```

    **Option 2: National ID + Selfie**

    ```json theme={null}
    "identifying_information": [
      {
        "type": "national-id",
        "number": "12345678901",
        "country": "NG"
      },
      {
        "type": "selfie",
        "image_front": "{{base64 encoded selfie image}}",
        "number": "",
        "country": "NG"
      }
    ]
    ```

    <table style={{ width: '100%', borderCollapse: 'collapse' }}>
      <thead>
        <tr>
          <th style={{ width: '30%', textAlign: 'left', padding: '12px' }}>
            Country
          </th>

          <th style={{ width: '70%', textAlign: 'left', padding: '12px' }}>
            Documents Required
          </th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td style={{ padding: '12px' }}>Nigeria</td>

          <td style={{ padding: '12px' }}>
            <ul style={{ margin: '8px 0', paddingLeft: '20px' }}>
              <li>NIN number and selfie image</li>
              <li>National passport and selfie image</li>
              <li>Driver's license and selfie image</li>
            </ul>
          </td>
        </tr>

        <tr>
          <td style={{ padding: '12px' }}>Kenya</td>

          <td style={{ padding: '12px' }}>
            <ul style={{ margin: '8px 0', paddingLeft: '20px' }}>
              <li>National ID and selfie image</li>
            </ul>
          </td>
        </tr>
      </tbody>
    </table>

    To update an individual customer with their verification documents:

    1. Open your terminal or command prompt.
    2. Use the `PUT` request below to the `/v1/customers/{customer_id}` endpoint.
    3. Replace `{customer_id}` with the customer ID.
    4. Replace `YOUR_BASE_URL` with your chosen environment's URL and `{YOUR_SECRET_KEY}` with your actual key.
    5. Replace the values in the `identifying_information` array with the customer documents.

    **Example with Passport + Selfie:**

    ```shell theme={null}
    $ curl -i -X PUT https://YOUR_BASE_URL/v1/customers/{customer_id} \
      -H 'Authorization: Bearer {YOUR_SECRET_KEY}' \
      -H 'Content-Type: application/json' \
      -d '{
        "email": "customer@gmail.com",
        "first_name": "John",
        "last_name": "Doe",
        "has_accepted_terms": true,
        "type": "individual",
        "country_id": "NG",
        "phone": "+234 8012345678",
        "birth_date": "15-06-1990",
        "address": {
          "city": "Lagos",
          "state": "Lagos",
          "country_id": "NG",
          "address_line_1": "10 Allen Avenue",
          "postal_code": "100001"
        },
        "identifying_information": [
          {
            "type": "passport",
            "number": "A12345678",
            "country": "NG",
            "image_front": "{{base64 string}}"
          },
          {
            "type": "selfie",
            "image_front": "{{base64 string}}",
            "number": "",
            "country": "NG"
          }
        ]
      }'
    ```

    **Example with National ID + Selfie:**

    ```shell theme={null}
    $ curl -i -X PUT https://YOUR_BASE_URL/v1/customers/{customer_id} \
      -H 'Authorization: Bearer {YOUR_SECRET_KEY}' \
      -H 'Content-Type: application/json' \
      -d '{
        "email": "customer@gmail.com",
        "first_name": "John",
        "last_name": "Doe",
        "has_accepted_terms": true,
        "type": "individual",
        "country_id": "NG",
        "phone": "+234 8012345678",
        "birth_date": "15-06-1990",
        "address": {
          "city": "Lagos",
          "state": "Lagos",
          "country_id": "NG",
          "address_line_1": "10 Allen Avenue",
          "postal_code": "100001"
        },
        "identifying_information": [
          {
            "type": "national-id",
            "number": "12345678901",
            "country": "NG"
          },
          {
            "type": "selfie",
            "image_front": "{{base64 string}}",
            "number": "",
            "country": "NG"
          }
        ]
      }'
    ```

    **Business customer**

    For business customers, the KYB documents and sections required are:

    **Documents:**

    * Certificate of Incorporation
    * Corporate registry extract
    * Memorandum of Association articles (memart)
    * Corporate structure chart
    * Board resolution
    * Anti-money laundering policy
    * Regulatory licenses
    * Proof of wealth
    * Proof of address

    **Required Sections:**

    * **Business Owners** - Directors and beneficial owners information
    * **Business Transaction** - Expected transaction patterns and volumes
    * **Business Registration** - Legal and regulatory details

    To update a business customer with complete KYB information:

    1. Open your terminal or command prompt.
    2. Use the `PUT` request below to the `/v1/customers/{customer_id}` endpoint.
    3. Replace `{customer_id}` with the customer ID.
    4. Replace `YOUR_BASE_URL` with your chosen environment's URL and `{YOUR_SECRET_KEY}` with your actual key.
    5. Include all required sections and documents.

    ```shell theme={null}
    $ curl -i -X PUT https://YOUR_BASE_URL/v1/customers/{customer_id} \
      -H 'Authorization: Bearer {YOUR_SECRET_KEY}' \
      -H 'Content-Type: application/json' \
      -d '{
        "email": "business@gmail.com",
        "has_accepted_terms": true,
        "type": "business",
        "country_id": "NG",
        "phone": "+234 8012345678",
        "business_name": "ABC Corporation",
        "business_industry": "BIN_C4UvTYR5V8jsOx5LmwQ",
        "business_incorporation_date": "2015-06-15",
        "documents": [
          {
            "purposes": ["certificate_of_incorporation"],
            "file": "{{base64 string}}"
          }
        ],
        "business_owners": [
          {
            "first_name": "John",
            "last_name": "Owner",
            "role": ["director"],
            "percentage_ownership": 100,
            "is_pep": false,
            "nationality": "NG",
            "bvn": "12345678901"
          }
        ],
        "business_transaction": {
          "purpose": "international trade",
          "monthly_transaction_value": "above_1m_usd",
          "monthly_transaction_count": "100_to_200",
          "client_transaction_status": "self-owned",
          "api_access_needed": true,
          "api_integration_url": "https://yourbusiness.com"
        },
        "business_registration": {
          "business_type": "type_registered_company",
          "business_structure": "limited_liability_company",
          "business_regulation_status": "regulated",
          "registration_number": "RC1234567",
          "tax_identification_number": "TIN1234567",
          "corporate_group_status": "standalone_company",
          "exchange_listing_status": "not_listed_on_exchange",
          "license_number": "LIC123456"
        }
      }'
    ```
  </Step>

  <Step title="Verify the Customer">
    After uploading all required documents and information, call the verify endpoint to submit the customer for verification.

    To verify the customer:

    1. Open your terminal or command prompt.
    2. Use the `POST` request below to the `/v1/customers/{customer_id}/verify` endpoint.
    3. Replace `{customer_id}` with the customer ID.
    4. Replace `YOUR_BASE_URL` with your chosen environment's URL and `{YOUR_SECRET_KEY}` with your actual key.

    ```shell theme={null}
        $ curl -i -X POST "https://YOUR_BASE_URL/v1/customers/{customer_id}/verify" \
          -H 'Authorization: Bearer {YOUR_SECRET_KEY}'
    ```

    **Expected Response**

    A successful response indicates the verification request has been submitted:

    ```json theme={null}
    {
      "status": "success",
      "message": "Customer verified successfully"
    }
    ```

    <Info>
      After calling the verify endpoint, the customer status will change from `inactive` to `in_review`. You'll receive webhook notifications as the verification progresses.
    </Info>
  </Step>

  <Step title="Check Verification Status">
    Monitor the customer's verification status by retrieving their details:

    ```shell theme={null}
        $ curl -i -X GET "https://YOUR_BASE_URL/v1/customers/{customer_id}" \
          -H 'Authorization: Bearer {YOUR_SECRET_KEY}'
    ```

    **Customer Status Values:**

    * `inactive` - Customer created but not yet verified
    * `in_review` - Verification documents submitted and under review
    * `active` - Customer verified and can perform transactions
    * `rejected` - Verification failed (check rejection reason)

    **Example Response:**

    ```json theme={null}
    {
      "status": "success",
      "message": "Fetched customer successfully",
      "data": {
        "id": "CUS_Ikdb49NLsnlYU",
        "email": "customer@gmail.com",
        "first_name": "John",
        "last_name": "Doe",
        "type": "individual",
        "status": "in_review",
        "level": "0",
        "created_at": "2026-01-27T09:23:09.317273Z",
        "updated_at": "2026-01-27T09:26:34.537881Z"
      }
    }
    ```
  </Step>

  <Step title="Monitor Verification via Webhooks (Recommended)">
    Set up webhooks to receive real-time notifications about verification status changes. See [Webhook Events](/guides/webhooks/webhook-events) for available customer verification events:

    * `customer.verification.in_review` - Verification submitted
    * `customer.verification.active` - Verification approved
    * `customer.verification.rejected` - Verification failed
    * `customer.verification.inactive` - Verification reverted

    **Example Webhook Payload:**

    ```json theme={null}
    {
      "business_id": "BUS_CQr0jPzGGzmn1uW5W7OVs",
      "event": "customer.verification.in_review",
      "data": {
        "id": "CUS_Ikdb49NLsnlYU",
        "business_id": "BUS_CQr0jPzGGzmn1uW5W7OVs",
        "business_name": "",
        "first_name": "John",
        "last_name": "Doe",
        "email": "customer@gmail.com",
        "type": "individual",
        "status": "in_review",
        "level": "0",
        "created_at": "2026-01-27T09:23:09.317273Z"
      }
    }
    ```

    Learn how to set up webhooks in the [Webhooks Guide](/guides/webhooks/setup).
  </Step>
</Steps>

## Common Verification Errors

**Individual Customers:**

```json theme={null}
{
  "error": {
    "name": "profile_kyc_verification",
    "message": "KYC document does not contain a selfie image"
  }
}
```

**Solution:** Ensure the `identifying_information` array includes a selfie object with `type: "selfie"` and `image_front` containing a base64 encoded selfie image.

**Business Customers:**

```json theme={null}
{
  "error": {
    "name": "missing_section",
    "message": "Owners section must be completed before final submission"
  }
}
```

**Solution:** Add the `business_owners` array with at least one owner/director.

```json theme={null}
{
  "error": {
    "name": "missing_section",
    "message": "Transaction section must be completed before final submission"
  }
}
```

**Solution:** Add the `business_transaction` object with transaction details.

## Troubleshooting

* **`400 Bad Request / 422 Unprocessable Entity`:** Review your request body to ensure all required fields are present and correctly formatted.
* **`401 Unauthorized`:** Verify that your Secret API Key is correct and included in the header.
* **`missing_section` errors:** For business customers, ensure all three sections (owners, transaction, registration) are complete before verification.
* **`profile_kyc_verification` errors:** For individual customers, ensure all required documents (ID images and selfie image) are uploaded in the `identifying_information` array.

## What's Next?

Now that you can programmatically verify customers, you can proceed to perform transactions on their behalf:

* [How to Initiate Transactions on Behalf of a Customer](/guides/customers/transactions-on-behalf): Understand how to use the `customer_id` to perform operations for your customers.
* [Webhook Events](/guides/webhooks/webhook-events): Learn about all customer verification webhook events.
* [Monitor Verification Status](/guides/customers/check-status): Track customer verification progress.