Search for transactions

GET

https://firefly.example.com/api/v1/search/transactions

Searches through the users transactions.

curl -X GET 'https://firefly.example.com/api/v1/search/transactions?query=groceries' \
  -H 'X-Trace-Id: 40c71bbb-c676-4f24-83cf-cc725d7d7a00' \
  -H 'Authorization: Bearer YOUR_TOKEN'

const response = await fetch('https://firefly.example.com/api/v1/search/transactions?query=groceries', {
  method: 'GET',
  headers: {
    'X-Trace-Id': '40c71bbb-c676-4f24-83cf-cc725d7d7a00',
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();

import requests

response = requests.get(
    'https://firefly.example.com/api/v1/search/transactions?query=groceries',
    headers={
        'X-Trace-Id': '40c71bbb-c676-4f24-83cf-cc725d7d7a00',
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)

{
  "data": [
    {
      "type": "transactions",
      "id": "2",
      "attributes": {
        "created_at": "2026-10-01T00:00:00+00:00",
        "updated_at": "2026-10-01T00:00:00+00:00",
        "user": "3",
        "group_title": "Split transaction title.",
        "transactions": [
          {
            "user": "3",
            "transaction_journal_id": "10421",
            "type": "withdrawal",
            "date": "2026-10-01T00:00:00+00:00",
            "order": 0,
            "object_has_currency_setting": true,
            "currency_id": "12",
            "currency_code": "EUR",
            "currency_symbol": "$",
            "currency_name": "Euro",
            "currency_decimal_places": 2,
            "foreign_currency_id": "17",
            "foreign_currency_code": "USD",
            "foreign_currency_symbol": "$",
            "foreign_currency_decimal_places": 2,
            "primary_currency_id": "12",
            "primary_currency_code": "EUR",
            "primary_currency_symbol": "$",
            "primary_currency_decimal_places": 2,
            "amount": "123.45",
            "pc_amount": "123.45",
            "foreign_amount": "123.45",
            "pc_foreign_amount": "123.45",
            "source_balance_after": "123.45",
            "pc_source_balance_after": "123.45",
            "destination_balance_after": "123.45",
            "pc_destination_balance_after": "123.45",
            "description": "Vegetables",
            "source_id": "2",
            "source_name": "Checking account",
            "source_iban": "NL02ABNA0123456789",
            "source_type": "Asset account",
            "destination_id": "2",
            "destination_name": "Buy and Large",
            "destination_iban": "NL02ABNA0123456789",
            "destination_type": "Asset account",
            "budget_id": "4",
            "budget_name": "Groceries",
            "category_id": "43",
            "category_name": "Groceries",
            "bill_id": "111",
            "bill_name": "Monthly rent",
            "subscription_id": "111",
            "subscription_name": "Monthly rent",
            "reconciled": false,
            "notes": "Some example notes",
            "tags": null,
            "internal_reference": "string",
            "external_id": "string",
            "external_url": "string",
            "original_source": "string",
            "recurrence_id": "string",
            "recurrence_total": 0,
            "recurrence_count": 12,
            "import_hash_v2": "string",
            "sepa_cc": "string",
            "sepa_ct_op": "string",
            "sepa_ct_id": "string",
            "sepa_db": "string",
            "sepa_country": "string",
            "sepa_ep": "string",
            "sepa_ci": "string",
            "sepa_batch_id": "string",
            "interest_date": "2024-01-15T09:30:00Z",
            "book_date": "2024-01-15T09:30:00Z",
            "process_date": "2024-01-15T09:30:00Z",
            "due_date": "2024-01-15T09:30:00Z",
            "payment_date": "2024-01-15T09:30:00Z",
            "invoice_date": "2024-01-15T09:30:00Z",
            "latitude": 51.983333,
            "longitude": 5.916667,
            "zoom_level": 6,
            "has_attachments": false
          }
        ]
      },
      "links": {
        "0": {
          "rel": "self",
          "uri": "/OBJECTS/1"
        },
        "self": "https://demo.firefly-iii.org/api/v1/OBJECTS/1"
      }
    }
  ],
  "meta": {
    "pagination": {
      "total": 3,
      "count": 20,
      "per_page": 100,
      "current_page": 1,
      "total_pages": 1
    }
  },
  "links": {
    "self": "https://demo.firefly-iii.org/api/v1/OBJECT?&page=4",
    "first": "https://demo.firefly-iii.org/api/v1/OBJECT?&page=1",
    "next": "https://demo.firefly-iii.org/api/v1/OBJECT?&page=3",
    "prev": "https://demo.firefly-iii.org/api/v1/OBJECT?&page=2",
    "last": "https://demo.firefly-iii.org/api/v1/OBJECT?&page=12"
  }
}

{
  "message": "Bad Request",
  "exception": "BadRequestHttpException"
}

{
  "message": "Unauthenticated",
  "exception": "AuthenticationException"
}

{
  "message": "Resource not found",
  "exception": "NotFoundHttpException"
}

{
  "message": "Internal Exception",
  "exception": "InternalException"
}

Parameters

limitinteger<int32>query

Number of items per page. The default pagination is per 50 items.

pageinteger<int32>query

Page number. The default pagination is per 50 items.

querystringrequiredquery

The query you wish to search for.

Response

200OKTransactionArray

A list of transactions.

Response fields application/vnd.api+json

dataArray<TransactionRead>required

Show child attributes

typestringrequired

Immutable value

Example

transactions

idstringrequired

Example

attributesTransactionrequired

Show child attributes

created_atstring<date-time>read only

Example

2026-10-01T00:00:00+00:00

updated_atstring<date-time>read only

Example

2026-10-01T00:00:00+00:00

userstringread only

User ID

Example

group_titlestring | null

Title of the transaction if it has been split in more than one piece. Empty otherwise.

Example

Split transaction title.

transactionsArray<TransactionSplit>required

Show child attributes

userstringread only

User ID

Example

transaction_journal_idstringread only

ID of the underlying transaction journal. Each transaction consists of a transaction group (see the top ID) and one or more journals making up the splits of the transaction.

Example

typeTransactionTypePropertywithdrawaldeposittransferreconciliationopening balancerequired

Example

withdrawal

datestring<date-time>required

Date of the transaction

Example

2026-10-01T00:00:00+00:00

orderinteger<int32> | null

Order of this entry in the list of transactions.

Example

object_has_currency_settingbooleanread only

Indicates whether the transaction has a currency setting. For transactions this is always true.

Example

true

currency_idstring

Currency ID for the currency of this transaction.

Example

currency_codestring

Currency code for the currency of this transaction.

Example

EUR

currency_symbolstringread only

Currency symbol for the currency of this transaction.

Example

currency_namestring

Currency name for the currency of this transaction.

Example

Euro

currency_decimal_placesinteger<int32>

Number of decimals used in this currency.

Example

foreign_currency_idstring | null

Currency ID of the foreign currency, if this transaction has a foreign amount.

Example

foreign_currency_codestring | null

Currency code of the foreign currency. Default is NULL.

Example

USD

foreign_currency_symbolstring | nullread only

Example

foreign_currency_decimal_placesinteger<int32> | nullread only

Number of decimals in the foreign currency.

Example

primary_currency_idstring | nullread only

Returns the primary currency ID of the administration. This currency is used as the currency for all pc_* amount and balance fields of this account.

Example

primary_currency_codestring | null

Returns the primary currency code of the administration. This currency is used as the currency for all pc_* amount and balance fields of this account.

Example

EUR

primary_currency_symbolstring | nullread only

See the other primary_* fields.

Example

primary_currency_decimal_placesinteger<int32> | nullread only

See the other primary_* fields.

Example

amountstring<amount>required

Amount of the transaction.

Example

123.45

pc_amountstring<amount>

Amount of the transaction in the primary currency of this administration. The primary_currency_* fields reflect the currency used. This field is NULL if the user does have 'convert to primary' set to true in their settings.

Example

123.45

foreign_amountstring<amount> | null

The amount in the set foreign currency. May be NULL if the transaction does not have a foreign amount.

Example

123.45

pc_foreign_amountstring<amount>

Foreign amount of the transaction in the primary currency of this administration. The primary_currency_* fields reflect the currency used. This field is NULL if the user does have 'convert to primary' set to true in their settings.

Example

123.45

source_balance_afterstring<amount> | null

The balance of the source account. This is the balance in the account's currency which may be different from this transaction, and is not provided in this model.

Example

123.45

pc_source_balance_afterstring<amount> | null

The balance of the source account in the primary currency of this administration. The primary_currency_* fields reflect the currency used. This field is NULL if the user does have 'convert to primary' set to true in their settings.

Example

123.45

destination_balance_afterstring<amount> | null

The balance of the destination account. This is the balance in the account's currency which may be different from this transaction, and is not provided in this model.

Example

123.45

pc_destination_balance_afterstring<amount> | null

The balance of the destination account in the primary currency of this administration. The primary_currency_* fields reflect the currency used. This field is NULL if the user does have 'convert to primary' set to true in their settings.

Example

123.45

descriptionstringrequired

Description of the transaction.

Example

Vegetables

source_idstring | nullrequired

ID of the source account. For a withdrawal or a transfer, this must always be an asset account. For deposits, this must be a revenue account.

Example

source_namestring | null

Name of the source account. For a withdrawal or a transfer, this must always be an asset account. For deposits, this must be a revenue account. Can be used instead of the source_id. If the transaction is a deposit, the source_name can be filled in freely: the account will be created based on the name.

Example

Checking account

source_ibanstring | nullread only

Example

NL02ABNA0123456789

source_typeAccountTypePropertyDefault accountCash accountAsset accountExpense accountRevenue accountInitial balance accountBeneficiary accountImport accountReconciliation accountLoanDebtMortgageread only

Example

Asset account

destination_idstring | nullrequired

ID of the destination account. For a deposit or a transfer, this must always be an asset account. For withdrawals this must be an expense account.

Example

destination_namestring | null

Name of the destination account. You can submit the name instead of the ID. For everything except transfers, the account will be auto-generated if unknown, so submitting a name is enough.

Example

Buy and Large

destination_ibanstring | nullread only

Example

NL02ABNA0123456789

destination_typeAccountTypePropertyDefault accountCash accountAsset accountExpense accountRevenue accountInitial balance accountBeneficiary accountImport accountReconciliation accountLoanDebtMortgageread only

Example

Asset account

budget_idstring | null

The budget ID for this transaction.

Example

budget_namestring | nullread only

The name of the budget used.

Example

Groceries

category_idstring | null

The category ID for this transaction.

Example

category_namestring | null

The name of the category to be used. If the category is unknown, it will be created. If the ID and the name point to different categories, the ID overrules the name.

Example

Groceries

bill_idstring | null

The associated subscription ID for this transaction. bill refers to the OLD name for subscriptions and this field will be removed.

Example

bill_namestring | null

The associated subscription name for this transaction. bill refers to the OLD name for subscriptions and this field will be removed.

Example

Monthly rent

subscription_idstring | null

The associated subscription ID for this transaction.

Example

subscription_namestring | null

The associated subscription name for this transaction.

Example

Monthly rent

reconciledboolean

If the transaction has been reconciled already. When you set this, the amount can no longer be edited by the user.

Example

false

notesstring | null

Example

Some example notes

tagsArray<string> | null

Array of tags.

Example

null

internal_referencestring | null

Reference to internal reference of other systems.

external_idstring | null

Reference to external ID in other systems.

external_urlstring | null

External, custom URL for this transaction.

original_sourcestring | nullread only

System generated identifier for original creator of transaction.

recurrence_idstring | nullread only

Reference to recurrence that made the transaction.

recurrence_totalinteger<int32> | nullread only

Total number of transactions expected to be created by this recurrence repetition. Will be 0 if infinite.

Example

recurrence_countinteger<int32> | nullread only

The # of the current transaction created under this recurrence.

Example

import_hash_v2string | nullread only

Hash value of original import transaction (for duplicate detection).

sepa_ccstring | null

SEPA Clearing Code

sepa_ct_opstring | null

SEPA Opposing Account Identifier

sepa_ct_idstring | null

SEPA end-to-end Identifier

sepa_dbstring | null

SEPA mandate identifier

sepa_countrystring | null

SEPA Country

sepa_epstring | null

SEPA External Purpose indicator

sepa_cistring | null

SEPA Creditor Identifier

sepa_batch_idstring | null

SEPA Batch ID

interest_datestring<date-time> | null

book_datestring<date-time> | null

process_datestring<date-time> | null

due_datestring<date-time> | null

payment_datestring<date-time> | null

invoice_datestring<date-time> | null

latitudenumber<double> | null

Latitude of the transaction's location, if applicable. Can be used to draw a map.

Example

51.983333

longitudenumber<double> | null

Latitude of the transaction's location, if applicable. Can be used to draw a map.

Example

5.916667

zoom_levelinteger<int32> | null

Zoom level for the map, if drawn. This to set the box right. Unfortunately this is a proprietary value because each map provider has different zoom levels.

Example

has_attachmentsboolean

If the transaction has attachments.

Example

false

linksObjectLinkrequired

Show child attributes

0object

Show child attributes

relstring

Example

self

uristring

Example

/OBJECTS/1

selfstring<uri>

Example

https://demo.firefly-iii.org/api/v1/OBJECTS/1

metaMetarequired

Show child attributes

paginationobject

Show child attributes

totalinteger

Example

countinteger

Example

per_pageinteger

Example

current_pageinteger

Example

total_pagesinteger

Example

linksPageLinkrequired

Show child attributes

selfstring<uri>

Example

https://demo.firefly-iii.org/api/v1/OBJECT?&page=4

firststring<uri>

Example

https://demo.firefly-iii.org/api/v1/OBJECT?&page=1

nextstring<uri> | null

Example

https://demo.firefly-iii.org/api/v1/OBJECT?&page=3

prevstring<uri> | null

Example

https://demo.firefly-iii.org/api/v1/OBJECT?&page=2

laststring<uri>

Example

https://demo.firefly-iii.org/api/v1/OBJECT?&page=12

400Bad RequestBadRequestResponse

Bad request

Response fields application/json

messagestring

Example

Bad Request

exceptionstring

Example

BadRequestHttpException

401UnauthorizedUnauthenticatedResponse

Unauthenticated

Response fields application/json

messagestring

Example

Unauthenticated

exceptionstring

Example

AuthenticationException

404Not FoundNotFoundResponse

Page not found

Response fields application/json

messagestring

Example

Resource not found

exceptionstring

Example

NotFoundHttpException

500Internal Server ErrorInternalExceptionResponse

Internal exception

Response fields application/json

messagestring

Example

Internal Exception

exceptionstring

Example

InternalException

Authorization

firefly_iii_authoauth2

OAuth2 authorization code flow. Create a client on your installation's /profile page; it authorizes at /oauth/authorize and issues tokens at /oauth/token there. The URLs below are the demo site's. How to use the API walks through it.

local_bearer_authhttp (bearer)

A Personal Access Token, sent as a bearer token. Create one on your installation under Options > Profile > OAuth > Personal Access Tokens.