New: Streamlined onboarding defaults  View changelog →
Customers & OnboardingKYB Integration Guide

KYB via API

This guide walks you through the process of onboarding business customers using the Customer KYB API.

Introduction

To initiate the KYB process via API, include all required business information fields in the customer creation request. Once submitted, the customer information is verified programmatically. Business documents and UBO (business representative) identification documents must then be uploaded to complete the KYB process.

Information

This method applies only to business customers and is not supported for individual customers.

Before you begin

Ensure you have:

  • A SpherePay API key — see Authentication
  • The business's legal details ready (name, entity type, address, identification number)
  • Business documents ready for upload (incorporation certificate, shareholder registry, proof of address)
  • UBO information and identity documents ready for each qualifying individual

KYB via API Flow

For the full list of required business documents and their API values, see Business Document Guideline.

Core Steps

The following steps are required for every KYB API integration.

1. Create a Customer

To create a customer, you can use the Create Customer endpoint.

POST https://api.spherepay.co/v2/customer

Information

When using the API integration path, include businessInformation and full addresses in the creation request. These fields allow SpherePay to verify the business identity programmatically — you will not need to generate a KYB link. You will still need to upload business documents and complete UBO registration and verification in the following steps.

Request Example

{
  "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": "Acme Corporation provides enterprise software solutions for supply chain management and logistics optimization.",
    "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 services",
    "isDao": false,
    "regulatedActivities": ["none_of_the_above"],
    "participatesInRegulatedFinancialActivity": false,
    "operatesInProhibitedCountries": false
  }
}

Business Identification Fields

The businessInformation object includes identification details for the business. The accepted values depend on the business's country of incorporation:

  • identificationNumberCountry — The business's country code (e.g. USA, SGP, GBR).
  • identificationNumberType — The type of identification number. Accepted values vary by country — for example, ein for the United States, uen for Singapore, or crn for the United Kingdom.
  • identificationNumber — The actual identification number.
  • identificationNumberDescription — A human-readable description of the document type. Optional — only required when identificationNumberType is other.

For the full list of accepted business identification types and codes by country, see Business Identification Types by Country.

2. Upload Business Documents

Upload the required business documents to verify the company's identity, legal standing, and ownership structure. These documents use target="customer" since they belong to the business entity itself.

Required Business Documents

For the full list of required business documents and their API values, see Business Document Guideline.

To upload documents, use the Upload Document endpoint.

POST https://api.spherepay.co/v2/document

Request Example

curl --location 'https://api.spherepay.co/v2/document' \
--header 'Authorization: Bearer <your_api_key>' \
--form 'target="customer"' \
--form 'targetId="customer_2f283221a9d44ada800ac7f11f640402"' \
--form 'documentType="incorporation_certificate"' \
--form 'file=@"/path/to/your/document.pdf"'

Response Example

{
  "target": "customer",
  "targetId": "customer_2f283221a9d44ada800ac7f11f640402",
  "documentType": "incorporation_certificate",
  "fileName": "document.pdf",
  "fileSize": 1048576,
  "mimeType": "application/pdf",
  "createdAt": "2025-05-23T11:30:00Z"
}

3. Register Business Representative (UBO)

A business representative, also known as an Ultimate Beneficial Owner (UBO), is any individual who owns 25% or more of the company. All individuals meeting this threshold must be registered — repeat this step for each qualifying UBO.

To register a business representative, use the Register Business Representative endpoint.

POST https://api.spherepay.co/v2/business-representative

Request Example

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

Personal Information Fields

The personalInformation object contains the UBO's tax identification details. The accepted values depend on the representative's country of residence:

  • taxIdentificationNumberCountry — The representative's country code (e.g. USA, SGP, GBR).
  • taxIdentificationNumberType — The type of identification number. Accepted values vary by country — for example, ssn for the United States, nric for Singapore, or nino for the United Kingdom.
  • taxIdentificationNumber — The actual identification number.
  • taxIdentificationNumberDescription — A human-readable description of the document type. Required when taxIdentificationNumberType is other.

For the full list of accepted identification types and codes by country, see Individual Identification Numbers by Country.

4. Upload Identification Documents for Business Representative (UBO)

