---
title: "List clients"
method: GET
path: "/v1/clients"
tags: ["Clients"]
---

# List clients

`GET /v1/clients`

## Request

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

Retrieve a paginated list of clients with optional search.

## Query parameters

- `limit` integer
- `offset` integer
- `cursor` string
- `from` string, date
- `to` string, date
- `q` string
- `fields` string
- `stage` 'lead' | 'contacted' | 'proposal' | 'active' | 'inactive' | 'lost'

## Response `200`

A paginated list of clients

- object
  - `data` Client[]
    - `id` string: Unique identifier
    - `createdAt` string, date-time
    - `updatedAt` string, date-time
    - `name` string, required: Client name (person or company)
    - `email` string, email: Contact email
    - `phone` string: Phone number
    - `taxId` string: Tax identification number (NIF/CIF/VAT)
    - `address` Address: Structured address. Canonical fields are `province` and `zip`. The aliases `state` and `postalCode` are also accepted for backward compatibility.
      - `street` string
      - `city` string
      - `province` string: Province or state (canonical field)
      - `zip` string: Postal/ZIP code (canonical field)
      - `country` string
      - `state` string: Alias for `province` (backward compatibility)
      - `postalCode` string: Alias for `zip` (backward compatibility)
    - `integrationSource` 'hubspot' | 'pipedrive' | 'intercom' | 'mailchimp': Source integration when the client is imported from an external CRM or marketing tool.
    - `nextAction` ClientNextAction
      - `title` string, required: Current next step for this client.
      - `dueDate` string, date: Optional due date for the next action.
      - `status` 'open' | 'done', required: Whether the next action is still open or already completed.
      - `source` 'manual' | 'api' | 'integration' | 'system': Origin of the next action.
      - `createdAt` string, date-time
      - `updatedAt` string, date-time
      - `completedAt` string, date-time
  - `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)