Search API

Search transactions and accounts using powerful query syntax

The Search API allows you to find transactions and accounts using flexible search queries and filters.

Overview

Firefly III provides search endpoints for:

• Transactions - Search through transaction groups with advanced query syntax
• Accounts - Find accounts by name and properties

Search results are paginated and return full resource objects in JSON API format.

Base Path

/api/v1/search

Transaction Search

Search transactions using natural language queries or specific field filters.

Search Transactions

Basic Search

curl -X GET "https://your-firefly-instance.com/api/v1/search/transactions?query=groceries" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

query · string · required

Search query string. Supports natural language and advanced query syntax.

page · integer · default: "1"

Page number for pagination

limit · integer · default: "50"

Number of results per page (max: 65536)

Query Syntax

Firefly III uses a powerful query parser that supports:

Basic Text Search

Search in description and notes:

groceries

Field-Specific Search

Search specific fields:

amount:>100
category:food
account:checking
date:2024-01-01

Operators

Operator	Description	Example
:	Equals	category:groceries
:>	Greater than	amount:>100
:<	Less than	amount:<50
:>=	Greater or equal	amount:>=100
:<=	Less or equal	amount:<=50

Boolean Logic

Combine conditions:

amount:>100 category:food
amount:<50 OR category:entertainment

Quotation Marks

Exact phrase matching:

"monthly rent"
category:"dining out"

Searchable Fields

• description - Transaction description
• amount - Transaction amount
• date - Transaction date
• account - Source or destination account
• category - Category name
• budget - Budget name
• tag - Transaction tags
• notes - Transaction notes
• external_id - External identifier
• internal_reference - Internal reference

The query parser is powered by gdbots/query-parser library, supporting advanced search syntax.

Get Transaction Count

Get the number of transactions matching search criteria without fetching full data.

Count by External ID

curl -X GET "https://your-firefly-instance.com/api/v1/search/transactions/count?external_identifier=INV-2024-001" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

external_identifier · string

Search by external identifier metadata

internal_reference · string

Search by internal reference metadata

description · string

Search by transaction description (exact match)

notes · string

Search in transaction notes (LIKE query)

include_deleted · boolean · default: "false"

Include deleted transactions in the count

count · integer

Total number of matching transactions

The count endpoint is useful for validation before importing transactions or checking for duplicates.

Account Search

Search for accounts by name and properties.

Search Accounts

Search Accounts

curl -X GET "https://your-firefly-instance.com/api/v1/search/accounts?query=savings" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

query · string · required

Search query for account name

type · string

Filter by account type (asset, expense, revenue, etc.)

page · integer · default: "1"

Page number for pagination

limit · integer · default: "50"

Number of results per page

Search Examples

Find High-Value Transactions

Amount Filter

curl -X GET "https://your-firefly-instance.com/api/v1/search/transactions?query=amount:>1000" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Search by Date Range

Date Range

curl -X GET "https://your-firefly-instance.com/api/v1/search/transactions?query=date:>=2024-01-01%20date:<=2024-01-31" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Find Uncategorized Expenses

No Category

curl -X GET "https://your-firefly-instance.com/api/v1/search/transactions?query=type:withdrawal%20category:null" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Search by External Reference

External ID

curl -X GET "https://your-firefly-instance.com/api/v1/search/transactions?query=external_id:INV-2024-001" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Complex Query

Combined Filters

curl -X GET "https://your-firefly-instance.com/api/v1/search/transactions?query=amount:>50%20amount:<200%20category:dining%20date:>=2024-01-01" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Response Format

Search endpoints return standard JSON API formatted responses with:

data · array

Array of matching resources (transactions or accounts)

meta.pagination · object

Pagination metadata including total count and page information

links · object

HATEOAS links for pagination navigation

Performance Tips

Complex queries on large datasets may be slow. Consider:

• Adding date ranges to limit search scope
• Using specific field searches instead of full-text
• Implementing client-side result caching

Optimize Searches

1. Use specific fields - description:rent is faster than just rent
2. Limit date ranges - Add date constraints for better performance
3. Use count endpoint - Check result count before fetching full data
4. Paginate results - Don’t fetch all results at once

URL Encoding

Remember to URL-encode query parameters:

Encoded Query

# Instead of: query=amount:>100 category:food
# Use:
curl -X GET "https://your-firefly-instance.com/api/v1/search/transactions?query=amount%3A%3E100%20category%3Afood" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Search Limitations

• Maximum page size: 65,536 results
• No fuzzy matching (exact or wildcard only)
• Case-insensitive text search
• Boolean operators: AND (space), OR
• No NOT operator support

The search functionality is documented at https://api-docs.firefly-iii.org/?urls.primaryName=2.0.0%20(v1)#/search/searchTransactions

Use Cases

Duplicate Detection

Find potentially duplicate transactions before import:

Check Duplicates

curl -X GET "https://your-firefly-instance.com/api/v1/search/transactions/count?external_identifier=BANK-TX-12345" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Expense Analysis

Find all dining expenses over $50:

Dining Analysis

curl -X GET "https://your-firefly-instance.com/api/v1/search/transactions?query=category:dining%20amount:>50" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Account Lookup

Find accounts by partial name:

Find Accounts

curl -X GET "https://your-firefly-instance.com/api/v1/search/accounts?query=bank&type=asset" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Next Steps

Insights API

Get aggregated financial insights

Data Operations

Bulk operations and data management