> ## Documentation Index
> Fetch the complete documentation index at: https://docs.spherepay.co/llms.txt
> Use this file to discover all available pages before exploring further.
# KYB for Business Customers
> Onboard business customers through KYB verification. Submit company documents, register UBOs, and complete identity verification via API or hosted link.
KYB (Know Your Business) is a legal identity and compliance verification process required before a business customer can send or receive funds through SpherePay. It is mandated by anti-money laundering (AML) and regulatory requirements and must be completed once per business. KYB includes not only verifying the business entity itself, but also verifying the individuals who ultimately own or control it.
## Required information
SpherePay requires the following information to verify a business customer. Fields marked **API** are submitted via request body; fields marked **Document** are uploaded as files.
| Field | Source | Notes |
| ---------------------------------------------------- | -------- | ------------------------------------------------------------------------------------ |
| Legal name, trade name & business description | API | `businessInformation.legalName`, `tradeName`, and `description` |
| Entity type & NAICS industry code | API | `businessInformation.entityType` and `naicsCode` |
| Website & incorporation date | API | `businessInformation.website` and `incorporatedOn` |
| Physical & mailing address | API | `addresses` array — both `registered` and `operating` types required |
| Business identification number | API | `businessInformation.identificationNumber` — accepted types vary by country |
| Estimated annual revenue & expected monthly payments | API | `businessInformation.estimatedAnnualRevenueInUsd` and `expectedMonthlyPaymentsInUsd` |
| Account purpose & source of funds | API | `businessInformation.accountPurpose` and `primarySourceOfFunds` |
| Regulated activities & compliance details | API | `businessInformation.regulatedActivities` and related compliance fields |
| Incorporation certificate | Document | `POST /v2/document` with `documentType: "incorporation_certificate"` |
| Shareholder registry | Document | `POST /v2/document` with `documentType: "shareholder_registry"` |
| Proof of business address | Document | `POST /v2/document` with `documentType: "proof_of_address"` |
| UBO name, residential address & date of birth | API | Provided in the business representative registration request |
| UBO tax identification number | API | `personalInformation.taxIdentificationNumber` in the UBO registration request |
| UBO ownership percentage & role | API | `representationDetails.ownershipPercentage` and `roles` |
| UBO government-issued identity document | Document | `POST /v2/document` with `target: "business-representative"` |
In certain circumstances SpherePay may request additional documentation — for example, for businesses in regulated or high-risk industries, those with complex ownership structures, or those operating in higher-risk jurisdictions. SpherePay will contact you directly when this applies.
## KYB flow overview
The flow below shows the required steps for business KYB. The only step that differs between onboarding models is TOS and MSA acceptance.
1. Create business customer with full `businessInformation` and `addresses`
2. Generate TOS/MSA link → redirect business representative to accept
3. Upload business documents (incorporation certificate, shareholder registry, proof of address)
4. Register each UBO (individuals with ≥ 25% ownership)
5. Upload identity documents for each UBO
6. Complete face liveness verification for each UBO (Sumsub SDK, in-flow)
7. Poll `GET /v2/customer/{id}` until `status` reaches `approved`
1. Create business customer with full `businessInformation` and `addresses`
2. Upload business documents
3. Register each UBO
4. Upload identity documents for each UBO
5. Upload liveness report document for each UBO
6. Poll `GET /v2/customer/{id}` until `status` reaches `approved`
## Integration methods
Full control over each step. Use this for a custom onboarding UX embedded in your product.
Fastest integration. SpherePay hosts the entire verification experience.
***
## KYB via API
Use this guide to onboard a business customer step by step via the SpherePay API. The example below uses the Sphere-Managed model (default).
**Before you begin**, ensure you have:
* A SpherePay API key
* The business's legal details (name, entity type, address, identification number)
* Business documents ready for upload (incorporation certificate, shareholder registry, proof of address)
* UBO information and identity documents for each qualifying individual
Call `POST /v2/customer` with `type: "business"`. Include the full `businessInformation` object and both address types in `addresses`.
```json theme={"dark"}
{
"type": "business",
"email": "contact@acmecorp.example.com",
"phone": "+14155551234",
"addresses": [
{
"type": "registered",
"country": "USA",
"line1": "123 Main Street",
"line2": "Suite 100",
"city": "Chicago",
"state": "IL",
"postalCode": "60601"
},
{
"type": "operating",
"country": "USA",
"line1": "456 Market Street",
"line2": "Floor 10",
"city": "Chicago",
"state": "IL",
"postalCode": "60602"
}
],
"businessInformation": {
"legalName": "Acme Corporation Inc.",
"tradeName": "Acme Corp",
"entityType": "corporation",
"description": "Enterprise software solutions for supply chain management.",
"naicsCode": "511210",
"website": "https://acmecorp.example.com",
"incorporatedOn": "2020-03-15",
"identificationNumberType": "ein",
"identificationNumber": "12-3456789",
"identificationNumberCountry": "USA",
"estimatedAnnualRevenueInUsd": "1000000_9999999",
"expectedMonthlyPaymentsInUsd": "50000",
"accountPurpose": "investment_purposes",
"primarySourceOfFunds": "sales_of_goods_and_services",
"primarySourceOfFundsDescription": "Revenue from software licensing and consulting",
"isDao": false,
"regulatedActivities": ["none_of_the_above"],
"participatesInRegulatedFinancialActivity": false,
"operatesInProhibitedCountries": false
}
}
```
The `businessInformation.identificationNumberType` accepted values vary by country — for example, `ein` for the United States, `uen` for Singapore, or `crn` for the United Kingdom.
Generate a TOS link and redirect the business representative to accept the Terms and Conditions and the Master Service Agreement.
```bash theme={"dark"}
POST https://api.spherepay.co/v2/customer/{id}/tos-link
```
This step can be done in parallel with uploading business documents.
This step applies to the Sphere-Managed model only. In Platform-Managed, TOS and MSA acceptance must be embedded in your platform's own terms prior to onboarding.
Upload the required business documents. Use `target="customer"` for all business entity documents.
```bash theme={"dark"}
curl --location 'https://api.spherepay.co/v2/document' \
--header 'Authorization: Bearer ' \
--form 'target="customer"' \
--form 'targetId="customer_2f283221a9d44ada800ac7f11f640402"' \
--form 'documentType="incorporation_certificate"' \
--form 'file=@"/path/to/your/document.pdf"'
```
Repeat for `shareholder_registry` and `proof_of_address` document types.
A **UBO (Ultimate Beneficial Owner)** is any individual who owns **25% or more** of the company. Register each qualifying individual via `POST /v2/business-representative`. Repeat this step for every UBO.
```json theme={"dark"}
{
"customerId": "customer_2f283221a9d44ada800ac7f11f640402",
"type": "individual",
"email": "james.wilson@acmecorp.example.com",
"phone": "+13125559876",
"address": {
"line1": "742 North Wabash Avenue",
"line2": "Apt 4B",
"city": "Chicago",
"state": "IL",
"postalCode": "60611",
"country": "USA"
},
"personalInformation": {
"taxIdentificationNumber": "987654321",
"taxIdentificationNumberType": "ssn",
"taxIdentificationNumberCountry": "USA"
},
"representationDetails": {
"roles": ["ubo"],
"ownershipPercentage": "50",
"isControlPerson": true,
"isSigner": true,
"title": "CEO",
"relationshipEstablishedAt": "2020-03-15"
}
}
```
All individuals who meet the 25% ownership threshold must be registered and verified. If more than one individual qualifies, repeat this step for each one.
Upload identity documents for each UBO. Use `target="business-representative"` — these documents belong to the individual, not the business entity.
```bash theme={"dark"}
curl --location 'https://api.spherepay.co/v2/document' \
--header 'Authorization: Bearer ' \
--form 'target="business-representative"' \
--form 'targetId="associatedPerson_4914a2f6226e42cc8d207ead9573b29f"' \
--form 'documentType="id_card"' \
--form 'side="front"' \
--form 'file=@"/path/to/your/document.jpg"' \
--form 'country="SGP"'
```
Each UBO requires liveness verification. Check the UBO's `required` array via `GET /v2/business-representative/{id}`, then perform **exactly one** of the following:
* **`liveness_check` in required** — Generate a face verification link for the UBO and redirect them to complete an interactive liveness check via the Sumsub SDK.
* **`liveness_report_document` in required** — Upload a liveness report document for the UBO from your identity verification provider.
Repeat for each registered UBO.
Once all required steps are complete for both the business and its UBOs, SpherePay processes the verification automatically — no submit call is needed. Poll `GET /v2/customer/{id}` until `status` reaches `approved`.
```json theme={"dark"}
{
"id": "customer_2f283221a9d44ada800ac7f11f640402",
"email": "contact@acmecorp.example.com",
"verificationProfiles": [
{
"name": "kyb_profile_a",
"status": "approved",
"criteria": {
"complete": [
"email_address",
"phone_number",
"operating_address",
"registered_address",
"legal_name",
"identification_number",
"business_representatives",
"incorporation_cert_document",
"shareholder_registry_document",
"proof_of_address_document"
],
"pending": [],
"required": [],
"errors": []
}
}
],
"type": "business"
}
```
When `required` is empty and `status` is `approved`, the business customer is fully onboarded and ready to transfer.
KYB review typically takes 2–7 business days after all required documents and data are submitted.
***
## What's next
Once the business customer's verification profile is `approved`, register their payment methods and initiate a transfer.
Register a bank account so the business can send or receive funds via bank rail.
Register a crypto wallet address to enable on-ramp and off-ramp transfers.
Create and manage transfers once the customer has registered their payment methods.
Understand verification statuses, criteria arrays, and what triggers state changes.