Onboarding a business customer

Prerequisites

Before starting the onboarding process, ensure you have:

API credentials (Get your API key)
Business legal information and documentation
Beneficiary information (for owners with 20%+ shares)
Required documents in digital format (PDF, PNG, or JPEG)

Process overview

Create Business Profile

Upload Business Documents

Submit incorporation and business proof of address

Upload Beneficiary Documents

Submit KYC documents for each 20%+ owner

Start KYB Verification

Initiate the business verification process

Monitor Status

Track verification for business and all beneficiaries

Step 1: Create a Business Customer

Create a business customer profile with company and beneficiary information.

Request

curl -X POST https://api.lumx.io/customers \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "BUSINESS",
    "legalName": "Acme Corporation",
    "taxId": "12.345.678/0001-00",
    "incorporationDate": "2020-01-01",
    "country": "BRA",
    "email": "[email protected]",
    "beneficiaries": [
      {
        "type": "INDIVIDUAL",
        "name": "Jane Smith",
        "taxId": "987.654.321-00",
        "birthDate": "1985-05-15",
        "country": "BRA",
        "email": "[email protected]",
        "sharePercentage": 30
      },
      {
        "type": "INDIVIDUAL",
        "name": "John Doe",
        "taxId": "123.456.789-00",
        "birthDate": "1990-01-01",
        "country": "BRA",
        "email": "[email protected]",
        "sharePercentage": 25
      }
    ]
  }'

Required Fields

Field	Type	Description	Example
`type`	string	Must be `"BUSINESS"`	`"BUSINESS"`
`legalName`	string	Company’s legal registered name	`"Acme Corporation"`
`taxId`	string	Valid business tax ID	`"12.345.678/0001-00"` (CNPJ for Brazil)
`incorporationDate`	string	Date of incorporation (YYYY-MM-DD)	`"2020-01-01"`
`country`	string	ISO 3166-1 alpha-3 country code	`"BRA"`
`email`	string	Business contact email	`"[email protected]"`
`beneficiaries`	array	List of beneficiaries with 20%+ ownership	See beneficiary structure below

Beneficiary Structure

Each beneficiary must include:

Field	Type	Description	Example
`type`	string	Must be `"INDIVIDUAL"`	`"INDIVIDUAL"`
`name`	string	Beneficiary’s full legal name	`"Jane Smith"`
`taxId`	string	Beneficiary’s personal tax ID	`"987.654.321-00"`
`birthDate`	string	Date of birth (YYYY-MM-DD)	`"1985-05-15"`
`country`	string	ISO 3166-1 alpha-3 country code	`"BRA"`
`email`	string	Beneficiary’s email	`"[email protected]"`
`sharePercentage`	number	Ownership percentage (must be ≥20)	`30`

Include all beneficiaries with 20%+ ownership. Each requires KYC documents.

The response includes the business customerId, beneficiary IDs, and a KYB link:

Response

{
	"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
	"type": "BUSINESS",
	"legalName": "Acme Corporation",
	"taxId": "42.887.120/0001-00",
	"link": "https://in.sumsub.com/websdk/p/sbx_aA00bB11cC33dD44",
	"incorporationDate": "2020-01-01",
	"country": "BRA",
	"email": "[email protected]",
	"beneficiaries": [
		{
			"id": "123e4567-e89b-12d3-a456-426614174001",
			"type": "INDIVIDUAL",
			"name": "Jane Smith",
			"taxId": "987.654.321-00",
			"birthDate": "1985-05-15",
			"country": "BRA",
			"email": "[email protected]",
			"sharePercentage": 30,
			"verification": {
				"link": "https://in.sumsub.com/websdk/p/sbx_aA00bB11cC33dD44",
				"status": "NOT_STARTED",
				"level": "STANDARD"
			}
		},
		{
			"id": "123e4567-e89b-12d3-a456-426614174001",
			"type": "INDIVIDUAL",
			"name": "John Doe",
			"taxId": "987.654.321-00",
			"birthDate": "1985-05-15",
			"country": "BRA",
			"email": "[email protected]",
			"sharePercentage": 30,
			"verification": {
				"link": "https://in.sumsub.com/websdk/p/sbx_aA00bB11cC33dD44",
				"status": "NOT_STARTED",
				"level": "STANDARD"
			}
		}
	],
	"walletAddress": "0x1234567890123456789012345678901234567890",
	"blockExplorerUrl": "https://amoy.polygonscan.com/address/0x1234567890123456789012345678901234567890",
	"verification": {
		"status": "NOT_STARTED",
		"level": "STANDARD"
	},
	"transactionLimits": {
		"single": "1000.00",
		"daily": "10000.00",
		"monthly": "100000.00"
	},
	"createdAt": "2021-01-01T00:00:00Z",
	"updatedAt": "2021-01-01T00:00:00Z"
}

