Search Transactions

POST /api/v1/transactions/search

Search transactions using rule-engine style conditions. This provides more powerful filtering than the basic List endpoint.

Request Body

Field	Type	Default	Description
conditions	array	-	Required. Array of condition objects (combined with AND)
currency	string	-	Filter by account currency code (e.g. `USD`). Resolved to the org's accounts of that currency and AND-combined with `conditions`.
page	number	1	Page number
limit	number	100	Items per page (max 500)
sort_by	string	date	Field to sort by
sort_order	string	desc	Sort order: `asc` or `desc`
fields	array	all	Array of field names to return

Condition Object

Each condition in the conditions array:

Field	Type	Required	Description
field	string	Yes	Transaction field to filter on
operator	string	Yes	Comparison operator
value	any	*	Value to compare against
case_sensitive	boolean	No	Case sensitivity for string ops (default: false)

*Value is required for all operators except is_null and is_not_null.

Allowed Fields

Field	Description
`particulars`	Transaction description
`inflow`	Credit amount
`outflow`	Debit amount
`balance`	Account balance
`date`	Transaction date
`type`	Transaction type
`category`	Category name
`entity`	Entity name
`account`	Account ID
`comments`	Notes
`po`	Purchase order

Operators

String Operators

Operator	Description
`equals`	Exact match (case-insensitive by default)
`not_equals`	Does not match
`contains`	Substring match
`not_contains`	Does not contain substring
`starts_with`	Starts with prefix
`ends_with`	Ends with suffix
`regex`	Regular expression match

Numeric Operators

Operator	Description
`equals`	Equal to
`not_equals`	Not equal to
`greater_than`	Greater than
`less_than`	Less than
`greater_than_or_equal`	Greater than or equal
`less_than_or_equal`	Less than or equal

Null Operators

Operator	Description
`is_null`	Field is null/empty
`is_not_null`	Field has value

Date Operators

Operator	Description
`within_last_days`	Date within last N days
`older_than_days`	Date older than N days

Examples

Find ATM Withdrawals Over 1000

curl -X POST "https://statements.finopsbricks.com/api/v1/transactions/search" \
  -H "api-key: fob_stm_xxxxxxxxxxxx" \
  -H "api-secret: xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "conditions": [
      {"field": "particulars", "operator": "contains", "value": "ATM"},
      {"field": "outflow", "operator": "greater_than", "value": 1000}
    ],
    "limit": 50
  }'

Find Uncategorized Transactions

curl -X POST "https://statements.finopsbricks.com/api/v1/transactions/search" \
  -H "api-key: fob_stm_xxxxxxxxxxxx" \
  -H "api-secret: xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "conditions": [
      {"field": "category", "operator": "is_null"}
    ]
  }'

Find Transactions from Last 30 Days

curl -X POST "https://statements.finopsbricks.com/api/v1/transactions/search" \
  -H "api-key: fob_stm_xxxxxxxxxxxx" \
  -H "api-secret: xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "conditions": [
      {"field": "date", "operator": "within_last_days", "value": 30}
    ],
    "sort_by": "date",
    "sort_order": "desc"
  }'

Find USD Transactions Over 100 (Currency Filter)

curl -X POST "https://statements.finopsbricks.com/api/v1/transactions/search" \
  -H "api-key: fob_stm_xxxxxxxxxxxx" \
  -H "api-secret: xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "conditions": [
      {"field": "inflow", "operator": "greater_than", "value": 100}
    ],
    "currency": "USD"
  }'

Find Transactions Using Regex

curl -X POST "https://statements.finopsbricks.com/api/v1/transactions/search" \
  -H "api-key: fob_stm_xxxxxxxxxxxx" \
  -H "api-secret: xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "conditions": [
      {"field": "particulars", "operator": "regex", "value": "INV-\\d{4,6}"}
    ]
  }'

Response

Same format as List Transactions:

{
  "data": [
    {
      "id": "abc123xyz789",
      "date": "2025-01-05",
      "particulars": "ATM WITHDRAWAL",
      "inflow": 0,
      "outflow": 5000.00,
      "balance": 45000.00,
      "entity": null,
      "category": "cash_withdrawal",
      "type": "expense",
      "po": null,
      "comments": null,
      "account_id": "acc123",
      "account_name": "Main Account",
      "account_currency": "INR",
      "statement": "stmt123"
    }
  ],
  "page_context": {
    "count": 25,
    "page": 1,
    "per_page": 100,
    "total": 150,
    "has_more": true
  }
}

Errors

Code	Description
400	Invalid conditions, unknown field, or invalid operator
401	Invalid or missing API credentials
403	API key lacks `transactions:read` permission