> ## 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.
# Create a Customer
> Register individual and business customers on the Lumx platform
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](https://dashboard.lumx.io)
* Your environment base URL (see [Environments](/get-started/environments))
## Create a customer
Send a `POST` request to `/customers`. The required fields depend on the customer type.
```bash Request theme={null}
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"
}'
```
```json Response theme={null}
{
"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 |
```bash Request theme={null}
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"
}'
```
```json Response theme={null}
{
"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.
```bash Request theme={null}
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](/get-started/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](/developer/webhooks) or call [Read a customer](/api-reference/customers/read-a-customer) to retrieve wallets after approval.
## Related resources
Understand customer entities and verification workflows.
Required data for KYC/KYB verification processes.
Understand post-verification transaction limits.
## What's next
After creating a customer, complete the verification process:
Complete identity verification for individual customers.
Complete identity verification for business customers.