You can either use the API endpoints or the links provided in the response above to proceed with the next steps. For businesses with other businesses as beneficiaries, only link is supported.

Step 2: Upload Required Documents

Business customers require corporate documents and KYC documents for each beneficiary.

Business Documents Required

1. Legal Incorporation Documents

Articles of Incorporation (INCORPORATION_ARTICLES)
Certificate of Formation
State Business Registration Extract
Incumbency Certificate (INCUMBENCY_CERT)
Shareholder Registry (SHAREHOLDER_REGISTRY)

2. Business Proof of Address

Must be dated within last 3 months

Beneficiary Documents Required

For each beneficiary with 20%+ ownership: 1. Identity Document (Choose One)

National ID Card (front and back)
Driver’s License (front and back)
Passport

2. Proof of Address

Must be dated within the last 3 months

Upload Examples

curl -X POST https://api.lumx.io/customers/{customerId}/documents \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@/path/to/INCORPORATION_ARTICLES.pdf" \
  -F 'metadata={
    "type": "INCORPORATION_ARTICLES",
    "country": "BRA"
  }'

Upload documents for ALL beneficiaries with 20%+ ownership.

File Requirements:

Formats: PDF, PNG, or JPEG
Maximum size: 50MB per document
Documents must be clearly legible and fully visible
Official documents must be properly certified if required

Step 3: Start KYB Verification

Once all business and beneficiary documents are uploaded, initiate the KYB verification:

Request

curl -X POST https://api.lumx.io/customers/{customerId}/verifications \
  -H "Authorization: Bearer YOUR_API_KEY"

Processing Time: Business KYB verification typically takes up to 24 hours, though it may take longer during peak times.

Step 4: Monitor Verification Status

Check the verification progress for both the business and its beneficiaries:

Request

curl -X GET https://api.lumx.io/customers/{customerId}/verifications \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
	"customerId": "c85cb5ef-0574-4450-806d-195944f1e309",
	"status": "UNDER_VERIFICATION",
	"level": "STANDARD",
	"beneficiaries": [
		{
			"id": "6737ca44-0fc7-4523-a1db-de014a865302",
			"status": "APPROVED",
			"level": "STANDARD"
		},
		{
			"id": "123e4567-e89b-12d3-a456-426614174002",
			"status": "UNDER_VERIFICATION",
			"level": "STANDARD"
		}
	]
}

Verification Statuses

Type	Description
`NOT_STARTED`	Verification hasn’t been initiated yet
`UNDER_VERIFICATION`	Documents are being reviewed
`APPROVED`	Customer is fully verified and ready to transact
`TEMPORARY_REJECTION`	Documents need to be resubmitted
`FINAL_REJECTION`	Customer was not approved

Businesses must be approved along with ALL beneficiaries for full verification.

Next Steps

Learn how to onboard individual customers or move to exchange rates.

Get Started

Core Concepts

Compliance

Additional Information

Onboarding a business customer

Prerequisites

Process overview

Step 1: Create a Business Customer

Required Fields

Beneficiary Structure

Step 2: Upload Required Documents

Business Documents Required

Beneficiary Documents Required

Upload Examples

Step 3: Start KYB Verification

Step 4: Monitor Verification Status

Verification Statuses

Next Steps

Get Started

Core Concepts

Compliance

Additional Information

​Prerequisites

​Process overview

​Step 1: Create a Business Customer

​Required Fields

​Beneficiary Structure

​Step 2: Upload Required Documents

​Business Documents Required

​Beneficiary Documents Required

​Upload Examples

​Step 3: Start KYB Verification

​Step 4: Monitor Verification Status

​Verification Statuses

​Next Steps

Prerequisites

Process overview

Step 1: Create a Business Customer

Required Fields

Beneficiary Structure

Step 2: Upload Required Documents

Business Documents Required

Beneficiary Documents Required

Upload Examples

Step 3: Start KYB Verification

Step 4: Monitor Verification Status

Verification Statuses

Next Steps