Business Verification (KYB)

After creating a business customer, you must complete identity verification (KYB) before they can transact. Business verification requires company information, documents, and details about associated parties (UBOs, shareholders, and representatives).

If you don’t want to build the verification flow via API, you can share the verification.link returned in the customer response directly with your customer. The link opens a guided flow where they can submit all required information and documents without any additional API integration.

If you start the verification process through the API, do not share the verification.link with your customer. Mixing both approaches can cause conflicts and lead to unexpected issues during the verification flow.

Prerequisites

A business customer already created (see Create a Customer)
An API key from the Dashboard
Your environment base URL (see Environments)

Verification flow

Accept terms of service

Before starting verification, the customer must accept the terms of service. Send a POST request to /customers/{id}/tos to get the acceptance URL. You can optionally include a redirectUrl to redirect the customer after they accept.

Request

curl -X POST https://api-sandbox.lumx.io/customers/{id}/tos \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "redirectUrl": "https://yourapp.com/onboarding/next-step"
  }'

Response

{
  "url": "https://dashboard.lumx.io/tos/sandbox/eyJhbGciOiJSUzI1...",
  "expiresAt": "2026-04-09T16:00:00Z"
}

Share the returned URL with your customer. The link expires after 24 hours. Generate a new one if needed. The requirements array will show TERMS_OF_SERVICE as NOT_SENT until they accept. You can check the status by reading the customer.

The request body is optional. If you don’t need to redirect the customer after acceptance, you can send the request without a body.

Send additional information

Send a PATCH request to /customers/{id}/additional-information with the company’s details and transactional information.

Request

curl -X PATCH https://api-sandbox.lumx.io/customers/{id}/additional-information \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "BUSINESS",
    "phone": "+5511999999999",
    "address": {
      "country": "BRA",
      "line1": "Av. Paulista, 1000, Sala 101",
      "city": "São Paulo",
      "state": "SP",
      "postalCode": "01310-100"
    },
    "monthlyVolumeInUSD": "50000.00",
    "transactionVolumeInUSD": "10000.00",
    "jurisdictions": ["BRA", "USA", "EU"],
    "involvedActivities": ["NONE"],
    "transactionCounterparties": ["SELF"],
    "companyType": "BLOCKCHAIN_SOFTWARE_COMPANY",
    "annualRevenue": "1000000.00",
    "monthlyTransactionVolume": "100000.00",
    "complianceAndAML": "We have a dedicated compliance team and use third-party AML screening tools.",
    "isRegulatedActivity": false,
    "regulatedActivityDetails": "",
    "website": "https://example.com",
    "sourceOfFunds": "COMPANY",
    "servicesProvided": "We provide blockchain-based payment infrastructure for B2B cross-border transactions."
  }'

All fields are required. Here’s a summary of the business-specific fields:

Field	Description
`companyType`	Type of company (e.g., `BLOCKCHAIN_SOFTWARE_COMPANY`, `PAYMENT_GATEWAY`)
`annualRevenue`	Company’s annual revenue in USD
`monthlyTransactionVolume`	Expected monthly transaction volume
`complianceAndAML`	Description of the company’s compliance and AML policies
`isRegulatedActivity`	Whether the company is involved in regulated activities
`regulatedActivityDetails`	Details if `isRegulatedActivity` is `true`
`website`	Company website URL
`sourceOfFunds`	Origin of funds (e.g., `COMPANY`, `COMPANY_CAPITAL`, `INVESTMENT`)
`servicesProvided`	Description of the services or products the company offers

For all accepted values, see the API Reference.

Upload company documents

Upload company documents using POST /customers/{id}/documents. Each document is sent as a multipart/form-data request.Required documents:

INCORPORATION_ARTICLES
SHAREHOLDER_REGISTRY
DIRECTORS_REGISTRY
PROOF_OF_ADDRESS (must be from the last 90 days)

Optional documents:

POWER_OF_ATTORNEY
REGULATED_ACTIVITY_DOCUMENT
SIGNED_BALANCE_SHEET
SIGNED_CORPORATE_STRUCTURE_CHART
SIGNED_INCOME_STATEMENT
OTHER (any additional document)

