> ## 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.

# Individual Verification (KYC)

> Complete identity verification for individual customers

After creating an individual customer, you must complete identity verification (KYC) before they can transact. This guide walks through each step of the process.

<Info>
  If you don't want to build the verification flow via API, you can share the `verification.link` returned in the customer response directly with your customer. The link opens a guided flow where they can submit all required information and documents without any additional API integration.
</Info>

## Prerequisites

* An individual customer already created (see [Create a Customer](/guides/create-a-customer))
* An API key from the [Dashboard](https://dashboard.lumx.io)
* Your environment base URL (see [Environments](/get-started/environments))

## Verification flow

<Steps>
  <Step title="Accept terms of service">
    Before starting verification, the customer must accept the terms of service. Send a `POST` request to `/customers/{id}/tos` to get the acceptance URL. You can optionally include a `redirectUrl` to redirect the customer after they accept.

    ```bash Request theme={null}
    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"
      }'
    ```

    ```json Response theme={null}
    {
      "url": "https://dashboard.lumx.io/tos/sandbox/eyJhbGciOiJSUzI1...",
      "expiresAt": "2026-04-09T16:00:00Z"
    }
    ```

    Share the returned URL with your customer. The link expires after 24 hours. Generate a new one if needed. The `requirements` array will show `TERMS_OF_SERVICE` as `NOT_SENT` until they accept. You can check the status by [reading the customer](/api-reference/customers/read-a-customer).

    <Note>
      The request body is optional. If you don't need to redirect the customer after acceptance, you can send the request without a body.
    </Note>
  </Step>

  <Step title="Send additional information">
    Send a `PATCH` request to `/customers/{id}/additional-information` with the customer's personal and transactional information. This has to be done before uploading documents.

    ```bash Request theme={null}
    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"
      }'
    ```

    All fields are required unless noted otherwise. Here's a summary of the key fields:

    | Field                       | Description                                                           |
    | :-------------------------- | :-------------------------------------------------------------------- |
    | `phone`                     | Phone number in international format                                  |
    | `firstName`, `lastName`     | Customer's name split into parts                                      |
    | `middleName`                | Customer's middle name (optional)                                     |
    | `address`                   | Full address with `country`, `line1`, `city`, `state`, `postalCode`   |
    | `monthlyVolumeInUSD`        | Expected monthly transaction volume in USD                            |
    | `transactionVolumeInUSD`    | Expected volume per transaction in USD                                |
    | `jurisdictions`             | Regions where transactions will occur (e.g., `BRA`, `USA`, `EU`)      |
    | `involvedActivities`        | Activities involved (e.g., `NONE`, `GAMBLING`)                        |
    | `transactionCounterparties` | Who the customer transacts with (e.g., `SELF`, `MERCHANTS_SUPPLIERS`) |
    | `professionalSituation`     | One of: `EMPLOYEE`, `SELF_EMPLOYED`, `UNEMPLOYED`, `RETIRED`, `OTHER` |
    | `professionalOccupation`    | Free-text description of occupation                                   |
    | `sourceOfFunds`             | Origin of funds (e.g., `EMPLOYMENT`, `SAVINGS`, `COMPANY`)            |

    For all accepted values, see the [API Reference](/api-reference/customers/send-additional-information).
  </Step>

  <Step title="Upload documents">
    Upload the required documents using `POST /customers/{id}/documents`. Each document is sent as a `multipart/form-data` request.

    Required documents:

    * One identity document: `ID_CARD`, `PASSPORT`, or `DRIVERS_LICENSE`
    * `BANK_STATEMENT` (must be from the last 6 months)
    * `PROOF_OF_ADDRESS` (must be from the last 90 days)

    Optional documents:

    * `INCOME_TAX_RETURN` (must be from the last calendar year)
    * `DELIVERY_RECEIPT` (must be from the last calendar year)
    * `OTHER` (any additional document)

    <Note>
      Identity documents (`ID_CARD` and `DRIVERS_LICENSE`) require the `side` field. Upload the front and back as separate requests. For the digital Brazilian driver's license (CNH digital), the `side` field is not needed.
    </Note>

    ```bash Upload identity document (front) theme={null}
    curl -X POST https://api-sandbox.lumx.io/customers/{id}/documents \
      -H "Authorization: Bearer YOUR_API_KEY" \
      -F "file=@/path/to/document-front.jpg" \
      -F "type=ID_CARD" \
      -F "side=FRONT_SIDE" \
      -F "country=BRA"
    ```

    ```bash Upload identity document (back) theme={null}
    curl -X POST https://api-sandbox.lumx.io/customers/{id}/documents \
      -H "Authorization: Bearer YOUR_API_KEY" \
      -F "file=@/path/to/document-back.jpg" \
      -F "type=ID_CARD" \
      -F "side=BACK_SIDE" \
      -F "country=BRA"
    ```

    ```bash Upload bank statement theme={null}
    curl -X POST https://api-sandbox.lumx.io/customers/{id}/documents \
      -H "Authorization: Bearer YOUR_API_KEY" \
      -F "file=@/path/to/bank-statement.pdf" \
      -F "type=BANK_STATEMENT" \
      -F "country=BRA"
    ```

    Files must be JPG, PNG, or PDF with a maximum size of 50MB.
  </Step>

  <Step title="Complete liveness check">
    The customer must complete a liveness check by accessing the `verification.link` returned in the customer response. This link opens a guided selfie flow.

    You can retrieve the link at any time by reading the customer:

    ```bash theme={null}
    curl https://api-sandbox.lumx.io/customers/{id} \
      -H "Authorization: Bearer YOUR_API_KEY"
    ```

    <Info>
      For individual customers, verification starts automatically after the liveness check is completed. You do not need to call a separate endpoint to start verification.
    </Info>
  </Step>

  <Step title="Monitor verification status">
    Check the verification status by reading the customer's verification:

    ```bash Request theme={null}
    curl https://api-sandbox.lumx.io/customers/{id}/verifications/{verificationId} \
      -H "Authorization: Bearer YOUR_API_KEY"
    ```

    ```json Response theme={null}
    {
      "customerId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "status": "UNDER_VERIFICATION",
      "level": "STANDARD"
    }
    ```

    | Status               | Description                                         |
    | :------------------- | :-------------------------------------------------- |
    | `NOT_STARTED`        | Customer created but verification not yet initiated |
    | `UNDER_VERIFICATION` | Documents submitted and being reviewed              |
    | `APPROVED`           | Verification complete. Customer can transact        |
    | `RFI`                | Additional documentation required                   |
    | `FINAL_REJECTION`    | Customer permanently rejected                       |

    You can also receive status updates via [webhooks](/developer/webhooks) instead of polling.

    <Tip>
      In sandbox, you can simulate different verification statuses using magic numbers in the customer's `taxId`. See [Sandbox magic numbers](/compliance/identity-verification#sandbox-magic-numbers) for the full list.
    </Tip>
  </Step>
</Steps>

## Handling rejections

When a customer receives `RFI`, the verification response includes details about what needs to be corrected:

```json theme={null}
{
  "customerId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "status": "RFI",
  "level": "STANDARD",
  "statusReason": {
    "rejectLabels": ["screenshot", "unsatisfactory_photos"],
    "documents": [
      {
        "type": "PASSPORT",
        "status": "RFI",
        "comment": "Screenshots aren't accepted. Please upload a live photo of the document.",
        "rejectLabels": ["screenshot", "unsatisfactory_photos"]
      }
    ]
  }
}
```

Re-upload the corrected documents and the verification will automatically resume.

<Warning>
  A `FINAL_REJECTION` is permanent. The customer cannot resubmit documents or be re-verified.
</Warning>

## Review timeline

Standard KYC verification is typically reviewed within 1 business day. See [Identity Verification](/compliance/identity-verification#verification-slas) for full details.

## Related resources

<CardGroup cols="2">
  <Card title="Webhooks" href="/developer/webhooks">
    Receive real-time status updates.
  </Card>

  <Card title="Transaction Limits" href="/compliance/transaction-limits">
    Understand post-verification limits.
  </Card>

  <Card title="Identity Verification" href="/compliance/identity-verification">
    Full compliance requirements.
  </Card>
</CardGroup>