---
title: "List deposits"
method: GET
path: "/v1/deposits"
tags: ["Deposits"]
---

# List deposits

`GET /v1/deposits`

## Request

- Base URL: `https://api.frihet.io`
- URL: `https://api.frihet.io/v1/deposits`
- Auth: API key in header `X-API-Key`

Retrieve a paginated list of deposits with optional date range, client, and search filters.

## Query parameters

- `limit` integer
- `offset` integer
- `cursor` string
- `from` string, date
- `to` string, date
- `q` string
- `fields` string
- `clientId` string

## Response `200`

A paginated list of deposits

- object
  - `data` Deposit[]
    - `id` string: Unique identifier
    - `createdAt` string, date-time
    - `updatedAt` string, date-time
    - `clientId` string, required: ID of the client who made the deposit
    - `clientName` string, required: Client name (denormalized for display)
    - `amount` number, required: Deposit amount (must be positive)
    - `currency` string: Currency code (ISO 4217)
    - `description` string, required: Description of the deposit
    - `receivedDate` string, date, required: Date the deposit was received (YYYY-MM-DD)
    - `paymentMethod` string: Payment method used
    - `paymentReference` string: Payment reference or transaction ID
    - `status` 'active' | 'partially_applied' | 'fully_applied' | 'refunded'
    - `appliedAmount` number: Total amount already applied to invoices
    - `remainingBalance` number: Remaining balance available for application or refund
    - `refundedAmount` number: Total amount refunded to the client
    - `applications` object[]: List of invoice applications for this deposit
      - `invoiceId` string
      - `invoiceNumber` string
      - `amount` number
      - `appliedAt` string, date
  - `total` integer: Total number of items matching the query
  - `limit` integer: Number of items per page
  - `offset` integer: Current offset
  - `nextCursor` string: Cursor for fetching the next page of results. Only present when there are more results available. Pass this value as the `cursor` query parameter in the next request. Base64url-encoded.
  - `truncated` boolean: Only present (and `true`) when the underlying search query saturated the internal 500-document cap. `total` therefore reports the size of the first 500 matches, not the full match count. Narrow the search query (taxId / fiscal id, exact email) to ensure you see every result.

## Other responses

- `400`: Bad request - invalid parameters or request body
- `401`: Authentication required or invalid API key
- `429`: Rate limit exceeded (100 requests per minute)
- `500`: Internal server error

---

[API](https://skmtc.dev/frihet/apis/frihet-api.md) · [All operations](https://skmtc.dev/frihet/apis/frihet-api/llms.txt) · [OpenAPI document](https://skmtc.dev/frihet/apis/frihet-api/revisions/3dd37f6a72d1?raw)