Upload incorporation articles

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

Upload shareholder registry

curl -X POST https://api-sandbox.lumx.io/customers/{id}/documents \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@/path/to/shareholder-registry.pdf" \
  -F "type=SHAREHOLDER_REGISTRY" \
  -F "country=BRA"

Upload directors registry

curl -X POST https://api-sandbox.lumx.io/customers/{id}/documents \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@/path/to/directors-registry.pdf" \
  -F "type=DIRECTORS_REGISTRY" \
  -F "country=BRA"

Files must be JPG, PNG, or PDF with a maximum size of 50MB.

Add associated parties

Add the company’s UBOs, shareholders, and representatives using POST /customers/{id}/associated-parties. Each associated party can have one or more roles.

Before starting verification, the company must have at least one associated party assigned to each required role: UBO, Shareholder, and Representative. A single individual may fulfill multiple roles, and multiple individuals may be assigned to the same role.

There are three role types:

UBO (Ultimate Beneficial Owner): always INDIVIDUAL type. Requires ownershipPercentage (25–100%).
SHAREHOLDER: can be INDIVIDUAL or BUSINESS type. Requires ownershipPercentage (25–100%).
REPRESENTATIVE: always INDIVIDUAL type. No ownershipPercentage needed.

UBO (Individual)
Shareholder (Individual)
Shareholder (Business)
Representative
Multiple roles

Request

curl -X POST https://api-sandbox.lumx.io/customers/{id}/associated-parties \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "INDIVIDUAL",
    "roles": ["UBO"],
    "name": "Maria Santos",
    "birthDate": "1985-07-10",
    "email": "maria.santos@example.com",
    "taxId": "987.654.321-00",
    "address": {
      "country": "BRA",
      "line1": "Rua das Acácias, 456",
      "city": "Rio de Janeiro",
      "state": "RJ",
      "postalCode": "20000-000"
    },
    "ownershipPercentage": 40
  }'

Response

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "type": "INDIVIDUAL",
  "roles": ["UBO"],
  "name": "Maria Santos",
  "taxId": "987.654.321-00",
  "birthDate": "1985-07-10",
  "email": "maria.santos@example.com",
  "address": {
    "country": "BRA",
    "line1": "Rua das Acácias, 456",
    "city": "Rio de Janeiro",
    "state": "RJ",
    "postalCode": "20000-000"
  },
  "ownershipPercentage": 40,
  "verification": {
    "status": "NOT_STARTED",
    "level": "STANDARD",
    "link": "https://in.sumsub.com/websdk/p/sbx_aA00bB11cC33dD44"
  },
  "createdAt": "2024-01-15T11:00:00Z",
  "updatedAt": "2024-01-15T11:00:00Z"
}

Request

curl -X POST https://api-sandbox.lumx.io/customers/{id}/associated-parties \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "INDIVIDUAL",
    "roles": ["SHAREHOLDER"],
    "name": "Pedro Oliveira",
    "birthDate": "1978-12-05",
    "email": "pedro.oliveira@example.com",
    "taxId": "111.222.333-44",
    "address": {
      "country": "BRA",
      "line1": "Av. Brasil, 789",
      "city": "São Paulo",
      "state": "SP",
      "postalCode": "01000-000"
    },
    "ownershipPercentage": 35
  }'

Request

curl -X POST https://api-sandbox.lumx.io/customers/{id}/associated-parties \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "BUSINESS",
    "roles": ["SHAREHOLDER"],
    "legalName": "Investment Fund ABC",
    "incorporationDate": "2010-05-20",
    "email": "contact@fundabc.com",
    "taxId": "99.988.877/0001-66",
    "address": {
      "country": "USA",
      "line1": "123 Wall Street",
      "city": "New York",
      "state": "NY",
      "postalCode": "10005"
    },
    "ownershipPercentage": 25
  }'

Request

