Skip to main content

​
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

1

Create Business Profile

Register business and beneficiary information
2

Upload Business Documents

Submit incorporation and business proof of address
3

Upload Beneficiary Documents

Submit KYC documents for each 20%+ owner
4

Start KYB Verification

Initiate the business verification process
5

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

FieldTypeDescriptionExample
typestringMust be "BUSINESS""BUSINESS"
legalNamestringCompany’s legal registered name"Acme Corporation"
taxIdstringValid business tax ID"12.345.678/0001-00" (CNPJ for Brazil)
incorporationDatestringDate of incorporation (YYYY-MM-DD)"2020-01-01"
countrystringISO 3166-1 alpha-3 country code"BRA"
emailstringBusiness contact email"[email protected]"
beneficiariesarrayList of beneficiaries with 20%+ ownershipSee beneficiary structure below

​
Beneficiary Structure

Each beneficiary must include:
FieldTypeDescriptionExample
typestringMust be "INDIVIDUAL""INDIVIDUAL"
namestringBeneficiary’s full legal name"Jane Smith"
taxIdstringBeneficiary’s personal tax ID"987.654.321-00"
birthDatestringDate of birth (YYYY-MM-DD)"1985-05-15"
countrystringISO 3166-1 alpha-3 country code"BRA"
emailstringBeneficiary’s email"[email protected]"
sharePercentagenumberOwnership 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

TypeDescription
NOT_STARTEDVerification hasn’t been initiated yet
UNDER_VERIFICATIONDocuments are being reviewed
APPROVEDCustomer is fully verified and ready to transact
TEMPORARY_REJECTIONDocuments need to be resubmitted
FINAL_REJECTIONCustomer 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.