Individual Verification (KYC)

After creating an individual customer, you must complete identity verification (KYC) before they can transact. This guide walks through each step of the process.

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

An individual 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 customer’s personal and transactional information. This has to be done before uploading documents.

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": "INDIVIDUAL",
    "phone": "+5511999999999",
    "firstName": "William",
    "middleName": "",
    "lastName": "Default",
    "address": {
      "country": "BRA",
      "line1": "Rua das Flores, 123",
      "city": "São Paulo",
      "state": "SP",
      "postalCode": "01234-567"
    },
    "monthlyVolumeInUSD": "5000",
    "transactionVolumeInUSD": "1000",
    "jurisdictions": ["BRA", "USA", "OTHERS"],
    "involvedActivities": ["NONE"],
    "transactionCounterparties": ["SELF", "MERCHANTS_SUPPLIERS"],
    "professionalSituation": "EMPLOYEE",
    "professionalOccupation": "Software Engineer",
    "sourceOfFunds": "EMPLOYMENT"
  }'

All fields are required unless noted otherwise. Here’s a summary of the key fields:

Field	Description
`phone`	Phone number in international format
`firstName`, `lastName`	Customer’s name split into parts
`middleName`	Customer’s middle name (optional)
`address`	Full address with `country`, `line1`, `city`, `state`, `postalCode`
`monthlyVolumeInUSD`	Expected monthly transaction volume in USD
`transactionVolumeInUSD`	Expected volume per transaction in USD
`jurisdictions`	Regions where transactions will occur (e.g., `BRA`, `USA`, `EU`)
`involvedActivities`	Activities involved (e.g., `NONE`, `GAMBLING`)
`transactionCounterparties`	Who the customer transacts with (e.g., `SELF`, `MERCHANTS_SUPPLIERS`)
`professionalSituation`	One of: `EMPLOYEE`, `SELF_EMPLOYED`, `UNEMPLOYED`, `RETIRED`, `OTHER`
`professionalOccupation`	Free-text description of occupation
`sourceOfFunds`	Origin of funds (e.g., `EMPLOYMENT`, `SAVINGS`, `COMPANY`)

For all accepted values, see the API Reference.

Upload documents

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

One identity document: ID_CARD, PASSPORT, or DRIVERS_LICENSE
BANK_STATEMENT (must be from the last 6 months)
PROOF_OF_ADDRESS (must be from the last 90 days)

Optional documents:

INCOME_TAX_RETURN (must be from the last calendar year)
DELIVERY_RECEIPT (must be from the last calendar year)
OTHER (any additional document)

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

Upload identity document (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"

Upload bank statement

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

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

Complete liveness check

The customer must complete a liveness check by accessing the verification.link returned in the customer response. This link opens a guided selfie flow.You can retrieve the link at any time by reading the customer:

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

For individual customers, verification starts automatically after the liveness check is completed. You do not need to call a separate endpoint to start verification.

Monitor verification status

Check the verification status by reading the customer’s verification:

Request

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

Response

{
  "customerId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "status": "UNDER_VERIFICATION",
  "level": "STANDARD"
}

Status	Description
`NOT_STARTED`	Customer created but verification not yet initiated
`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.

Handling rejections

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

{
  "customerId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "status": "RFI",
  "level": "STANDARD",
  "statusReason": {
    "rejectLabels": ["screenshot", "unsatisfactory_photos"],
    "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 the verification will automatically resume.

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

Review timeline

Standard KYC verification is typically reviewed within 1 business day. See Identity Verification for full details.

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

Individual Verification (KYC)

Prerequisites

Verification flow

Handling rejections

Review timeline

Webhooks

Transaction Limits

Identity Verification

​Prerequisites

​Verification flow

​Handling rejections

​Review timeline

​Related resources

Webhooks

Transaction Limits

Identity Verification

Prerequisites

Verification flow

Handling rejections

Review timeline

Related resources