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

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. Here’s a summary of the key fields:
FieldDescription
phonePhone number in international format
firstName, middleName, lastNameCustomer’s name split into parts
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.
2

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)
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, PASSPORT, DRIVERS_LICENSE) require the side field. Upload the front and back as separate requests.
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.
3

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

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.

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