Skip to main content
POST
/
api
/
external
/
customer
/
{customer}
/
upgrade-kyb-scope
Upgrade a business customer from MINIMAL to FULL KYB
curl --request POST \
  --url https://api-prod.blaaiz.com/api/external/customer/{customer}/upgrade-kyb-scope \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "trading_name": "Acme",
  "business_type": "llc",
  "incorporation_date": "2019-03-12",
  "industry_type": "Software & SaaS",
  "business_description": "B2B SaaS platform.",
  "website": "https://acme.example.com",
  "source_of_funds": "business_revenue",
  "estimated_annual_revenue": "1000000_4999999",
  "expected_monthly_payments": 250,
  "account_purpose": "send_receive_funds_related_parties",
  "owners": [
    {
      "first_name": "Jane",
      "last_name": "Doe",
      "email": "jane@acme.example.com",
      "date_of_birth": "1985-04-22",
      "nationality": "NG",
      "title": "CEO",
      "ownership_percentage": 60,
      "has_control": true,
      "is_signer": true,
      "is_beneficial_owner": true,
      "id_document_type": "passport",
      "id_document_number": "A12345678",
      "id_document_country": "NG",
      "id_expiry_date": "2030-01-15",
      "is_pep": false
    },
    {
      "first_name": "John",
      "last_name": "Smith",
      "ownership_percentage": 40,
      "is_beneficial_owner": true
    }
  ]
}
'
{
  "message": "Customer KYB scope upgraded to FULL. Upload owner ID files and call /submit to re-verify.",
  "data": {
    "id": "019a6da3-4a9a-7033-81b9-12489eff13ee",
    "type": "business",
    "kyb_scope": "FULL",
    "verification_status": "PENDING",
    "business_name": "Acme Nigeria Limited",
    "registration_number": "RC123456",
    "incorporation_country": "NG",
    "country": "NG",
    "owners": [
      {
        "id": "019a6e22-8b4c-7c8d-9d12-c0c1ab3f1a90",
        "first_name": "Jane",
        "last_name": "Doe",
        "ownership_percentage": 60,
        "status": "PENDING"
      },
      {
        "id": "019a6e22-8b4c-7c8d-9d12-d1d2bc4e2b91",
        "first_name": "John",
        "last_name": "Smith",
        "ownership_percentage": 40,
        "status": "PENDING"
      }
    ]
  }
}

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.

Path Parameters

​
customer
string<uuid>
required

Body

application/json
​
owners
object[]
required

Beneficial owners, signatories, and directors. Required, at least one owner. The sum of every owner's ownership_percentage must equal exactly 100 (validated at this endpoint). Per-owner ID files are uploaded after the upgrade succeeds, via the dedicated owner-file endpoints — they're not part of this payload.

Required array length: 1 - 5 elements
​
registration_number
string

Optional override. The business registration / company number is already on the customer from MINIMAL onboarding (canonical for both scopes), so you typically don't send this. Send it only to update the value during the upgrade. Subject to the standard uniqueness rule on (business_id, registration_number, incorporation_country).

​
incorporation_country
string

Optional override. Already on the customer from Minimal onboarding. Send only if you want to update the value during the upgrade. Must match the customer's country after your changes are applied — if they don't match, the request returns 422.

​
country
string

Optional. Update the registered-address country alongside incorporation_country when correcting jurisdiction during the upgrade. The resulting country and incorporation_country must match.

​
trading_name
string

Optional augmentation. Trading or 'doing business as' name.

​
business_type
enum<string>

Optional augmentation. Legal entity type.

Available options:
corporation,
government_entity,
llc,
non_profit,
other,
partnership,
sole_proprietorship
​
incorporation_date
string<date>

Optional augmentation. Must be in the past.

​
industry_type
string

Optional augmentation.

​
business_description
string

Optional augmentation. Max 2000 chars.

​
website
string<uri>

Optional augmentation.

​
source_of_funds
enum<string>

Optional augmentation.

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

Optional augmentation. 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

Optional augmentation.

​
account_purpose
enum<string>

Optional augmentation.

Available options:
receive_payments_for_goods_and_services,
send_payments_for_goods_and_services,
send_receive_funds_related_parties,
other
​
operating_street
string
​
operating_city
string
​
operating_state
string
​
operating_zip_code
string

Validated against operating_country.

​
operating_country
string

ISO alpha-2. Required whenever any other operating_* field is supplied.

Response

Customer upgraded. kyb_scope is now FULL. Owner ID files still need to be uploaded; then call /submit to re-verify under the FULL floor.

​
message
string
required
​
data
object
required

Updated customer record after the upgrade. kyb_scope is now FULL. verification_status is PENDING (or whatever the customer was, except VERIFIED which transitions to PENDING automatically). Same shape as GET /customer/{id}.