Skip to main content
POST
/
api
/
external
/
customer
curl --request POST \
  --url https://api-prod.blaaiz.com/api/external/customer \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "type": "individual",
  "first_name": "John",
  "last_name": "Doe",
  "email": "john.doe@company.com",
  "country": "NG",
  "id_type": "passport",
  "id_number": "6733823632872",
  "phone": "+2348012345678",
  "dob": "1990-01-15",
  "street": "123 Main Street",
  "city": "Lagos",
  "state": "Lagos",
  "zip_code": "100001",
  "id_expiry_date": "2030-01-15",
  "id_issue_date": "2020-01-15"
}
'
{
  "message": "Customer created successfully.",
  "data": {
    "id": "9d4c4ec5-59ea-4130-bf8a-6a5edec401ee",
    "business_id": "9d4c4ec5-572d-49de-a362-f01ed09f2b1b",
    "first_name": "John",
    "last_name": "Doe",
    "business_name": null,
    "type": "individual",
    "email": "john.doe@company.com",
    "country": "NG",
    "id_type": "passport",
    "id_number": "6733823632872",
    "verification_status": "PENDING",
    "kyb_scope": null
  }
}

Documentation Index

Fetch the complete documentation index at: https://docs.business.blaaiz.com/llms.txt

Use this file to discover all available pages before exploring further.

Authorizations

​
Authorization
string
header
required

Use your OAuth client credentials to obtain a short-lived Bearer token from POST /oauth/token.

Body

application/json
​
type
enum<string>
required

Customer type.

Available options:
individual,
business
​
email
string<email>
required
​
kyb_scope
enum<string>

Business-only. Selects what data we require to onboard the customer, and which currencies they can hold a Virtual Bank Account in.

  • FULL (Standard KYB) — Business identity (name, registration number, country of incorporation), beneficial owners summing to 100% ownership, an ID file for each owner, plus a formation document. Eligible for NGN / USD / GBP / EUR VBAs.
  • MINIMAL — Same business identity as Full, without owners or per-owner ID files, plus a formation document. Eligible for NGN VBAs only.

Who can use MINIMAL: Minimal is gated by an admin-controlled allow list. Allow-listed platforms who omit kyb_scope default to MINIMAL and can pass FULL explicitly when they need a customer to qualify for non-NGN currencies. Platforms not on the list get FULL by default — sending MINIMAL returns 422. Forbidden on type=individual (returns 422).

Direction is one-way: a MINIMAL customer can be upgraded via POST /customer/{id}/upgrade-kyb-scope. There is no downgrade. See the Business customer KYB guide.

Available options:
FULL,
MINIMAL
​
country
string

ISO alpha-2 country code of the registered address. Required for both type=individual and type=business. For individuals, must match the country on the identity document. For businesses, must equal incorporation_country — a company's registered office sits in its country of incorporation by company law (cross-field check at validation time).

​
id_type
enum<string>

Personal identity document type. Individual customers only.

  • type=individual — required. Must be drivers_license, passport, or resident_permit.
  • type=business — prohibited. Businesses identify via registration_number + incorporation_country regardless of kyb_scope. Sending id_type on a business returns 422.
Available options:
drivers_license,
passport,
resident_permit
​
id_number
string

Personal identity document number. Individual customers only.

  • type=individual — required. The number on the document supplied via id_type.
  • type=business — prohibited. Businesses identify via registration_number. Sending id_number on a business returns 422.
​
first_name
string

Required if type is individual.

​
last_name
string

Required if type is individual.

​
business_name
string

Required if type is business.

​
phone
string
​
tin
string

Tax identification number (varies by country). Where applicable, use the Get Identification Type endpoint to determine the correct label or field to collect for the customer's country and type.

​
dob
string<date>
​
street
string
​
city
string
​
state
string
​
zip_code
string
​
id_expiry_date
string<date>
​
id_issue_date
string<date>
​
operating_street
string

Business operating address — street. Use when the operating address differs from the registered (street) address.

​
operating_city
string

Business operating city.

​
operating_state
string

Business operating state.

​
operating_zip_code
string

Business operating zip / postal code. Validated against operating_country (not country) — the operating address is self-describing.

​
operating_country
string

Business operating address country, as ISO alpha-2. Required whenever any other operating_* field is supplied. Can differ from country and incorporation_country when the business operates from a different jurisdiction. Anchors postal-code validation for operating_zip_code.

​
trading_name
string

Business KYB field. Trading or 'doing business as' name.

​
business_type
enum<string>

Business KYB field. Legal entity type.

Available options:
corporation,
government_entity,
llc,
non_profit,
other,
partnership,
sole_proprietorship
​
registration_number
string

Business registration / company number from the issuing authority. Required for every business customer regardless of kyb_scope. Together with incorporation_country, this is the canonical identifier for a business customer.

Unique per platform: two of your customers cannot share the same (registration_number, incorporation_country) pair. The same number is fine across different incorporation countries (jurisdictions overlap), and across different platforms.

​
incorporation_country
string

Legal jurisdiction of incorporation, as ISO alpha-2. Required for every business customer regardless of kyb_scope. Distinct from country (registered-address country) and operating_country (operating-address country); for businesses, country must equal incorporation_country (a company's registered office sits in its country of incorporation).

​
incorporation_date
string<date>

Business KYB field. Must be in the past.

​
industry_type
string

Business KYB field. Free-form industry/sector descriptor.

​
business_description
string

Business KYB field. Description of the business activity (max 2000 chars).

​
website
string<uri>

Business KYB field. Public website URL.

​
source_of_funds
enum<string>

Business KYB field. Where the business's funds originate.

Available options:
business_revenue,
business_loans,
investment_income,
third_party_funds,
other
​
estimated_annual_revenue
enum<string>

Business KYB field. Estimated annual revenue band, in USD.

Available options:
0_99999,
100000_499999,
500000_999999,
1000000_4999999,
5000000_24999999,
25000000_99999999,
100000000_249999999,
250000000_plus
​
expected_monthly_payments
integer

Business KYB field. Expected monthly payment count (0–1,000,000,000).

​
account_purpose
enum<string>

Business KYB field. Stated purpose of the Blaaiz account.

Available options:
receive_payments_for_goods_and_services,
send_payments_for_goods_and_services,
send_receive_funds_related_parties,
other
​
owners
object[]

Business KYB field. Beneficial owners, signatories, and directors. Up to 5 entries. Each entry's ownership_percentage must sum across all owners to exactly 100 before /submit will accept the customer.

Maximum array length: 5

Response

Customer created successfully.

​
message
string
required
​
data
object
required