Once the business representative (UBO) has been registered, upload their identification documents. These documents use target="business-representative" since they belong to the individual representative, not the business entity.

Required UBO Documents

For the full list of accepted identification documents for individuals, see Document Guideline.

To upload documents, use the Upload Document endpoint.

POST https://api.spherepay.co/v2/document

Request Example

curl --location 'https://api.spherepay.co/v2/document' \
--header 'Authorization: Bearer <your_api_key>' \
--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"'

Response Example

{
  "target": "business_representative",
  "targetId": "associatedPerson_4914a2f6226e42cc8d207ead9573b29f",
  "documentType": "id_card",
  "fileName": "document.jpg",
  "fileSize": 2048576,
  "mimeType": "image/jpeg",
  "createdAt": "2025-05-23T11:45:00Z"
}

5. UBO Liveness Verification

Each UBO requires liveness verification. Check the UBO's required array using the Get Business Representative endpoint to determine which path applies, then perform only one of the following.

Do exactly one of the following

Check the required array in the UBO's verification profile and follow only the matching path. Do not perform both.

6. Poll for Verification Result

Once all required steps are complete for both the business and its UBOs, SpherePay automatically processes the verification — no submit call is needed. Poll the Get Customer endpoint until status in verificationProfiles reaches approved.

GET https://api.spherepay.co/v2/customer/{id}

Approved Response Example

{
  "id": "customer_2f283221a9d44ada800ac7f11f640402",
  "email": "contact@acmecorp.example.com",
  "phone": "+14155551234",
  "businessLegalName": "Acme Corporation Inc.",
  "businessTradeName": "Acme Corp",
  "verificationProfiles": [
    {
      "name": "kyb_profile_a",
      "status": "approved",
      "criteria": {
        "complete": [
          "email_address",
          "phone_number",
          "operating_address",
          "registered_address",
          "legal_name",
          "trade_name",
          "entity_type",
          "description",
          "naics_code",
          "website",
          "incorporated_on",
          "identification_number",
          "estimated_annual_revenue",
          "expected_monthly_payments",
          "account_purpose",
          "source_of_funds",
          "source_of_funds_description",
          "is_dao",
          "regulated_activities",
          "participates_in_regulated_financial_activity",
          "operates_in_prohibited_countries",
          "business_representatives",
          "incorporation_cert_document",
          "shareholder_registry_document",
          "proof_of_address_document"
        ],
        "pending": [],
        "required": [],
        "errors": []
      }
    }
  ],
  "meta": {},
  "createdAt": "2026-03-09T21:26:43.756Z",
  "updatedAt": "2026-03-09T21:26:43.756Z",
  "type": "business"
}

When required is empty and status is approved, the business customer is fully onboarded and ready to transfer.

Additional Steps

The following steps are only required for some integrations. Check the required array in the customer's verification profile using the Get Customer endpoint — only perform a step if its corresponding item appears there. See the Verification Profile reference for details on each field.

What's Next

With the business customer onboarded, register their payment methods before initiating a transfer.

Register Payment Methods

Bank Accounts

Register a bank account so the customer can send or receive funds via bank rail.

Wallets

Register a crypto wallet address to enable on-ramp and off-ramp transfers.

Create a Transfer

Transfers API

Create and manage transfers once the customer has registered their payment methods.

Make Routine Transfers Easier with Onramper Accounts & Offloader Wallets

Onramper Accounts

Register a bank account so the customer can send or receive funds via bank rail.

Offloader Wallets

Register a crypto wallet address to enable on-ramp and off-ramp transfers.

Last updated on

On this page

Introduction
KYB via API Flow
Core Steps
1. Create a Customer
Request Example
Business Identification Fields
2. Upload Business Documents
Request Example
Response Example
3. Register Business Representative (UBO)
Request Example
Personal Information Fields
4. Upload Identification Documents for Business Representative (UBO)
Request Example
Response Example
5. UBO Liveness Verification
Response Example
6. Poll for Verification Result
Approved Response Example
Additional Steps
What's Next
Register Payment Methods
Create a Transfer
Make Routine Transfers Easier with Onramper Accounts & Offloader Wallets