Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.lumx.io/llms.txt

Use this file to discover all available pages before exploring further.

A customer is the legal entity behind every transaction. Each one gets a dedicated wallet and has to complete identity verification before it can move money.

​
Prerequisites

​
Create a customer

Send a POST request to /customers. The required fields depend on the customer type.
Request
curl -X POST https://api-sandbox.lumx.io/customers \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "INDIVIDUAL",
    "name": "William Default",
    "taxId": "123.456.789-00",
    "birthDate": "1990-01-01",
    "country": "BRA",
    "email": "william.default@example.com"
  }'
Response
{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "type": "INDIVIDUAL",
  "name": "William Default",
  "taxId": "123.456.789-00",
  "birthDate": "1990-01-01",
  "country": "BRA",
  "email": "william.default@example.com",
  "verification": {
    "status": "NOT_STARTED",
    "level": "STANDARD",
    "link": "https://in.sumsub.com/websdk/p/sbx_aA00bB11cC33dD44"
  },
  "requirements": [
    { "name": "ID_CARD", "status": "NOT_SENT" },
    { "name": "PASSPORT", "status": "NOT_SENT" },
    { "name": "DRIVERS_LICENSE", "status": "NOT_SENT" },
    { "name": "BANK_STATEMENT", "status": "NOT_SENT" },
    { "name": "INCOME_TAX_RETURN", "status": "NOT_SENT" },
    { "name": "DELIVERY_RECEIPT", "status": "NOT_SENT" },
    { "name": "SELFIE", "status": "NOT_SENT" },
    { "name": "ADDITIONAL_INFORMATION", "status": "NOT_SENT" },
    { "name": "TERMS_OF_SERVICE", "status": "NOT_SENT" }
  ],
  "createdAt": "2021-01-01T00:00:00Z",
  "updatedAt": "2021-01-01T00:00:00Z"
}

​
Required fields

FieldDescription
typeMust be INDIVIDUAL
nameCustomer’s full name
taxIdValid tax ID for the customer’s country (e.g., CPF for Brazil)
birthDateDate of birth in YYYY-MM-DD format
countryCountry code in ISO 3166-1 alpha-3 format (e.g., BRA)
emailCustomer’s email address

​
Provision fiat accounts

To let the customer receive payments on local rails (PIX, SPEI, ACH, SEPA, etc.), include an accounts array on creation with the currencies you want to provision. Each currency triggers a virtual account that enters verification alongside the customer.
Request
curl -X POST https://api-sandbox.lumx.io/customers \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "INDIVIDUAL",
    "name": "William Default",
    "taxId": "123.456.789-00",
    "birthDate": "1990-01-01",
    "country": "BRA",
    "email": "william.default@example.com",
    "accounts": ["BRL", "USD", "EUR", "MXN"]
  }'
The accounts array is optional. If you omit it, the customer is provisioned with a BRL account by default and can still send and receive stablecoin on-chain through their wallet. For the full list of supported currencies and rails, see Coverage.

​
Testing verification statuses in sandbox

In sandbox, the last digit of taxId is a sentinel that drives the simulated verification outcome. Webhooks fire almost instantly with the matching status, so you can exercise your full flow end-to-end.
taxId endingSimulated status
1NOT_STARTED — verification never starts automatically
2RFI — requests additional documents
3FINAL_REJECTION — permanent rejection
Any other digitAPPROVED (default)

​
Understanding the response

The creation response includes fields you’ll use throughout the verification flow:
  • verification carries the current status (NOT_STARTED after creation), the verification level (STANDARD), and a link for the verification flow.
  • requirements lists the documents and information needed for verification, each with a status indicating whether it has been submitted.
  • transactionLimits isn’t returned by default. Call GET /customers/{id}?includeTransactionLimits=true to retrieve single, daily, and monthly limits.
The wallets array is only returned once verification reaches APPROVED. Subscribe to the customer.approved webhook or call Read a customer to retrieve wallets after approval.

Customers

Understand customer entities and verification workflows.

Identity Verification

Required data for KYC/KYB verification processes.

Transaction Limits

Understand post-verification transaction limits.

​
What’s next

After creating a customer, complete the verification process:

Individual Verification (KYC)

Complete identity verification for individual customers.

Business Verification (KYB)

Complete identity verification for business customers.