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"
      }
    ]
  }
}

Customer

Upgrade a business customer from MINIMAL to FULL KYB

Promote a kyb_scope=MINIMAL business customer to kyb_scope=FULL by attaching beneficial-owner data. Identity columns (registration_number, incorporation_country) are typically already on file from MINIMAL onboarding.

Eligibility checks (return 422 on failure):

Customer exists and belongs to your platform.
Customer is type=business.
Customer is currently kyb_scope=MINIMAL (or has no scope set, treated as Minimal). A FULL customer cannot be “upgraded” again.
Customer is not PROCESSING (rejected with 400 — wait for the customer-level webhook before retrying).

Validation (return 422 on failure):

At least one owner.
Ownership percentages sum to exactly 100.
Per-owner identity invariants (DOB ≥ 18, expiry future, valid ISO codes where supplied).
Owner emails unique within the customer.
If you send registration_number / incorporation_country overrides, they must satisfy the same rules as create.
If you send country to update jurisdiction, the resulting country and incorporation_country must match.

On success:

New owners are saved on the customer.
kyb_scope flips to FULL.
If the customer was VERIFIED, verification_status flips back to PENDING (re-onboarding under stricter rules). Existing NGN VBAs are unaffected.
An audit comment is recorded.
A customer.status_changed webhook fires for the verification-status transition (if any).

Important: This endpoint does NOT run the Standard readiness checks. Owner ID files are not part of this payload — upload them per-owner via POST /api/external/customer/{id}/owner/{owner}/files after the upgrade succeeds. Then call POST /api/external/customer/{id}/submit to re-verify the customer under the Standard checks.

Required scope: customer:write.

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"
      }
    ]
  }
}

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

Show child attributes

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

Show child attributes

Submit customer for verification List customer KYB documents

⌘I