Create a Customer

Register individual and business customers on the Lumx platform

Customers are the entities on whose behalf transactions are executed. Each customer gets a dedicated wallet and must complete identity verification before transacting.

Prerequisites

• An API key from the Dashboard
• Your environment base URL (see Environments)

Create a customer

Send a POST request to /customers. The required fields depend on the customer type.

Individual

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": "[e-mail]"
  }'

Response

{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "type": "INDIVIDUAL",
  "name": "William Default",
  "taxId": "123.456.789-00",
  "birthDate": "1990-01-01",
  "country": "BRA",
  "email": "[e-mail]",
  "wallets": [
    {
      "blockchain": "POLYGON",
      "address": "0x1234567890123456789012345678901234567890",
      "blockExplorerUrl": "https://polygonscan.com/address/0x1234567890123456789012345678901234567890",
      "isDefault": true
    }
  ],
  "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" }
  ],
  "createdAt": "2021-01-01T00:00:00Z",
  "updatedAt": "2021-01-01T00:00:00Z"
}

Required fields

Field	Description
type	Must be INDIVIDUAL
name	Customer’s full name
taxId	Valid tax ID for the customer’s country (e.g., CPF for Brazil)
birthDate	Date of birth in YYYY-MM-DD format
country	Country code in ISO 3166-1 alpha-3 format (e.g., BRA)
email	Customer’s email address

Business

Request

curl -X POST https://api-sandbox.lumx.io/customers \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "BUSINESS",
    "legalName": "Lumx S.A",
    "taxId": "42.887.120/0001-00",
    "incorporationDate": "2020-01-01",
    "country": "BRA",
    "email": "[e-mail]"
  }'

Response

{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "type": "BUSINESS",
  "legalName": "Lumx S.A",
  "taxId": "42.887.120/0001-00",
  "incorporationDate": "2020-01-01",
  "country": "BRA",
  "email": "[e-mail]",
  "wallets": [
    {
      "blockchain": "POLYGON",
      "address": "0x1234567890123456789012345678901234567890",
      "blockExplorerUrl": "https://polygonscan.com/address/0x1234567890123456789012345678901234567890",
      "isDefault": true
    }
  ],
  "verification": {
    "status": "NOT_STARTED",
    "level": "STANDARD",
    "link": "https://in.sumsub.com/websdk/p/sbx_aA00bB11cC33dD44"
  },
  "requirements": [
    { "name": "INCORPORATION_ARTICLES", "status": "NOT_SENT" },
    { "name": "POWER_OF_ATTORNEY", "status": "NOT_SENT" },
    { "name": "DIRECTORS_REGISTRY", "status": "NOT_SENT" },
    { "name": "SHAREHOLDER_REGISTRY", "status": "NOT_SENT" },
    { "name": "REGULATED_ACTIVITY_DOCUMENT", "status": "NOT_SENT" },
    { "name": "SIGNED_BALANCE_SHEET", "status": "NOT_SENT" },
    { "name": "SIGNED_CORPORATE_STRUCTURE_CHART", "status": "NOT_SENT" },
    { "name": "SIGNED_INCOME_STATEMENT", "status": "NOT_SENT" },
    { "name": "ADDITIONAL_INFORMATION", "status": "NOT_SENT" }
  ],
  "createdAt": "2021-01-01T00:00:00Z",
  "updatedAt": "2021-01-01T00:00:00Z"
}

Required fields

Field	Description
type	Must be BUSINESS
legalName	Company’s registered legal name
taxId	Valid tax ID for the company’s country (e.g., CNPJ for Brazil)
incorporationDate	Incorporation date in YYYY-MM-DD format
country	Country code in ISO 3166-1 alpha-3 format (e.g., BRA)
email	Company’s email address

Testing verification statuses in sandbox

In sandbox, you can use magic numbers in the taxId field to simulate different verification outcomes. See Sandbox magic numbers for details.

Understanding the response

The creation response includes fields you’ll use throughout the verification flow:

• wallets — The customer’s provisioned wallets by blockchain, each with an address, block explorer URL, and default flag.
• verification — Contains the current status (NOT_STARTED after creation), the verification level (STANDARD), and a link for the verification flow.
• requirements — A list of documents and information needed for verification, each with a status indicating whether it has been submitted.
• transactionLimits — Not returned by default. Use GET /customers/{id}?includeTransactionLimits=true to retrieve single, daily, and monthly limits.

Related resources

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.