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.

Prerequisites

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

Verification flow

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

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.There are three roles:

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

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",
    "role": "UBO",
    "name": "Maria Santos",
    "birthDate": "1985-07-10",
    "email": "[email protected]",
    "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",
  "role": "UBO",
  "name": "Maria Santos",
  "taxId": "987.654.321-00",
  "birthDate": "1985-07-10",
  "email": "[email protected]",
  "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",
    "role": "SHAREHOLDER",
    "name": "Pedro Oliveira",
    "birthDate": "1978-12-05",
    "email": "[email protected]",
    "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",
    "role": "SHAREHOLDER",
    "legalName": "Investment Fund ABC",
    "incorporationDate": "2010-05-20",
    "email": "[email protected]",
    "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",
    "role": "REPRESENTATIVE",
    "name": "Carlos Mendes",
    "birthDate": "1990-03-15",
    "email": "[email protected]",
    "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.

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 need an identity document (ID_CARD, PASSPORT, or DRIVERS_LICENSE):

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"

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

Make sure all required documents and associated party documents are uploaded before starting verification. Missing documents will delay the 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
`TEMPORARY_REJECTION`	Additional documentation required
`FINAL_REJECTION`	Customer permanently rejected

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

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",
    "role": "SHAREHOLDER",
    "parentId": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
    "name": "John Smith",
    "birthDate": "1975-04-20",
    "email": "[email protected]",
    "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%

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 TEMPORARY_REJECTION, the verification response includes details about what needs to be corrected:

{
  "customerId": "c85cb5ef-0574-4450-806d-195944f1e309",
  "status": "TEMPORARY_REJECTION",
  "level": "STANDARD",
  "statusReason": {
    "rejectLabels": ["screenshot", "unsatisfactory_photos"],
    "rejectSubLabels": ["proofOfAddress_listOfDocs", "badPhoto"],
    "documents": [
      {
        "type": "PASSPORT",
        "status": "TEMPORARY_REJECTION",
        "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.

Webhooks

Receive real-time status updates.

Transaction Limits

Understand post-verification limits.

Identity Verification

Full compliance requirements.

Guides

​Prerequisites

​Verification flow

​Multi-level corporate structures

​Handling rejections

​Review timeline

​Related resources

Webhooks

Transaction Limits

Identity Verification

Prerequisites

Verification flow

Multi-level corporate structures

Handling rejections

Review timeline

Related resources