Skip to main content
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

​
Verification flow

1

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.
2

Send additional information

Send a PATCH request to /customers/{id}/additional-information with the customer’s personal and transactional information. This must 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:
FieldDescription
phonePhone number in international format
firstName, lastNameCustomer’s name split into parts
middleNameCustomer’s middle name (optional)
addressFull address with country, line1, city, state, postalCode
monthlyVolumeInUSDExpected monthly transaction volume in USD
transactionVolumeInUSDExpected volume per transaction in USD
jurisdictionsRegions where transactions will occur (e.g., BRA, USA, EU)
involvedActivitiesActivities involved (e.g., NONE, GAMBLING)
transactionCounterpartiesWho the customer transacts with (e.g., SELF, MERCHANTS_SUPPLIERS)
professionalSituationOne of: EMPLOYEE, SELF_EMPLOYED, UNEMPLOYED, RETIRED, OTHER
professionalOccupationFree-text description of occupation
sourceOfFundsOrigin of funds (e.g., EMPLOYMENT, SAVINGS, COMPANY)
For all accepted values, see the API Reference.
3

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.
4

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.
5

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"
}
StatusDescription
NOT_STARTEDCustomer created but verification not yet initiated
UNDER_VERIFICATIONDocuments submitted and being reviewed
APPROVEDVerification complete — customer can transact
TEMPORARY_REJECTIONAdditional documentation required
FINAL_REJECTIONCustomer 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 details.

​
Handling rejections

When a customer receives TEMPORARY_REJECTION, the verification response includes details about what needs to be corrected: 
{
  "customerId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "status": "TEMPORARY_REJECTION",
  "level": "STANDARD",
  "statusReason": {
    "rejectLabels": ["screenshot", "unsatisfactory_photos"],
    "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 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.