curl -X POST https://api-sandbox.lumx.io/customers/{id}/associated-parties \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "INDIVIDUAL",
    "roles": ["REPRESENTATIVE"],
    "name": "Carlos Mendes",
    "birthDate": "1990-03-15",
    "email": "carlos.mendes@example.com",
    "taxId": "555.666.777-88",
    "address": {
      "country": "BRA",
      "line1": "Rua Principal, 100",
      "city": "Belo Horizonte",
      "state": "MG",
      "postalCode": "30000-000"
    }
  }'

Representatives do not require ownershipPercentage.

Request

curl -X POST https://api-sandbox.lumx.io/customers/{id}/associated-parties \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "INDIVIDUAL",
    "roles": ["UBO", "REPRESENTATIVE"],
    "name": "Ana Silva",
    "birthDate": "1982-09-25",
    "email": "ana.silva@example.com",
    "taxId": "444.555.666-77",
    "address": {
      "country": "BRA",
      "line1": "Av. das Nações, 200",
      "city": "Brasília",
      "state": "DF",
      "postalCode": "70000-000"
    },
    "ownershipPercentage": 30
  }'

When an associated party has multiple roles, include all applicable roles in the roles array. If UBO or SHAREHOLDER is included, ownershipPercentage is required.

Upload associated party documents

Upload documents for each associated party using the same POST /customers/{id}/documents endpoint, but include the associatedPartyId field.Individual associated parties (UBOs, shareholders, and representatives) need an identity document (ID_CARD, PASSPORT, or DRIVERS_LICENSE) and a PROOF_OF_ADDRESS from the last 90 days:

Identity documents (ID_CARD and DRIVERS_LICENSE) require the side field. Upload the front and back as separate requests. For the digital Brazilian driver’s license (CNH digital), the side field is not needed.

Upload identity document for associated party (front)

curl -X POST https://api-sandbox.lumx.io/customers/{id}/documents \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@/path/to/document-front.jpg" \
  -F "type=ID_CARD" \
  -F "side=FRONT_SIDE" \
  -F "country=BRA" \
  -F "associatedPartyId=a1b2c3d4-e5f6-7890-abcd-ef1234567890"

Upload identity document for associated party (back)

curl -X POST https://api-sandbox.lumx.io/customers/{id}/documents \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@/path/to/document-back.jpg" \
  -F "type=ID_CARD" \
  -F "side=BACK_SIDE" \
  -F "country=BRA" \
  -F "associatedPartyId=a1b2c3d4-e5f6-7890-abcd-ef1234567890"

Upload proof of address for associated party

curl -X POST https://api-sandbox.lumx.io/customers/{id}/documents \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@/path/to/proof-of-address.pdf" \
  -F "type=PROOF_OF_ADDRESS" \
  -F "country=BRA" \
  -F "associatedPartyId=a1b2c3d4-e5f6-7890-abcd-ef1234567890"

Business associated parties need company formation documents:

Upload incorporation articles for business shareholder

curl -X POST https://api-sandbox.lumx.io/customers/{id}/documents \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@/path/to/incorporation-articles.pdf" \
  -F "type=INCORPORATION_ARTICLES" \
  -F "country=USA" \
  -F "associatedPartyId=b2c3d4e5-f6a7-8901-bcde-f12345678901"

Upload directors registry for business shareholder

curl -X POST https://api-sandbox.lumx.io/customers/{id}/documents \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@/path/to/directors-registry.pdf" \
  -F "type=DIRECTORS_REGISTRY" \
  -F "country=USA" \
  -F "associatedPartyId=b2c3d4e5-f6a7-8901-bcde-f12345678901"

Start verification

Unlike individual customers, business verification must be started explicitly. Ensure all documents and associated parties are uploaded before calling this endpoint.

Request

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

Response

{
  "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479"
}

Before starting verification, ensure you have:

At least one associated party with each role type: UBO, SHAREHOLDER, and REPRESENTATIVE
All required company documents uploaded
All associated party documents uploaded

Missing documents or role types will delay or prevent the verification review.

Monitor verification status

Check the verification status using the verification ID returned in the previous step:

Request

curl https://api-sandbox.lumx.io/customers/{id}/verifications/{verificationId} \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "customerId": "c85cb5ef-0574-4450-806d-195944f1e309",
  "status": "UNDER_VERIFICATION",
  "level": "STANDARD"
}

