Transactions API

Create and manage financial transactions including withdrawals, deposits, and transfers

Overview

The Transactions API allows you to create and manage transaction groups. Each transaction group can contain multiple transaction splits, supporting complex financial scenarios.

List All Transactions

cURL

curl -X GET "https://demo.firefly-iii.org/api/v1/transactions" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Accept: application/json"

Endpoint: GET /v1/transactions

Query Parameters

page · integer

Page number for pagination

start · string

Start date filter (YYYY-MM-DD)

end · string

End date filter (YYYY-MM-DD)

type · string

Filter by type: withdrawal, deposit, transfer, opening-balance, reconciliation

Response Fields

id · integer

Transaction group ID

created_at · string

ISO 8601 timestamp of creation

updated_at · string

ISO 8601 timestamp of last update

user · string

User ID

group_title · string

Optional title for transaction group

transactions · array

Array of transaction objects (see Transaction Object below)

Transaction Object

transaction_journal_id · string

Unique journal identifier

type · string

Transaction type: withdrawal, deposit, transfer, etc.

date · string

Transaction date (ISO 8601)

order · integer

Order within the group

description · string

Transaction description

amount · string

Transaction amount (always positive)

currency_id · string

Currency ID

currency_code · string

Currency code (e.g., USD)

currency_symbol · string

Currency symbol

currency_decimal_places · integer

Decimal places for currency

foreign_amount · string

Foreign currency amount

foreign_currency_id · string

Foreign currency ID

foreign_currency_code · string

Foreign currency code

source_id · string

Source account ID

source_name · string

Source account name

source_iban · string

Source account IBAN

source_type · string

Source account type

destination_id · string

Destination account ID

destination_name · string

Destination account name

destination_iban · string

Destination account IBAN

destination_type · string

Destination account type

budget_id · string

Associated budget ID

budget_name · string

Budget name

category_id · string

Associated category ID

category_name · string

Category name

bill_id · string

Associated bill ID

bill_name · string

Bill name

reconciled · boolean

Whether transaction is reconciled

notes · string

Transaction notes

tags · array

Array of tag strings

internal_reference · string

Internal reference code

external_id · string

External system ID

external_url · string

External URL reference

original_source · string

Import source identifier

sepa_cc · string

SEPA credit card reference

sepa_ct_op · string

SEPA credit transfer operation

sepa_ct_id · string

SEPA credit transfer ID

sepa_db · string

SEPA direct debit

sepa_country · string

SEPA country code

sepa_ep · string

SEPA endpoint

sepa_ci · string

SEPA creditor identifier

sepa_batch_id · string

SEPA batch ID

interest_date · string

Interest calculation date

book_date · string

Booking date

process_date · string

Processing date

due_date · string

Due date

payment_date · string

Payment date

invoice_date · string

Invoice date

latitude · number

Geographic latitude

longitude · number

Geographic longitude

zoom_level · integer

Map zoom level

Create Transaction

cURL

curl -X POST "https://demo.firefly-iii.org/api/v1/transactions" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "group_title": "Weekly groceries",
    "error_if_duplicate_hash": false,
    "apply_rules": true,
    "fire_webhooks": true,
    "transactions": [
      {
        "type": "withdrawal",
        "date": "2024-01-15T10:30:00Z",
        "amount": "125.50",
        "description": "Grocery shopping",
        "source_id": "1",
        "destination_name": "Supermarket",
        "category_name": "Groceries",
        "budget_id": "3",
        "tags": ["food", "essential"]
      }
    ]
  }'

Endpoint: POST /v1/transactions

Request Body

group_title · string

Optional title for the transaction group (max 1000 characters)

error_if_duplicate_hash · boolean · default: "false"

Error if duplicate transaction hash detected

apply_rules · boolean · default: "true"

Apply transaction rules after creation

fire_webhooks · boolean · default: "true"

Trigger webhooks for this transaction

transactions · array · required

Array of transaction objects (minimum 1)

Transaction Object Fields

transactions[].type · string · required

Transaction type: withdrawal, deposit, transfer, opening-balance, reconciliation

transactions[].date · string · required

Transaction date (ISO 8601 format or date)

transactions[].amount · string · required

Transaction amount (positive number)

transactions[].description · string

Transaction description (1-1000 characters)

transactions[].order · integer

Order within group (min 0)

