Verify Customer Identity

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

What You’ll Achieve:

Update customer profile with KYC/KYB documents.
Successfully verify your customer identity.
Monitor verification status changes.

Prerequisites

Before you begin, ensure you have:

A Busha Business Account and Secret API Key (from the Quick Start Tutorial).
An understanding of API Environments (Sandbox vs. Production) and their base URLs (from the Make Your First Request Guide).
A customer account created (see Create Individual Customer or Create Business Customer).

Verifying Customer Identity (KYC/KYB)

Submit Customer KYC/KYB Documents

Skip this step if verification documents were attached when creating the customer.

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

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

Individual customerFor individual customers, you must provide ONE of the following combinations in the identifying_information array:Option 1: Passport + Selfie

"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

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

Country	Documents Required
Nigeria	NIN number and selfie image National passport and selfie image Driver’s license and selfie image
Kenya	National ID and selfie image

To update an individual customer with their verification documents:

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

Example with Passport + Selfie:

$ 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:

$ 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"
      }
    ]
  }'

Verifying Individual Customers with a KYC Link

As an alternative, you can generate a hosted verification link and let the customer complete their own KYC directly.

Generate the link

Call the KYC link endpoint for the customer:

curl -X POST "https://api.busha.io/v1/customers/CUS_xxx/kyc-link" \
  -H "Authorization: Bearer YOUR_SECRET_KEY" \
  -H "Content-Type: application/json"

Response:

{
  "status": "success",
  "message": "KYC link generated successfully",
  "data": {
    "url": "https://in.sumsub.com/websdk/p/sbx_j0t47nDxjmWDw503"
  }
}

Share the link with your customer

Send the returned url to your customer. They complete identity verification directly through this hosted flow.

Check verification status

Once your customer submits their information, their status updates the same way as document-based verification, moving from inactive to in_review, then to active or rejected.

This is only available for individual customers, not business customers.

Business customerFor 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:

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

$ 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"
    }
  }'

Verify the Customer

After uploading all required documents and information, call the verify endpoint to submit the customer for verification.To verify the customer:

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

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

Expected ResponseA successful response indicates the verification request has been submitted:

{
  "status": "success",
  "message": "Customer verified successfully"
}

After calling the verify endpoint, the customer status will change from inactive to in_review. You’ll receive webhook notifications as the verification progresses.

Check Verification Status

Monitor the customer’s verification status by retrieving their details:

    $ 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:

{
  "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"
  }
}

Monitor Verification via Webhooks (Recommended)

Set up webhooks to receive real-time notifications about verification status changes. See 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:

{
  "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.

Common Verification Errors

Individual Customers:

{
  "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:

{
  "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.

{
  "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: Understand how to use the customer_id to perform operations for your customers.
Webhook Events: Learn about all customer verification webhook events.
Monitor Verification Status: Track customer verification progress.

Start Here

Accept Payments (API)

Accept Payments (SDK & Widgets)

On/Off Ramp (API)

Customer Onboarding (B2B2C)

Balance & Treasury

Recipients

Token Sharing

Request ID

OAuth2

Pledges

Webhooks

Reference

Prerequisites

Verifying Customer Identity (KYC/KYB)

Verifying Individual Customers with a KYC Link

Common Verification Errors

Troubleshooting

What’s Next?

​Prerequisites

​Verifying Customer Identity (KYC/KYB)

​Verifying Individual Customers with a KYC Link

​Common Verification Errors

​Troubleshooting

​What’s Next?

Prerequisites

Verifying Customer Identity (KYC/KYB)

Verifying Individual Customers with a KYC Link

Common Verification Errors

Troubleshooting

What’s Next?