Create Individual Customer • Busha Developer Documentation

This guide provides a technical walkthrough on programmatically creating an individual customer account within your Busha Business account using the Busha API. By automating customer creation, you can streamline your onboarding processes and prepare to perform transactions on behalf of your customers.

What You’ll Achieve:

Understand the basic structure for creating a customer.
Learn how to structure API requests for individual customer types.
Successfully create and verify customer accounts programmatically.

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

Creating an Individual Customer Account

Understand Customer Creation Parameters

The essential parameters for creating an individual customer type are:

Parameter	Type	Description
`email`	string	The individual customer’s email address.
`has_accepted_terms`	boolean	A flag indicating whether the individual has accepted your platform’s (or Busha’s) terms and conditions.
`type`	string	The type of customer. Must be `individual` for this customer type.
`country_id`	string	The ISO 3166-1 alpha-2 country code representing the individual’s primary country of residence.
`phone`	string	The individual’s phone number, including the international country code (e.g., +234 8012345678).
`birth_date`	string	The individual’s date of birth, typically required for identity verification. Format: DD-MM-YYYY.
`first_name`	string	The individual customer’s first name.
`middle_name`	string	The individual customer’s middle name (optional).
`last_name`	string	The individual customer’s last name.
`address`	object	The individual’s physical address details. See the Address Object Parameters table below for nested fields.
`identifying_information`	array	An array of objects describing the individual’s identification documents (e.g., passport, national ID).
`documents`	array	An array of objects referencing uploaded documents for various purposes (e.g., selfie video for verification).

For the address field in the customer creation object, the fields required are:

Parameter	Type	Description
`city`	string	The city component of the address.
`state`	string	The state or region component of the address.
`county`	string	The county or district component of the address (optional).
`country_id`	string	The ISO 3166-1 alpha-2 country code of the address.
`address_line_1`	string	The first line of the street address.
`address_line_2`	string	The second line of the street address (optional).
`province`	string	The province component of the address (optional).
`postal_code`	string	The postal or ZIP code of the address.

Know Your Customer (KYC)Optionally, you can choose to upload your customer’s KYC documents at the point of creation in the identifying_information and documents array fields.

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

The identifying_information array expects the object(s) in this format:

"identifying_information": [
    {
      "type": "national-id",
      "number": "12345678901",
      "country": "NG",
      "image_front": "{{base64 string}}",
      "image_back": "{{base64 string}}"
    }
]

For individual customers, the KYC documents required, depending on your country, are:

Country	Documents Required
Nigeria	NIN slip and selfie video National passport and selfie video Driver’s license and selfie video
Kenya	National ID and selfie video

The document array expects the object(s) in this format:

"documents": [
    {
      "purposes": ["selfie_video"],
      "file": "{{base64 video data}}"
    }
]

For a full list of acceptable documents, please refer to the Compliance Guide.

Create a Customer (Without KYC Documents)

Individual customers refer to persons who engage with your services. Start with basic information and add KYC documents later.To create an individual customer without KYC documents:

Open your terminal or command prompt.
Use the POST request below to the /v1/customers endpoint.
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 \
      -H 'Authorization: Bearer {YOUR_SECRET_KEY}' \
      -H 'Content-Type: application/json' \
      -d '{
        "email": "[email protected]",
        "has_accepted_terms": true,
        "type": "individual",
        "country_id": "NG",
        "phone": "+234 8012345678",
        "birth_date": "24-12-2000",
        "address": {
          "city": "Lagos",
          "state": "Lagos",
          "country_id": "NG",
          "address_line_1": "10 Allen Avenue",
          "postal_code": "100001"
        },
        "first_name": "John",
        "last_name": "Doe"
      }'

Expected Response:A successful response will return a Customer object with status: "inactive" until KYC is completed.

The default status of a customer is inactive until they complete their Know-Your-Customer (KYC) process.

    {
      "status": "success",
      "message": "Created customer successfully",
      "data": {
        "address": {
          "address_line_1": "10 Allen Avenue",
          "city": "Lagos",
          "country_id": "NG",
          "postal_code": "100001",
          "state": "Lagos"
        },
        "business_id": "BUS_jlKUYwF9z1ynQZ98bWbaP",
        "country_id": "NG",
        "created_at": "2026-01-27T09:23:09.317273Z",
        "deposit": true,
        "display_currency": "NGN",
        "email": "[email protected]",
        "first_name": "John",
        "has_accepted_terms_of_service": true,
        "id": "CUS_IL2Qf2pEoNADZ",
        "last_name": "Doe",
        "level": "0",
        "payout": true,
        "phone": "+234 8012345678",
        "status": "inactive",
        "type": "individual",
        "updated_at": "2026-01-27T09:23:09.317273Z"
      }
    }

Create a Customer (With KYC Documents)

Create a verified customer by including KYC documents at creation.To create a customer with supporting KYC documents:

