Create a customer

Create a new customer. Verification stays PENDING until the type-specific verification flow completes.

For type=individual, id_type and id_number are required. After creation, upload identity files via the legacy KYC flow (see Creating your first payout). Only Driver's License, Passport, or Resident Permit are accepted as id_type.

For type=business, business_name + registration_number + incorporation_country are required. The legacy id_type / id_number fields are no longer required (still accepted for back-compat — when supplied, id_type must be certificate_of_incorporation). After creation, follow the Business customer KYB flow: register beneficial owners, upload owner ID files, register KYB documents, then call /submit.

ID cards (National Identity Cards) are not accepted at any stage. All uploaded documents must be clear, legible, and authentic — unclear images will be rejected. Fraudulent or falsified documents will result in the customer being permanently blacklisted from the platform.

Required scope: customer:write.

POSTapi-prod.blaaiz.com/api/external/customer

Authorization

oauth2ClientCredentials customer:write

AuthorizationBearer <token>

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

In: header

Scope: customer:write

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

type*string

Customer type.

Value in

"individual"
"business"

kyb_scope?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.

Value in

"FULL"
"MINIMAL"

email*string

Formatemail

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

Value in

"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

Formatdate

street?string

city?string

state?string

zip_code?string

id_expiry_date?string

Formatdate

id_issue_date?string

Formatdate

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?string

Business KYB field. Legal entity type.

Value in

"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

Business KYB field. Must be in the past.

Formatdate

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

Business KYB field. Public website URL.

Formaturi

source_of_funds?string

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

Value in

"business_revenue"
"business_loans"
"investment_income"
"third_party_funds"
"other"

estimated_annual_revenue?string

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

Value in

"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?string

Business KYB field. Stated purpose of the Blaaiz account.

Value in

"receive_payments_for_goods_and_services"
"send_payments_for_goods_and_services"
"send_receive_funds_related_parties"
"other"

owners?array<>

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.

Itemsitems <= 5

Response Body

`application/json`

Create a customer

curl --request POST \  --url 'https://example.com/api/external/customer' \  --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  }}