transactions[].currency_id · integer

Currency ID

transactions[].currency_code · string

3-51 character currency code

transactions[].foreign_amount · string

Foreign currency amount

transactions[].foreign_currency_id · integer

Foreign currency ID

transactions[].foreign_currency_code · string

Foreign currency code

transactions[].source_id · integer

Source account ID (must belong to user)

transactions[].source_name · string

Source account name (1-255 characters)

transactions[].source_iban · string

Source account IBAN

transactions[].source_number · string

Source account number

transactions[].source_bic · string

Source account BIC

transactions[].destination_id · integer

Destination account ID

transactions[].destination_name · string

Destination account name

transactions[].destination_iban · string

Destination account IBAN

transactions[].destination_number · string

Destination account number

transactions[].destination_bic · string

Destination account BIC

transactions[].budget_id · integer

Budget ID (must exist and belong to user)

transactions[].budget_name · string

Budget name (1-255 characters)

transactions[].category_id · integer

Category ID (must exist and belong to user)

transactions[].category_name · string

Category name (1-255 characters)

transactions[].bill_id · integer

Bill ID (must exist and belong to user)

transactions[].bill_name · string

Bill name (1-255 characters)

transactions[].piggy_bank_id · integer

Piggy bank ID

transactions[].piggy_bank_name · string

Piggy bank name

transactions[].reconciled · boolean

Mark as reconciled

transactions[].notes · string

Transaction notes (max 32,768 characters)

transactions[].tags · array

Array of tag strings (max 255 characters each)

transactions[].internal_reference · string

Internal reference (1-255 characters)

transactions[].external_id · string

External ID (1-255 characters)

transactions[].external_url · string

External URL (valid URL, 1-255 characters)

transactions[].bunq_payment_id · string

Bunq payment ID

transactions[].sepa_cc · string

SEPA credit card reference

transactions[].sepa_ct_op · string

SEPA credit transfer operation

transactions[].sepa_ct_id · string

SEPA credit transfer ID

transactions[].sepa_db · string

SEPA direct debit

transactions[].sepa_country · string

SEPA country

transactions[].sepa_ep · string

SEPA endpoint

transactions[].sepa_ci · string

SEPA creditor identifier

transactions[].sepa_batch_id · string

SEPA batch ID

transactions[].interest_date · string

Interest date (YYYY-MM-DD)

transactions[].book_date · string

Book date (YYYY-MM-DD)

transactions[].process_date · string

Process date (YYYY-MM-DD)

transactions[].due_date · string

Due date (YYYY-MM-DD)

transactions[].payment_date · string

Payment date (YYYY-MM-DD)

transactions[].invoice_date · string

Invoice date (YYYY-MM-DD)

transactions[].latitude · number

Geographic latitude

transactions[].longitude · number

Geographic longitude

transactions[].zoom_level · integer

Map zoom level

Transaction Types:

• withdrawal: Money leaves your asset accounts
• deposit: Money enters your asset accounts
• transfer: Money moves between asset accounts
• opening-balance: Set initial account balance
• reconciliation: Balance adjustment

Get Transaction by ID

cURL

curl -X GET "https://demo.firefly-iii.org/api/v1/transactions/{id}" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Accept: application/json"

Endpoint: GET /v1/transactions/{id}

Returns the same response structure as the List endpoint.

Update Transaction

cURL

curl -X PUT "https://demo.firefly-iii.org/api/v1/transactions/{id}" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "transactions": [
      {
        "description": "Updated description",
        "amount": "150.00",
        "category_name": "Food & Dining"
      }
    ]
  }'

Endpoint: PUT /v1/transactions/{id}

Accepts the same parameters as Create Transaction. All fields are optional.

Delete Transaction

cURL

curl -X DELETE "https://demo.firefly-iii.org/api/v1/transactions/{id}" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Accept: application/json"

Endpoint: DELETE /v1/transactions/{id}

Deletes the entire transaction group and all splits.

Deleting a transaction cannot be undone. All associated splits will be permanently removed.

Related Endpoints

Get Transaction Attachments

Endpoint: GET /v1/transactions/{id}/attachments

Returns all attachments for this transaction.

Get Transaction Piggy Bank Events

Endpoint: GET /v1/transactions/{id}/piggy-bank-events

Returns piggy bank events triggered by this transaction.