> ## Documentation Index
> Fetch the complete documentation index at: https://docs-api.kravata.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Tiers and limits

> Find out which compliance tier each user is in, and the per-transaction and monthly limits of every tier in COP and USD.

Every user operates under a **compliance tier**. A tier defines how much the user can move: per transaction, per day, per month, and so on. Tiers are configured for your company by Kravata; you read them with the API.

A user has **one tier assignment per currency**. For example, a user can be in tier 1 for `COP` and in tier 2 for `USD`.

## 1. Get the tiers and their limits

Call [Get Tier Limits](/stack/api-reference/users/get-tier-limits) (`GET /api/v1/tier/compliance/limits`). It returns your active tiers, ordered by `level`, each one with its limits.

```bash theme={"dark"}
curl "https://partners-api.kravata.co/api/v1/tier/compliance/limits?currency=COP" \
  --cert client.crt --key client.key \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```

```json theme={"dark"}
[
  {
    "id": "6c1f2a0e-3b4d-4f5a-9e8b-7c6d5e4f3a21",
    "level": 1,
    "name": "Tier 1",
    "description": "Basic verification",
    "active": true,
    "limits": [
      {
        "operation_type": "DEPOSIT",
        "currency": "COP",
        "amount_single": 4000000,
        "amount_daily": null,
        "amount_monthly": 20000000,
        "balance_limit": null,
        "tx_count_daily": null,
        "tx_count_monthly": null
      }
    ]
  }
]
```

Query parameters, all optional:

| Parameter | Description |
| - | - |
| `currency` | Only limits in this currency, for example `COP` or `USD`. Without it you get every currency. |
| `tier_compliance_id` | Only this tier. |
| `include_inactive` | `true` also returns tiers that are no longer active. Default `false`. |

Each entry in `limits` groups the limits of one operation type in one currency:

| Field | Meaning |
| - | - |
| `operation_type` | `DEPOSIT` (money in) or `WITHDRAW` (money out). |
| `currency` | Currency of the amounts. |
| `amount_single` | Maximum amount of **one** transaction. |
| `amount_daily` | Maximum total amount per day. |
| `amount_monthly` | Maximum total amount per month. |
| `balance_limit` | Maximum balance. |
| `tx_count_daily` / `tx_count_monthly` | Maximum number of transactions per day / per month. |

A `null` value means that tier has no limit of that kind. A tier with an empty `limits` list has no limits configured for the requested currency.

## 2. Find a user's tier

Call [Get Tier User Assignments](/stack/api-reference/users/get-tier-user-assignments) (`GET /api/v1/tier/user-assignments`) with the `user_id` filter:

```bash theme={"dark"}
curl "https://partners-api.kravata.co/api/v1/tier/user-assignments?user_id=USER_ID&currency=COP" \
  --cert client.crt --key client.key \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```

```json theme={"dark"}
{
  "items": [
    {
      "id": "0b9e8d7c-6f5a-4b3c-2d1e-0f9a8b7c6d5e",
      "user_id": "USER_ID",
      "tier_compliance_id": "6c1f2a0e-3b4d-4f5a-9e8b-7c6d5e4f3a21",
      "assigned_at": "2026-10-14T15:20:31.402Z",
      "assigned_by": null,
      "status": "ACTIVE",
      "currency": "COP"
    }
  ],
  "total": 1,
  "page": 1,
  "page_size": 10,
  "order_by": null,
  "order_dir": "asc"
}
```

`tier_compliance_id` is the `id` of a tier from step 1. Match them to get the tier's name, level and limits.

Filters, all optional and combinable:

| Parameter | Description |
| - | - |
| `user_id` | Assignments of this user. |
| `currency` | Assignments in this currency (`COP`, `USD`). |
| `status` | `ACTIVE`, `UNDER_REVIEW` or `SUSPENDED`. |
| `tier_compliance_id` | Users assigned to this tier. |
| `page`, `page_size` | Pagination. `page_size` goes up to 100. |

Without filters, the endpoint lists the assignments of all your users.

<Info>
  A user gets their first assignment for a currency when Kravata first evaluates them in that currency, usually at their first operation. Until then the list can be empty for that user. They start in the **base tier**: the active tier with the lowest `level` that has deposit limits in that currency.
</Info>

### Assignment statuses

| Status | Meaning |
| - | - |
| `ACTIVE` | The tier applies to the user's operations. |
| `UNDER_REVIEW` | The assignment is waiting for a Kravata review, for example after the user asked for higher limits or during onboarding. It is not in effect yet. |
| `SUSPENDED` | The assignment is not in effect. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.