Skip to main content
GET
/
api
/
transactions
List Transactions
curl --request GET \
  --url https://api.example.com/api/transactions
{
  "success": true,
  "transactions": [
    {
      "id": "<string>",
      "account_id": "<string>",
      "date": "<string>",
      "subcategory_id": {},
      "description": "<string>",
      "amount": 123,
      "description_encrypted": "<string>",
      "amount_encrypted": "<string>",
      "amount_sign": "<string>",
      "bank_category": {},
      "bank_subcategory": {},
      "bank_category_encrypted": {},
      "bank_subcategory_encrypted": {},
      "subcategory_name": "<string>",
      "subcategory_color": "<string>",
      "category_name": "<string>",
      "category_color": "<string>",
      "created_at": "<string>",
      "updated_at": "<string>"
    }
  ],
  "total": 123,
  "limit": 123,
  "offset": 123,
  "error": "<string>"
}

​
Overview

This endpoint retrieves transactions for a specified account with support for filtering, searching, and pagination. It returns both encrypted and unencrypted fields depending on how the transactions were created.

​
Authentication

Requires a valid authentication token. Only transactions belonging to accounts owned by the authenticated user will be returned.

​
Query Parameters

​
account_id
string
required
UUID of the account to retrieve transactions from
​
start_date
string
Filter transactions from this date onwards (YYYY-MM-DD format)
​
end_date
string
Filter transactions up to this date (YYYY-MM-DD format)
​
subcategory_id
string
Filter transactions by subcategory UUID
​
min_amount
number
Filter transactions with amount greater than or equal to this value
​
max_amount
number
Filter transactions with amount less than or equal to this value
​
search
string
Search term to filter transactions by description. Maximum 255 characters.
​
type
string
Filter by transaction type
​
limit
number
Number of transactions to return per page. Must be a positive integer. Defaults to 50.
​
offset
number
Number of transactions to skip for pagination. Must be >= 0. Defaults to 0.

​
Response

​
success
boolean
Indicates whether the request was successful
​
transactions
array
Array of transaction objects with details
​
total
number
Total number of transactions matching the filters (before pagination)
​
limit
number
Number of transactions returned per page
​
offset
number
Number of transactions skipped

​
Examples

​
Basic Request

curl -X GET "https://api.example.com/api/transactions?account_id=123e4567-e89b-12d3-a456-426614174000" \
  -H "Cookie: token=your-auth-token"

​
Request with Filters

curl -X GET "https://api.example.com/api/transactions?account_id=123e4567-e89b-12d3-a456-426614174000&start_date=2026-01-01&end_date=2026-03-31&type=expense&limit=20&offset=0" \
  -H "Cookie: token=your-auth-token"

curl -X GET "https://api.example.com/api/transactions?account_id=123e4567-e89b-12d3-a456-426614174000&search=grocery&subcategory_id=987fcdeb-51a2-43f1-b789-123456789abc" \
  -H "Cookie: token=your-auth-token"

​
Response with Encrypted Transactions

{
  "success": true,
  "transactions": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "account_id": "123e4567-e89b-12d3-a456-426614174000",
      "date": "2026-03-01T00:00:00.000Z",
      "description_encrypted": "U2FsdGVkX1+xxx...",
      "amount_encrypted": "U2FsdGVkX1+yyy...",
      "amount_sign": "negative",
      "subcategory_id": "987fcdeb-51a2-43f1-b789-123456789abc",
      "subcategory_name": "Groceries",
      "subcategory_color": "#4CAF50",
      "category_name": "Food & Dining",
      "category_color": "#8BC34A",
      "bank_category_encrypted": null,
      "bank_subcategory_encrypted": null,
      "created_at": "2026-03-05T10:30:00.000Z",
      "updated_at": "2026-03-05T10:30:00.000Z"
    },
    {
      "id": "660e8400-e29b-41d4-a716-446655440001",
      "account_id": "123e4567-e89b-12d3-a456-426614174000",
      "date": "2026-02-28T00:00:00.000Z",
      "description_encrypted": "U2FsdGVkX1+zzz...",
      "amount_encrypted": "U2FsdGVkX1+aaa...",
      "amount_sign": "positive",
      "subcategory_id": "111fcdeb-51a2-43f1-b789-123456789def",
      "subcategory_name": "Salary",
      "subcategory_color": "#2196F3",
      "category_name": "Income",
      "category_color": "#03A9F4",
      "bank_category_encrypted": null,
      "bank_subcategory_encrypted": null,
      "created_at": "2026-03-01T09:00:00.000Z",
      "updated_at": "2026-03-01T09:00:00.000Z"
    }
  ],
  "total": 2,
  "limit": 50,
  "offset": 0
}

​
Response with Unencrypted Transactions

{
  "success": true,
  "transactions": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "account_id": "123e4567-e89b-12d3-a456-426614174000",
      "date": "2026-03-01T00:00:00.000Z",
      "description": "Grocery shopping at Whole Foods",
      "amount": 125.50,
      "subcategory_id": "987fcdeb-51a2-43f1-b789-123456789abc",
      "subcategory_name": "Groceries",
      "subcategory_color": "#4CAF50",
      "category_name": "Food & Dining",
      "category_color": "#8BC34A",
      "bank_category": null,
      "bank_subcategory": null,
      "created_at": "2026-03-05T10:30:00.000Z",
      "updated_at": "2026-03-05T10:30:00.000Z"
    }
  ],
  "total": 1,
  "limit": 50,
  "offset": 0
}

​
Error Responses

​
success
boolean
Always false for errors
​
error
string
Error message describing what went wrong

​
Common Errors

  • 400 Bad Request: Invalid query parameters (e.g., invalid UUID, invalid date format)
  • 401 Unauthorized: Missing or invalid authentication token
  • 404 Not Found: Account not found or user doesn’t have access

​
Example Error Response

{
  "success": false,
  "error": "account_id debe ser un UUID válido"
}

​
Pagination

To paginate through results:
  1. First request: ?account_id=xxx&limit=50&offset=0
  2. Second request: ?account_id=xxx&limit=50&offset=50
  3. Third request: ?account_id=xxx&limit=50&offset=100
Use the total field in the response to determine the total number of pages.

​
Notes

  • The search parameter only works with unencrypted transactions (searches the description field)
  • For encrypted transactions, filtering by min_amount and max_amount is not supported as amounts are encrypted
  • The response includes category and subcategory details through database JOINs
  • Transactions are returned in descending order by date (newest first)

Build docs developers (and LLMs) love

Get started for freeTalk to us