Create and Manage Customers

This guide provides a technical walkthrough on programmatically creating customer accounts 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 users.

What You’ll Achieve:

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

PrerequisitesCopied!

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

Step 1: Understand Customer Creation ParametersCopied!

The essential parameters for creating a customer are:

Parameter	Type	Description
`email`	`string`	The customer's email address.
`has_accepted_terms`	`boolean`	A flag indicating whether the customer has acknowledged and accepted your platform's (or Busha's) terms and conditions. Often a prerequisite for certain actions.
`type`	`string`	The classification of the customer. Expected values are `individual` or `business`. This field dictates which other specific fields (e.g., `first_name` vs. `business_name`) are applicable.
`country_id`	`string`	The ISO 3166-1 alpha-2 country code representing the customer's primary country of residence or operation.
`phone`	`string`	The customer's phone number, including the international country code (e.g., `+234 8012345678`).
`birth_date`	`string`	The customer's date of birth, typically required for individual identity verification. The format appears to be `DD-MM-YYYY`.
`address`	`object`	An object containing the customer's full physical address details. See the `Address Object Parameters` table below for nested fields.
`first_name`	`string`	The individual customer's first name. (Required if `type` is `individual`).
`middle_name`	`string`	The individual customer's middle name.
`last_name`	`string`	The individual customer's last name. (Required if `type` is `individual`).
`business_name`	`string`	The legal name of the business customer. (Required if `type` is `business`).
`registration_number`	`string`	The official registration number of the business. (Relevant if `type` is `business`).

For the address object above, the table below details the fields nested in the object:

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 (may be optional or region-specific).
`country_id`	`string`	The ISO 3166-1 alpha-2 country code of the address. For example, “NG”
`address_line_1`	`string`	The first line of the street address.
`address_line_2`	`string`	The second line of the street address (e.g., apartment, suite number, or building name).
`province`	`string`	The province component of the address (may be optional or region-specific).
`postal_code`	`string`	The postal or ZIP code of the address.

Step 2: Create an Individual CustomerCopied!

Individual customers refer to persons that engage with your services. Let’s create an individual customer for your Busha Business account.

To create an individual customer:

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": "trybusha@busha.so",
        "has_accepted_terms": true,
        "type": "individual",
        "country_id": "NG",
        "phone": "+234 8012345678",
        "birth_date": "24-12-2000",
        "address": {
          "city": "Lekki",
          "state": "Lagos",
          "county": "Mombasa",
          "country_id": "NG",
          "address_line_1": "RT Lawal",
          "address_line_2": "",
          "province": "province",
          "postal_code": "12345"
   },
   "first_name": "Busha",
   "middle_name": "Crypto",
   "last_name": "Mascot"
}'

Expected Response:

A successful response will return a Customer object, providing the customer ID (CUS_IL2Qf2pEoNADZ), the customer type (individual) as set in the request body and the status of the customer.

The default status of a customer is inactive until the user completes their Know-Your-Customer (KYC) process.

{
  "status": "success",
  "message": "Created customer successfully",
  "data": {
    "address": {
      "address_line_1": "RT Lawal",
      "address_line_2": "",
      "city": "Lekki",
      "country_id": "NG",
      "county": "Mombasa",
      "postal_code": "12345",
      "province": "province",
      "state": "Lagos"
    },
    "business_id": "BUS_jlKUYwF9z1ynQZ98bWbaP",
    "country_id": "NG",
    "created_at": "2025-06-25T22:08:08.978994644Z",
    "deposit": true,
    "display_currency": "NGN",
    "email": "trybusha@busha.so",
    "first_name": "Busha",
    "has_accepted_terms_of_service": true,
    "id": "CUS_IL2Qf2pEoNADZ",
    "last_name": "Mascot",
    "middle_name": "Crypto",
    "payout": true,
    "phone": "+234 8012345678",
    "status": "inactive",
    "type": "individual",
    "updated_at": "2025-06-25T22:08:08.978994644Z"
  }
}

Step 3: Create a Business Customer Copied!

Business customers like you represent legal entities that utilize your offerings. Their legal and statutory details identify them.

To create a business customer:

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://api.sandbox.busha.so/v1/customers \
  -H 'Authorization: Bearer STV0ckQwSTZaeDpPQTJJODh5RkMwbDhPaVFTV1VMVzBjRWozTWljdkVqdDhkdUVicW10andQZzcwUGE=' \
  -H 'Content-Type: application/json' \
-d '{
  "email": "godisgoodcrypto@gmail.com",
  "has_accepted_terms": true,
  "type": "business",
  "country_id": "NG",
  "phone": "+234 8012345678",
  "birth_date": "24-12-2000",
  "business_name": "Busha Pay",
  "business_industry": "BIN_C4UvTYR5V8jsOx5LmwQ",
  "business_incorporation_date": "2019-08-24"
}'

Expected Response:

A successful response will return a Customer object, providing the customer id , the type of the customer business) and the status of the customer.

The default status of a customer is inactive until the user completes their Know-Your-Business (KYB) process.