Status	Description
`NOT_STARTED`	Verification created but review not yet started
`UNDER_VERIFICATION`	Documents submitted and being reviewed
`APPROVED`	Verification complete. Customer can transact
`RFI`	Additional documentation required
`FINAL_REJECTION`	Customer permanently rejected

You can also receive status updates via webhooks instead of polling.

In sandbox, you can simulate different verification statuses using magic numbers in the customer’s taxId. See Sandbox magic numbers for the full list.

Multi-level corporate structures

If your customer has a multi-level ownership structure (e.g., a holding company that owns another company that owns the customer), you can use the parentId field to nest shareholders across multiple levels. For example, if “Investment Fund ABC” (a business shareholder) has its own individual shareholders, you can link them by passing the fund’s associated party ID as parentId:

Request

curl -X POST https://api-sandbox.lumx.io/customers/{id}/associated-parties \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "INDIVIDUAL",
    "roles": ["SHAREHOLDER"],
    "parentId": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
    "name": "John Smith",
    "birthDate": "1975-04-20",
    "email": "john.smith@fundabc.com",
    "taxId": "123-45-6789",
    "address": {
      "country": "USA",
      "line1": "456 Broadway",
      "city": "New York",
      "state": "NY",
      "postalCode": "10013"
    },
    "ownershipPercentage": 50
  }'

This creates the following structure:

Your Customer (Business)
└── Investment Fund ABC (Business Shareholder): 25%
    └── John Smith (Individual Shareholder): 50%

Associated parties nested under a shareholder (via parentId) can only have the SHAREHOLDER role. Other roles such as UBO and REPRESENTATIVE are only valid for top-level associated parties.

You can repeat this pattern for as many levels as needed. Each associated party at every level requires its own documents and verification.

Handling rejections

When a business receives RFI, the verification response includes details about what needs to be corrected:

{
  "customerId": "c85cb5ef-0574-4450-806d-195944f1e309",
  "status": "RFI",
  "level": "STANDARD",
  "statusReason": {
    "rejectLabels": ["screenshot", "unsatisfactory_photos"],
    "rejectSubLabels": ["proofOfAddress_listOfDocs", "badPhoto"],
    "documents": [
      {
        "type": "PASSPORT",
        "status": "RFI",
        "comment": "Screenshots aren't accepted. Please upload a live photo of the document.",
        "rejectLabels": ["screenshot", "unsatisfactory_photos"]
      }
    ]
  }
}

Re-upload the corrected documents and start a new verification.

A FINAL_REJECTION is permanent. The customer cannot resubmit documents or be re-verified.

Review timeline

Standard KYB verification is typically reviewed within 2 business days. See Identity Verification for full details.

Retrying verification for specific associated parties

When only some associated parties are rejected, you can retry verification for those parties in isolation. Pass associatedPartyIds in the request body when starting a verification:

Request

curl -X POST https://api-sandbox.lumx.io/customers/{id}/verifications \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "associatedPartyIds": [
      "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "b2c3d4e5-f6a7-8901-bcde-f12345678901"
    ]
  }'

Only the listed associated parties are sent for verification again. The customer-level verification is not restarted, and any associated party not included in the list keeps its current verification status.

Resubmit any corrected documents/information for the affected associated parties before starting the retry. This option applies only to BUSINESS customers.

Webhooks

Receive real-time status updates.

Transaction Limits

Understand post-verification limits.

Identity Verification

Full compliance requirements.

Use Cases

Customer Onboarding

Conversions

Build with AI

Business Verification (KYB)

Prerequisites

Verification flow

Multi-level corporate structures

Handling rejections

Review timeline

Retrying verification for specific associated parties

Webhooks

Transaction Limits

Identity Verification

​Prerequisites

​Verification flow

​Multi-level corporate structures

​Handling rejections

​Review timeline

​Retrying verification for specific associated parties

​Related resources

Webhooks

Transaction Limits

Identity Verification

Prerequisites

Verification flow

Multi-level corporate structures

Handling rejections

Review timeline

Retrying verification for specific associated parties

Related resources