Create a Customer

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
Business

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": "[email protected]"
  }'

Response

{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "type": "INDIVIDUAL",
  "name": "William Default",
  "taxId": "123.456.789-00",
  "birthDate": "1990-01-01",
  "country": "BRA",
  "email": "[email protected]",
  "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

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": "[email protected]"
  }'

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": "[email protected]",
  "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

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.

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.

Guides

​Prerequisites

​Create a customer

​Required fields

​Required fields

​Understanding the response

​Related resources

Customers

Identity Verification

Transaction Limits

​What’s next

Individual Verification (KYC)

Business Verification (KYB)

Prerequisites

Create a customer

Required fields

Required fields

Understanding the response

Related resources

What’s next