These questions cover the KYB flow forDocumentation 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.
type=business customers. For individual customers (type=individual), see the Webhooks and notifications FAQ and API integration FAQ.
Why does POST /customer/{id}/files return 400 for my business customer?
Because /files (and the matching presigned-URL endpoint POST /file/get-presigned-url) is individual-only. Both endpoints reject type=business customers with 400 — there’s no fallback storage, no orphaned upload, the request just fails.
Business customers use a different flow:
- Add owners (via
POST /customerwith theownersarray, orPUT /customer/{id}after creation). - Upload each owner’s ID files via
POST /customer/{id}/owner/{owner}/file/presigned-urlandPOST /customer/{id}/owner/{owner}/files. - Register KYB documents (cert of inc, articles, bank statements, etc.) via
POST /customer/{id}/document/presigned-urlandPOST /customer/{id}/document. - Call
POST /customer/{id}/submit.
How long does business KYB take?
Typically 1–5 business days. Compliance reviews each owner and each document individually, then issues the customer-level verdict. This is longer than individual KYC (which usually completes within minutes) because business verification involves checks against company registries, beneficial-ownership records, and risk databases. Wait for thecustomer.status_changed webhook. Do not raise support tickets within the standard 5-business-day window — those will not be attended to. Only escalate if a customer has been in PROCESSING for more than 5 business days.
Can I edit an APPROVED owner?
No, not via the API. Once an owner isAPPROVED, the API returns 400 on edit, delete, and file-replacement attempts.
If you need to correct genuine bad data on an APPROVED owner (typo, wrong document, etc.), email support@blaaiz.com with the customer_id, the owner.id, what’s wrong, and supporting evidence. The operations team can correct it on your behalf — see Customer data corrections.
Why did /submit return 422?
/submit enforces a readiness floor — if any check fails, the response is 422 and the message names the specific gap. The most common reasons:
- Customer-level identity missing.
business_name,registration_number, andincorporation_countryare all required, andincorporation_countrymust be a valid ISO 3166-1 alpha-2 code. countrydoes not equalincorporation_country. For businesses, the registered-address country must equal the country of incorporation. When changing the jurisdiction, send both fields together.- No owners. Add at least one owner.
- Ownership percentages don’t sum to 100. Add up your owners’
ownership_percentagevalues; they must total exactly 100. 99.99% won’t pass. - Duplicate owner emails. Emails must be unique within the customer (case-insensitive).
- An owner is missing
id_document_front— run the owner-file flow for that owner. id_document_backis missing or stray.drivers_license,id_card, andresident_permitrequire a back image;passportmust not have one.- An owner’s
date_of_birthis under 18. - An owner’s
id_expiry_dateis in the past. Replace the document with a current one. - Invalid ISO codes for
nationality,country, orid_document_countryon an owner. - No formation document. Register at least one document of type
CERTIFICATE_OF_INCORPORATION,ARTICLES_OF_INCORPORATION,BENEFICIAL_OWNERSHIP_CERTIFICATE,INCORPORATION_DOCUMENTS, orCAC_STATUS_REPORT.
/submit again. The full readiness checklist is in Business customer KYB → Readiness.
Are owner or KYB-document state changes reflected in webhook events?
No. Only the customer-level state change (customer.status_changed) emits a webhook. Per-owner and per-document state changes happen silently from your perspective — they’re internal review noise.
When the customer-level verdict arrives (VERIFIED or REJECTED), fetch the customer with GET /customer/{id} and inspect the owners and documents arrays for per-record status and admin_comments.
Do I still need id_type=certificate_of_incorporation for a business customer?
No — and you can’t send it anymore. For business customers the canonical identifier is registration_number + incorporation_country, both required at create time. The legacy id_type and id_number fields are prohibited on type=business requests (create and update) and return 422. They’re personal-identity columns for individual customers only.
The actual certificate of incorporation file goes into the KYB document collection with type=CERTIFICATE_OF_INCORPORATION, not via /files.
Can a business customer have multiple owners?
Yes — up to 5 per customer. Each owner has their own ID, address, and review state. Theirownership_percentage values must sum to exactly 100 across all owners.
Can I create a type=business customer without owners and add them later?
Yes — but the customer cannot be verified without them. Owners are mandatory for KYB; they’re just not required at create time. You can POST /customer with type=business and the basic profile fields, then later PUT /customer/{id} with an owners array, or attach owners individually before calling /submit.
You can also add or replace owners between cycles if the customer comes back REJECTED. Once you’ve called /submit and the customer is PROCESSING or VERIFIED, every owner — and the customer itself — is locked. Edits return 400. Wait for the customer-level webhook before attempting changes.
Why does editing a rejected owner clear its admin_comments?
When you change any field on a REJECTED owner — or replace its ID file — the API automatically flips that owner’s status back to PENDING and clears its admin_comments. The same applies to REJECTED KYB documents. This signals “the issue compliance flagged has been addressed; please re-review on the next submit.” You don’t manually reset state. Fix the data, then call /submit to re-route the corrected record through review with any other pending records.
APPROVED records are not touched on re-submit — that work isn’t redone.
What’s admin_comments for and how should I display it?
admin_comments is an array of strings written by our compliance reviewers during the review of a specific owner or document. Each entry should be displayed as a separate bullet to your end customer.
Examples of what you might see:
["ID document is expired", "Re-upload a current passport"]["Document image is illegible", "Please re-upload a clearer scan"]["Beneficial ownership certificate does not match the registered owners on the customer record"]
My business customer has three country fields. Which is which?
A business customer carries up to three ISO alpha-2 country codes, each with a distinct meaning:incorporation_country— the legal jurisdiction the company is registered in (e.g. a Delaware LLC hasincorporation_country=US). Top-level on the customer, business-only, required at create time.country— the registered-address country. Top-level. For businesses, this must equalincorporation_countrybecause by company law a company’s registered office is in the country of incorporation. Sending divergent values fails the request.operating_country— the operating-address country, on KYC data. This is the only one that can differ — a UK-incorporated company can operate from Lagos, withincorporation_country=GB,country=GB,operating_country=NG. Required whenever any otheroperating_*field is set.
zip_code is validated against country, operating_zip_code is validated against operating_country. Each address is self-describing.
Can I use a verified business customer for a USD / GBP / EUR Virtual Bank Account?
Yes — provided the customer is onkyb_scope=FULL. NGN VBAs work for both Minimal and Full business customers. USD, GBP, and EUR VBAs are gated to Full — a Minimal customer trying to allocate a non-NGN VBA gets a clear error pointing at the upgrade endpoint.
If you have a Minimal customer who needs non-NGN currencies, use POST /customer/{id}/upgrade-kyb-scope to promote them to Full, attach owners, and re-submit.