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. It’s only returned once the customer has accepted the terms of service (step 1).

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",
    "lastName": "Default",
    "address": {
      "country": "BRA",
      "line1": "Rua das Flores, 123",
      "city": "São Paulo",
      "state": "SP",
      "postalCode": "01234-567"
    },
    "professionalSituation": "EMPLOYEE",
    "professionalOccupation": "Software Engineer",
    "monthlyIncomeInUSD": "8000",
    "monthlyVolumeInUSD": "5000",
    "transactionVolumeInUSD": "1000",
    "sourceOfFunds": "SALARY_EMPLOYMENT_INCOME",
    "transactionCounterparties": ["SELF", "FAMILY"]
  }'

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`
`professionalSituation`	Employment situation (e.g., `EMPLOYEE`, `BUSINESS_OWNER`)
`professionalOccupation`	Free-text description of occupation
`monthlyIncomeInUSD`	Monthly income in USD (e.g., `"8000"` or `"8000.50"`)
`monthlyVolumeInUSD`	Expected monthly transaction volume in USD
`transactionVolumeInUSD`	Expected volume per transaction in USD
`sourceOfFunds`	Origin of funds (e.g., `SALARY_EMPLOYMENT_INCOME`)
`transactionCounterparties`	Who the customer sends money to or receives it from (e.g., `SELF`, `FAMILY`)

monthlyIncomeInUSD takes a non-negative amount as a string, with up to 2 decimal places. professionalSituation, sourceOfFunds, and transactionCounterparties only accept the values listed in Onboarding fields. Any other value returns 400.

Customers created before October 28, 2026 keep the previous questionnaire, with jurisdictions and involvedActivities and without monthlyIncomeInUSD. Keep sending that body for them: a body that doesn’t match the customer’s questionnaire returns 400 with VALIDATION_ERROR. See Previous questionnaire and the changelog.

For the full schema, 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.verification.link is omitted from the customer until the TERMS_OF_SERVICE requirement is APPROVED. Once the customer has accepted the terms, read the customer to get it:

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 automated and typically completes in about 60 seconds. 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

Onboarding

Collect

Pay out

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