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

# Limit Increase Requests

> Request higher transaction limits for a customer through the API

A limit increase request raises a customer's per-transaction, daily, and monthly limits beyond what their verification level grants. You upload a document that justifies the new limits, submit the requested amounts, and Lumx compliance reviews the request.

<Note>
  Limit increase requests can also be submitted from the [Lumx Dashboard](https://dashboard.lumx.io). For the default limits per verification level and the Dashboard flow, see [Transaction Limits](/compliance/transaction-limits).
</Note>

## Prerequisites

* A customer with approved identity verification (KYC/B)
* An API key with the `WRITE_CUSTOMERS` scope. Creating, tracking, and reading a request all work with that single scope.
* Your environment base URL (see [Environments](/get-started/environments))

<Steps>
  <Step title="Upload the supporting document">
    Send a `POST` request to `/customers/{id}/documents` using the document type that matches the file:

    | **Type code**                        | **Document**                     | **Customer profile**    |
    | :----------------------------------- | :------------------------------- | :---------------------- |
    | `LIMIT_REQUEST_BANK_STATEMENT`       | Bank statement                   | Individual and business |
    | `LIMIT_REQUEST_TAX_RETURN`           | Personal or corporate tax return | Individual and business |
    | `LIMIT_REQUEST_FINANCIAL_STATEMENTS` | Financial statements             | Business                |

    ```bash Upload supporting document 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=LIMIT_REQUEST_BANK_STATEMENT" \
      -F "country=BRA"
    ```

    ```json Response theme={null}
    {
      "documentId": "9d1e2f3a-4b5c-6d7e-8f90-1a2b3c4d5e6f"
    }
    ```

    Keep the `documentId` from the response. Files must be JPG, PNG, or PDF with a maximum size of 10MB.
  </Step>

  <Step title="Create the limit request">
    Send a `POST` request to `/customers/{id}/limit-requests`, referencing that `documentId` as `supportingDocumentId`. `requested.single` cannot exceed `requested.daily`, which cannot exceed `requested.monthly`.

    ```bash Request a limit increase theme={null}
    curl -X POST https://api-sandbox.lumx.io/customers/{id}/limit-requests \
      -H "Authorization: Bearer YOUR_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "requested": {
          "single": "15000.00",
          "daily": "60000.00",
          "monthly": "120000.00"
        },
        "supportingDocumentId": "9d1e2f3a-4b5c-6d7e-8f90-1a2b3c4d5e6f"
      }'
    ```

    ```json Response theme={null}
    {
      "id": "b2e1a2d4-1234-4a3b-9c4d-5e6f7a8b9c0d",
      "customerId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "requested": {
        "single": "15000.00",
        "daily": "60000.00",
        "monthly": "120000.00"
      },
      "approved": {
        "single": null,
        "daily": null,
        "monthly": null
      },
      "supportingDocumentType": "LIMIT_REQUEST_BANK_STATEMENT",
      "supportingDocumentId": "9d1e2f3a-4b5c-6d7e-8f90-1a2b3c4d5e6f",
      "status": "IN_REVIEW",
      "reviewComment": null,
      "createdAt": "2024-01-15T10:00:00Z",
      "updatedAt": "2024-01-15T10:00:00Z"
    }
    ```
  </Step>

  <Step title="Track the request">
    Fetch a single request with `GET /customers/{id}/limit-requests/{id}`, or list every request the customer has made with `GET /customers/{id}/limit-requests`.

    While compliance reviews the request, `status` stays `IN_REVIEW` and the `approved` limits stay `null`. After the review:

    * `status` becomes `APPROVED`, `PARTIALLY_APPROVED`, or `REJECTED`
    * `approved` carries the granted limits
    * `reviewComment` carries the reviewer's note on a rejection or partial approval
    * `updatedAt` is the moment the request was reviewed

    If you'd rather not poll, subscribe to the `customer.limit_request.*` [webhook events](/developer/webhooks#available-events) instead.

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

    See the full request and response schemas in the [API Reference](/api-reference/customers/read-a-limit-request).
  </Step>
</Steps>

## Review outcomes

`APPROVED` grants the new limits in full, `PARTIALLY_APPROVED` grants limits below what was requested based on what the supporting document justifies, and `REJECTED` keeps the customer on their current limits. The approved limits become active immediately. For the full breakdown and review timelines, see [Review outcomes](/compliance/transaction-limits#review-outcomes).

## Sandbox magic numbers

In sandbox, the cents of `requested.single` are a sentinel that drives the simulated review outcome, so no manual back-office review is needed. The create response already reflects the final status, and the matching [webhook events](/developer/webhooks#available-events) fire right away.

| `requested.single` cents | Simulated status                                   |
| :----------------------- | :------------------------------------------------- |
| `.02`                    | `PARTIALLY_APPROVED` (50% of each requested limit) |
| `.03`                    | `REJECTED`                                         |
| Any other value          | `APPROVED` (default, in full)                      |

For example, requesting `"15000.03"` as `requested.single` rejects the request instantly. In production this field has no special effect, and every request waits for manual review.

## Related resources

<CardGroup cols="2">
  <Card title="Transaction Limits" href="/compliance/transaction-limits">
    Default limits per verification level and the Dashboard flow.
  </Card>

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

  <Card title="Document Types" href="/additional-information/document-types">
    Every accepted document type code.
  </Card>

  <Card title="API Reference" href="/api-reference/customers/read-a-limit-request">
    Full request and response schemas.
  </Card>
</CardGroup>