Skip to main content
KYC reuse lets you onboard a customer with identity verification (KYC) they already completed on your own Sumsub account, instead of asking them to submit documents and complete a liveness check again. You pass a Sumsub share token when creating the customer, and Lumx imports the existing applicant data.
KYC reuse is only available for individual customers. Business customers must go through the standard Business Verification (KYB) flow.

​
Prerequisites

  • A data-sharing agreement between you and Lumx on Sumsub. Both parties must agree to share applicant data before tokens can be exchanged. Contact compliance@lumx.io to set this up.
  • Your own Sumsub account with the customer already verified as an applicant
  • An API key from the Dashboard
  • Your environment base URL (see Environments)

​
Example flow

The exact steps depend on what your Sumsub applicant already contains: data imported through the share token doesn’t need to be submitted again, and Lumx may still require anything that’s missing. The flow below shows a common scenario where the identity documents and liveness check are reused, and the remaining requirements are completed on Lumx. In practice, you’ll still need to send the additional information (Step 4). Reuse typically saves the document upload and liveness check, not the questionnaire. The minimum data Lumx needs is the same as Create a Customer.
1

Generate a share token on Sumsub

Generate a share token for the applicant using the Sumsub share token endpoint. The token authorizes Lumx to import the applicant’s verification data from your Sumsub account.Share tokens are single-use and expire after the ttlInSecs you set when generating them. Sumsub invalidates a token once it’s used, so generate a fresh one for each attempt.
2

Create the customer with the share token

Send a POST request to /customers with the customer’s information and the shareToken field. The customer data must match the applicant data on Sumsub.
Request
curl -X POST https://api-sandbox.lumx.io/customers \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "shareToken": "_act-sbx-jwt-token-from-sumsub",
    "type": "INDIVIDUAL",
    "name": "William Default",
    "taxId": "123.456.789-00",
    "birthDate": "1990-01-01",
    "country": "BRA",
    "email": "william.default@example.com",
    "accounts": ["BRL"]
  }'
The shareToken field is optional. Omitting it creates a customer that goes through the standard Individual Verification (KYC) flow. For the full list of fields, see Create a Customer.
3

Accept terms of service

The customer must still accept the Lumx terms of service. Send a POST request to /customers/{id}/tos to get the acceptance URL and share it with your customer.
Request
curl -X POST https://api-sandbox.lumx.io/customers/{id}/tos \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "redirectUrl": "https://yourapp.com/onboarding/next-step"
  }'
Response
{
  "url": "https://dashboard.lumx.io/tos/sandbox/eyJhbGciOiJSUzI1...",
  "expiresAt": "2026-04-09T16:00:00Z"
}
4

Send additional information

Send a PATCH request to /customers/{id}/additional-information with the customer’s personal and transactional information.
Request
curl -X PATCH https://api-sandbox.lumx.io/customers/{id}/additional-information \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "INDIVIDUAL",
    "phone": "+5511999999999",
    "firstName": "William",
    "middleName": "",
    "lastName": "Default",
    "address": {
      "country": "BRA",
      "line1": "Rua das Flores, 123",
      "city": "São Paulo",
      "state": "SP",
      "postalCode": "01234-567"
    },
    "monthlyVolumeInUSD": "5000",
    "transactionVolumeInUSD": "1000",
    "jurisdictions": ["BRA", "USA", "OTHERS"],
    "involvedActivities": ["NONE"],
    "transactionCounterparties": ["SELF", "MERCHANTS_SUPPLIERS"],
    "professionalSituation": "EMPLOYEE",
    "professionalOccupation": "Software Engineer",
    "sourceOfFunds": "EMPLOYMENT"
  }'
For the accepted values of each field, see Individual Verification (KYC) and the API Reference.
5

Start the verification

Send a POST request to /customers/{id}/verifications to start the verification. Because the documents and liveness check are imported from Sumsub, there is no liveness step to trigger it automatically, so you start it explicitly.
Request
curl -X POST https://api-sandbox.lumx.io/customers/{id}/verifications \
  -H "Authorization: Bearer YOUR_API_KEY"
Monitor the verification status by reading the customer or subscribing to webhooks. Once the status reaches APPROVED, the customer can move money.

​
Errors

Sending a shareToken for a business customer is rejected. Reuse is only available for individuals. If customer creation fails with a share token, the most common causes are a token that’s expired, already used, or generated for a different applicant. Share tokens are single-use, so generate a fresh one and create the customer again. If reuse keeps failing, fall back to the standard Individual Verification (KYC) flow.

Create a Customer

Register individual and business customers.

Individual Verification (KYC)

The standard verification flow without reuse.

Identity Verification

Full compliance requirements.

Webhooks

Receive real-time status updates.