{
  "status": "success",
  "message": "Created customer successfully",
  "data": {
    "address": {
      "address_line_1": "",
      "country_id": ""
    },
    "business_id": "BUS_jlKUYwF9z1ynQZ98bWbaP",
    "business_incorporation_date": "2019-08-24",
    "business_industry": "BIN_C4UvTYR5V8jsOx5LmwQ",
    "business_name": "Busha Pay",
    "country_id": "NG",
    "created_at": "2025-06-26T08:59:30.835471769Z",
    "deposit": true,
    "display_currency": "NGN",
    "email": "godisgoodcrypto@gmail.com",
    "has_accepted_terms_of_service": true,
    "id": "CUS_B912WgfXH0I4U",
    "payout": true,
    "phone": "+234 8012345678",
    "status": "inactive",
    "type": "business",
    "updated_at": "2025-06-26T08:59:30.835471769Z"
  }
}

Step 3: Retrieve and List CustomersCopied!

After creating customers, you’ll often need to retrieve their details or get a list of all customers associated with your business account. This allows you to manage operations and ensure you’re using the correct customer_id for transactions.

Retrieve a Specific Customer

You can fetch the details of a single customer from their ID.

To retrieve a specific customer:

Open your terminal or command prompt.
Construct a GET request to the /v1/customers/{customer_id} endpoint, replacing {customer_id} with the actual customer ID.
Ensure your Authorization and YOUR_SECRET_TOKEN headers are included.
Replace placeholders like YOUR_BASE_URL and YOUR_SECRET_TOKEN.

$ curl -i -X GET https://YOUR_BASE_URL/v1/customers/{id} \
  -H 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  -H 'Content-Type: application/json'

Expected Response:

A successful response will return a single customer object, identical in structure to the one received during creation, containing all its details:

{
  "status": "success",
  "message": "Fetched customer successfully",
  "data": {
    "address": {
      "address_line_1": "RT Lawal",
      "address_line_2": "",
      "city": "Lekki",
      "country_id": "NG",
      "county": "Mombasa",
      "postal_code": "12345",
      "province": "province",
      "state": "Lagos"
    },
    "business_id": "BUS_jlKUYwF9z1ynQZ98bWbaP",
    "country_id": "NG",
    "created_at": "2025-06-25T22:08:08.978994Z",
    "deposit": true,
    "display_currency": "NGN",
    "email": "trybusha@busha.so",
    "first_name": "Busha",
    "has_accepted_terms_of_service": true,
    "id": "CUS_IL2Qf2pEoNADZ",
    "last_name": "Mascot",
    "middle_name": "Crypto",
    "payout": true,
    "phone": "+234 8012345678",
    "status": "inactive",
    "type": "individual",
    "updated_at": "2025-06-25T22:08:08.978994Z"
  }
}

List All Customers

To get an overview of all the customers you have created, you can make a GET request to the /v1/customers endpoint without specifying an ID.

To list all customers:

Open your terminal or command prompt.
Construct a GET request to the /v1/customers endpoint.
Ensure your Authorization header is included.
Replace placeholders like YOUR_BASE_URL and YOUR_SECRET_TOKEN.

$ curl -i -X GET 'https://api.busha.co/v1/recipients' \
  -H 'Authorization: Bearer YOUR_SECRET_TOKEN'

Expected Response

A successful response will return a list (an array) of all recipient objects associated with your account.

{
  "status": "success",
  "message": "Fetched customers successfully",
  "data": [
    {
      "address": {
        "address_line_1": "RT Lawal",
        "address_line_2": "",
        "city": "Lekki",
        "country_id": "NG",
        "county": "Mombasa",
        "postal_code": "12345",
        "province": "province",
        "state": "Lagos"
      },
      "business_id": "BUS_jlKUYwF9z1ynQZ98bWbaP",
      "country_id": "NG",
      "created_at": "2025-06-25T22:08:08.978994Z",
      "deposit": true,
      "display_currency": "NGN",
      "email": "trybusha@busha.co",
      "first_name": "Busha",
      "has_accepted_terms_of_service": true,
      "id": "CUS_IL2Qf2pEoNADZ",
      "last_name": "Mascot",
      "middle_name": "Crypto",
      "payout": true,
      "phone": "+234 8012345678",
      "status": "inactive",
      "type": "individual",
      "updated_at": "2025-06-25T22:08:08.978994Z"
    }    
  ],
  "pagination": {
    "current_entries_size": 1,
    "previous_cursor": "MDAwMS0wMS0wMVQwMDowMDowMFo="
  }
}

TroubleshootingCopied!

400 Bad Request / 422 Unprocessable Entity: Review your request body to ensure all required fields are present and correctly formatted for the specified type (individual or business).
401 Unauthorized: Verify that your Secret API Key is correct and included in the header.

What’s Next?Copied!

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

How to Verify Customer’s Identity (KYC): Learn how to conduct and verify the identity of your customer to allow them full access to Busha’s operations.
How to Verify Business Customer’s Identity (KYB): Learn how to conduct and verify the identity of your business customers to allow them full access to Busha’s operations.
How to Initiate Transactions on Behalf of a Customer: Understand how to use the customer_id to perform operations for your customers.