Open your terminal or command prompt.
Use the POST request below to the /v1/customers endpoint.
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 \
      -H 'Authorization: Bearer {YOUR_SECRET_KEY}' \
      -H 'Content-Type: application/json' \
      -d '{
        "email": "[email protected]",
        "first_name": "Jacob",
        "last_name": "Zuma",
        "has_accepted_terms": true,
        "type": "individual",
        "country_id": "NG",
        "phone": "+234 8087654321",
        "birth_date": "24-12-1990",
        "address": {
          "city": "Lagos",
          "state": "Lagos",
          "country_id": "NG",
          "address_line_1": "15 Victoria Island",
          "postal_code": "100001"
        },
        "identifying_information": [
          {
            "type": "national-id",
            "number": "12345678901",
            "country": "NG",
            "image_front": "{{base64 encoded image}}",
            "image_back": "{{base64 encoded image}}"
          }
        ],
        "documents": [
          {
            "purposes": ["selfie_video"],
            "file": "{{base64 encoded video}}"
          }
        ]
      }'

Expected Response:

    {
      "status": "success",
      "message": "Created customer successfully",
      "data": {
        "address": {
          "address_line_1": "15 Victoria Island",
          "city": "Lagos",
          "country_id": "NG",
          "postal_code": "100001",
          "state": "Lagos"
        },
        "business_id": "BUS_jlKUYwF9z1ynQZ98bWbaP",
        "country_id": "NG",
        "created_at": "2026-01-27T09:23:09.317273Z",
        "deposit": true,
        "display_currency": "NGN",
        "email": "[email protected]",
        "first_name": "Jacob",
        "has_accepted_terms_of_service": true,
        "id": "CUS_Ikdb49NLsnlYU",
        "last_name": "Zuma",
        "level": "0",
        "payout": true,
        "phone": "+234 8087654321",
        "status": "inactive",
        "type": "individual",
        "updated_at": "2026-01-27T09:23:09.317273Z"
      }
    }

The status remains inactive until the documents are verified. Call the verify endpoint to submit for verification.

Verify the Customer

After creating a customer with KYC documents, verify them to activate their account.To verify a 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 from the previous response.
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/CUS_Ikdb49NLsnlYU/verify \
      -H 'Authorization: Bearer {YOUR_SECRET_KEY}'

Expected Response:A successful verification will return:

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

After verification, check the customer status. It will change from inactive to in_review or active.

Common Errors:

profile_kyc_verification: KYC documents are missing or incomplete (e.g., no selfie video)

If you receive this error, update the customer with the missing documents using PUT /v1/customers/{customer_id}, then retry verification.

Complete Example: Create and Verify Customer

Here’s a complete workflow to create and verify an individual customer: Step 1: Create customer with KYC documents

curl -X POST https://api.sandbox.busha.so/v1/customers \
  -H 'Authorization: Bearer YOUR_SECRET_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "email": "[email protected]",
    "first_name": "Test",
    "last_name": "Customer",
    "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",
        "image_front": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg==",
        "image_back": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg=="
      }
    ],
    "documents": [
      {
        "purposes": ["selfie_video"],
        "file": "data:video/mp4;base64,AAAAIGZ0eXBpc29tAAACAGlzb21pc28yYXZjMW1wNDEAAAAIZnJlZQAAAu1tZGF0AAACrQYF"
      }
    ]
  }'

Step 2: Verify the customer

curl -X POST https://api.sandbox.busha.so/v1/customers/CUS_xxx/verify \
  -H 'Authorization: Bearer YOUR_SECRET_KEY'

Step 3: Check customer status

curl -X GET https://api.sandbox.busha.so/v1/customers/CUS_xxx \
  -H 'Authorization: Bearer YOUR_SECRET_KEY'

Expected status: "status": "in_review" or "status": "active"

Customer Status Flow:

inactive - Default status after creation
in_review - After calling verify endpoint with valid documents
active - After verification approval (automatic in sandbox, manual review in production)

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.
Email validation error: Use real email domains like @gmail.com instead of generic domains like @example.com.
profile_kyc_verification error during verification: Ensure all required documents (ID images and selfie video) are uploaded before calling verify.

What’s Next?

Now that you can programmatically create and verify individual customers, you can proceed to manage them and perform transactions on their behalf:

How to Create a Business Customer: Learn how to create a business customer in your Busha business account.
How to Verify Customer’s Identity (KYC/KYB): Learn more about the verification process and required documents.
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 customer verification webhook events.

Getting Started

Quotes

Deposits

Payouts

Balance

Recipients

Customers

Payment Requests

Widgets

Webhooks

Reference

Create an Individual Customer

Prerequisites

Creating an Individual Customer Account

Complete Example: Create and Verify Customer

Troubleshooting

What’s Next?

Getting Started

Quotes

Deposits

Payouts

Balance

Recipients

Customers

Payment Requests

Widgets

Webhooks

Reference

​Prerequisites

​Creating an Individual Customer Account

​Complete Example: Create and Verify Customer

​Troubleshooting

​What’s Next?

Prerequisites

Creating an Individual Customer Account

Complete Example: Create and Verify Customer

Troubleshooting

What’s Next?