> ## 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 |
| Company registration number | API | `businessInformation.registrationNumber` and `registrationNumberType` — required for EEA+ businesses. Distinct from the tax ID. See [EEA+ businesses](#eea-businesses) |
| 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"` |
EEA+ businesses must also provide a company registration number and complete KYC for directors, signers, and control persons, not only 25%+ owners. See [EEA+ businesses](#eea-businesses).
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 associated persons (UBOs with ≥ 25% ownership; EEA+ businesses also require directors, control persons, and signers)
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.
EEA+ businesses must also provide `registrationNumber` and `registrationNumberType`. These are separate from the tax identification number. See [EEA+ businesses](#eea-businesses).
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.
You can also register directors, control persons, and authorized signers. `representationDetails.roles` accepts `ubo` and `director` (up to two distinct roles). `ownershipPercentage` accepts any integer from 0 to 100; if the `ubo` role is present, ownership must still be ≥ 25.
```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. EEA+ businesses have additional associated-person requirements — see [EEA+ businesses](#eea-businesses).
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.
***
## EEA+ businesses
Sphere enforces additional KYB fields and associated-person requirements for businesses incorporated in the EEA+ region, in line with MiCA. Businesses outside EEA+ are unaffected. `accountPurpose` was already required for all businesses — that does not change.
EEA+ is the EEA plus the United Kingdom, Switzerland, Andorra, and several EU overseas territories (Åland Islands, French Guiana, Guadeloupe, Martinique, Mayotte, Réunion, Saint Martin). Scope is keyed off the business's registered address country (`country` on the address with `type: "registered"`). Business representatives inherit EEA+ scope from the parent business. See [EEA+ region](/concepts/onboarding/overview#eea-region) for the full definition.
### Registration number
EEA+ businesses must provide both of the following under `businessInformation` on `POST /v2/customer`:
| Field | Status | Required |
| ------------------------ | -------- | -------------------------------------------------------------------------------------------------------- |
| `registrationNumber` | Existing | Required for EEA+ businesses before verification |
| `registrationNumberType` | New | Required whenever `registrationNumber` is provided, and required for EEA+ businesses before verification |
The registration number is stored and verified separately from the tax ID (`identificationNumber`). Do not submit a VAT or tax number as the registration number.
`registrationNumberType` is validated against the registered-address country. Examples:
| Country | Accepted `registrationNumberType` values |
| ---------------------------------- | ---------------------------------------- |
| Austria | `fn` |
| Belgium | `bce`, `kbo` |
| Denmark | `cvr` |
| France | `siren`, `siret` |
| Germany | `crn` |
| Ireland | `cro` |
| Italy | `cf` |
| Netherlands | `kvk` |
| Norway | `org`, `orgnr` |
| Sweden | `org`, `orgnr` |
| Poland | `krs` |
| Portugal | `nipc` |
| Spain | `cif` |
| United Kingdom | `crn` |
| Countries with no defined type set | `other` |
Validation behavior:
* An EEA+ business missing `registrationNumber` or `registrationNumberType` cannot be submitted for verification. Submitting returns **422**.
* A `registrationNumberType` that is not valid for the registered-address country returns **422** listing the allowed types.
* Non-EEA businesses may continue to supply `registrationNumber` without a type. That behavior is unchanged.
The outstanding item surfaces as the `registration_number` requirement code on `kyb_profile_a` (EEA+ only). Sphere excludes this code for businesses outside EEA+.
You can backfill existing EEA+ businesses with `PATCH /v2/customer/{id}`. Validation runs on the merged customer state.
### Business representatives
EEA+ businesses have a broader associated-person scope than businesses outside EEA+.
**Director role.** `representationDetails.roles` accepts `director` alongside `ubo`, with up to two distinct roles.
**Ownership percentage.** `ownershipPercentage` accepts any integer from 0 to 100 (the previous minimum was 25). If the `ubo` role is present, ownership must still be ≥ 25. A representative without the `ubo` role — for example, director-only — may hold 0–24.
Call `POST /v2/business-representative` with the new role values:
```json theme={"dark"}
{
"representationDetails": {
"roles": ["ubo", "director"],
"ownershipPercentage": "40",
"isControlPerson": true,
"isSigner": true,
"title": "Managing Director"
}
}
```
The example highlights the new role and ownership values. Include the other representative fields required at creation (`customerId`, `type`, `email`, `phone`, `address`, and `personalInformation`) as usual.
**Country of birth and nationality.** For EEA+ businesses, each representative must provide `countryOfBirth` and `nationality` under `personalInformation`. Until they are supplied, they surface as `country_of_birth` and `nationality` on the representative's `ubo_kyc_profile_a` profile. Sphere excludes these codes for representatives of businesses outside EEA+.
You can backfill existing representatives with `PATCH /v2/business-representative/{id}`. Validation runs on the merged representative state.
### Business-level requirement codes
These codes appear on the business customer's `kyb_profile_a` profile for EEA+ businesses only. Sphere excludes them for businesses outside EEA+.
| Code | Meaning |
| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| `registration_number` | Provide `businessInformation.registrationNumber` and `registrationNumberType` |
| `eea_control_person_present` | At least one representative with `isControlPerson: true` |
| `eea_ap_kyc_scope` | At least one director on file, and every director, signer, control person, and ≥ 25% owner completes full identity verification |
For businesses outside EEA+, associated-person KYC scope is unchanged: only 25%+ owners.
***
## 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.