Create a Customer

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

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": "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

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": "hello@lumx.io"
  }'

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": "hello@lumx.io",
  "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" },
    { "name": "TERMS_OF_SERVICE", "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

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` ending	Simulated status
`1`	`NOT_STARTED` — verification never starts automatically
`2`	`RFI` — requests additional documents
`3`	`FINAL_REJECTION` — permanent rejection
Any other digit	`APPROVED` (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.

Use Cases

Customer Onboarding

Conversions

Build with AI

Create a Customer

Prerequisites

Create a customer

Required fields

Required fields

Provision fiat accounts

Testing verification statuses in sandbox

Understanding the response

Customers

Identity Verification

Transaction Limits

What’s next

Individual Verification (KYC)

Business Verification (KYB)

​Prerequisites

​Create a customer

​Required fields

​Required fields

​Provision fiat accounts

​Testing verification statuses in sandbox

​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

Provision fiat accounts

Testing verification statuses in sandbox

Understanding the response

Related resources

What’s next