Skip to main content
POST
/
customers
curl --request POST \ --url https://api.lumx.io/customers \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data ' { "type": "BUSINESS", "legalName": "Lumx S.A", "taxId": "42.887.120/0001-00", "incorporationDate": "2020-01-01", "country": "BRA", "email": "hello@lumx.io" } '
{ "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" } ], "metadata": {}, "createdAt": "2021-01-01T00:00:00Z", "updatedAt": "2021-01-01T00:00:00Z" }

Authorizations

​
Authorization
string
header
required

Bearer authentication header on the format Bearer <API_KEY>.

Headers

​
Idempotency-Key
string<uuid>

Optional UUID v4 idempotency key. If you resend the same key with a different request body, the API returns a 409 error. Cached responses include the header X-Idempotency-Cached: true. Keys expire after 24 hours.

Body

application/json
​
type
enum<string>
required

Customer's type.

Available options:
BUSINESS
​
legalName
string
required

Customer's legal name.

Example:

"Lumx S.A"

​
taxId
string
required

Customer's tax ID. It must be a valid tax ID in the country where the company is incorporated.

Example:

"42.887.120/0001-00"

​
incorporationDate
string<date>
required

Customer's incorporation date.

Example:

"2020-01-01"

​
country
string
required

Customer's country (ISO 3166-1 alpha-3).

Example:

"BRA"

​
email
string
required

Customer's email.

Example:

"hello@lumx.io"

​
metadata
object

Optional metadata object to attach to the customer. Accepts any valid JSON object.

Example:
{
  "externalId": "biz_456",
  "tier": "enterprise"
}

Response

201 - application/json

Resource successfully created.

​
id
string<uuid>

Customer's unique identifier.

Example:

"3c90c3cc-0d44-4b50-8888-8dd25736052a"

​
type
enum<string>

Customer's type.

Available options:
BUSINESS
​
legalName
string

Customer's legal name.

Example:

"Lumx S.A"

​
taxId
string

Customer's tax ID.

Example:

"42.887.120/0001-00"

​
incorporationDate
string<date>

Customer's incorporation date.

Example:

"2020-01-01"

​
country
string

Customer's country (ISO 3166-1 alpha-3).

Example:

"BRA"

​
email
string

Customer's email.

Example:

"hello@lumx.io"

​
metadata
object

Custom metadata associated with the customer. Returns an empty object if no metadata was provided.

Example:
{
  "externalId": "usr_123",
  "tier": "premium"
}
​
wallets
object[]

Customer's wallets by blockchain.

​
verification
object

Customer's verification.

​
requirements
object[]

List of document requirements for KYC/KYB verification.

Example:
[
  { "name": "ID_CARD", "status": "NOT_SENT" },
  { "name": "PASSPORT", "status": "NOT_SENT" },
  {
    "name": "BANK_STATEMENT",
    "status": "NOT_SENT"
  }
]
​
additionalInformation
object

Additional information submitted for KYC/KYB verification. Only present after sending additional information.

​
transactionLimits
object

Customer's transaction limits.

​
createdAt
string<date-time>

Creation date and time (UTC).

Example:

"2021-01-01T00:00:00Z"

​
updatedAt
string<date-time>

Last update date and time (UTC).

Example:

"2021-01-01T00:00:00Z"