Clients

List clients

Retrieve a paginated list of clients with optional search.

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

Query parameters

limitinteger

Number of items to return (default 50, max 100)

offsetinteger

Number of items to skip for pagination (max 10000)

cursorstring
Example:eyJpc3N1ZURhdGUiOiIyMDI2LTAzLTIwIiwiX19pZCI6ImFiYzEyMyJ9

Cursor for cursor-based pagination. Use the nextCursor value from a previous response to fetch the next page. When provided, offset is ignored. The cursor is a base64url-encoded JSON string.

fromstring date
Example:2026-01-01

Start date filter in ISO format (YYYY-MM-DD)

tostring date
Example:2026-12-31

End date filter in ISO format (YYYY-MM-DD)

qstring
Example:acme

Full-text search query. Searches across relevant fields per resource type (e.g., clientName, documentNumber for invoices; name, email for clients). Case-insensitive.

fieldsstring
Example:id,name,total

Comma-separated list of fields to include in the response. The id field is always included. Example: fields=id,name,total

stage'lead' | 'contacted' | 'proposal' | 'active' | 'inactive' | 'lost'
Example:active

Filter clients by pipeline stage

Response

A paginated list of clients

totalinteger

Total number of items matching the query

limitinteger

Number of items per page

offsetinteger

Current offset

nextCursorstring

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.

truncatedboolean

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.

Example response

{
  "data": [
    {
      "name": "Acme Corp",
      "email": "billing@acme.com",
      "phone": "+34 912 345 678",
      "taxId": "B12345678",
      "address": {
        "street": "Calle Gran Via 28",
        "city": "Madrid",
        "province": "Madrid",
        "zip": "28013",
        "country": "ES"
      },
      "nextAction": {
        "title": "Call to validate the accepted quote",
        "dueDate": "2026-07-10"
      }
    }
  ],
  "nextCursor": "eyJpc3N1ZURhdGUiOiIyMDI2LTAzLTIwIiwiX19pZCI6ImFiYzEyMyJ9",
  "truncated": true
}

Changes

No recorded changes to this operation across all 1 revision of this API.