Data Operations API - Firefly III

The Data Operations API provides endpoints for bulk modifications, data export, and data management operations.

Overview

Data operation endpoints enable:

Bulk Updates - Modify multiple transactions at once
Data Export - Export various data types to CSV
Data Destruction - Delete all user data
Data Purge - Purge all data except configuration
Batch Processing - Handle batch API requests

Data destruction and purge operations are irreversible. Use with extreme caution.

Bulk Operations

Perform bulk updates on transactions based on query criteria.

Base Path

/api/v1/data/bulk

Bulk Update Transactions

Update multiple transactions by moving them between accounts.

curl -X POST "https://your-firefly-instance.com/api/v1/data/bulk/transactions" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "query": {
      "where": {
        "account_id": "5"
      },
      "update": {
        "account_id": "8"
      }
    }
  }'

query.where.account_id

string

required

Source account ID (transactions to move FROM this account)

query.update.account_id

string

required

Destination account ID (transactions to move TO this account)

This endpoint moves all transactions from one account to another. This is useful when closing or consolidating accounts.

The bulk transaction endpoint requires the MANAGE_TRANSACTIONS role permission.

Response

Returns 204 No Content on success.

Data Export

Export various data types to CSV format for backup or analysis.

Base Path

/api/v1/data/export

Export Accounts

Export all accounts to CSV.

curl -X GET "https://your-firefly-instance.com/api/v1/data/export/accounts" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -o accounts-export.csv

Returns a CSV file with account data.

Export Bills

Export all bills/subscriptions to CSV.

curl -X GET "https://your-firefly-instance.com/api/v1/data/export/bills" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -o bills-export.csv

Export Budgets

Export all budgets to CSV.

curl -X GET "https://your-firefly-instance.com/api/v1/data/export/budgets" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -o budgets-export.csv

Export Categories

Export all categories to CSV.

curl -X GET "https://your-firefly-instance.com/api/v1/data/export/categories" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -o categories-export.csv

Export Piggy Banks

Export all piggy banks to CSV.

curl -X GET "https://your-firefly-instance.com/api/v1/data/export/piggy-banks" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -o piggies-export.csv

Export Recurring Transactions

Export all recurring transactions to CSV.

curl -X GET "https://your-firefly-instance.com/api/v1/data/export/recurring" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -o recurring-export.csv

Export Rules

Export all rules to CSV.

curl -X GET "https://your-firefly-instance.com/api/v1/data/export/rules" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -o rules-export.csv

Export Tags

Export all tags to CSV.

curl -X GET "https://your-firefly-instance.com/api/v1/data/export/tags" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -o tags-export.csv

Export Transactions

Export transactions within a date range to CSV.

curl -X GET "https://your-firefly-instance.com/api/v1/data/export/transactions?start=2024-01-01&end=2024-12-31&accounts=1,2,3" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -o transactions-export.csv

start

date

required

Start date for transaction export (format: YYYY-MM-DD)

end

date

required

End date for transaction export (format: YYYY-MM-DD)

accounts

string

Comma-separated list of account IDs to export. If omitted, exports all accounts.

Export Response Format

All export endpoints return:

Content-Type: application/octet-stream
Content-Disposition: attachment; filename=YYYY-MM-DD-HH-MM-SS-export-{type}.csv
Body: CSV formatted data

Export endpoints require the READ_ONLY role permission or higher.

Data Destruction

Permanently delete user data.

Base Path

/api/v1/data/destroy

Destroy All Data

Delete all user data while preserving the account.

curl -X DELETE "https://your-firefly-instance.com/api/v1/data/destroy" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

This operation is IRREVERSIBLE! All transactions, accounts, budgets, bills, categories, tags, rules, and other financial data will be permanently deleted.

Returns 204 No Content on success.

What Gets Deleted

All transactions (withdrawals, deposits, transfers)
All accounts (asset, expense, revenue)
All budgets and budget limits
All bills and subscriptions
All categories
All tags
All piggy banks
All rules and rule groups
All recurring transactions
All attachments

What Gets Preserved

User account and authentication
User preferences
OAuth clients and tokens
System configuration

Data Purge

Completely purge all data including configuration.

Base Path

/api/v1/data/purge

Purge All Data

Delete all user data AND reset preferences to defaults.

curl -X DELETE "https://your-firefly-instance.com/api/v1/data/purge" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

EXTREME CAUTION! This deletes everything from destroy operation PLUS user preferences and settings. Only the user account remains.

Returns 204 No Content on success.

Purge vs Destroy

Operation	Destroy	Purge
Transactions	✓ Deleted	✓ Deleted
Accounts	✓ Deleted	✓ Deleted
Budgets/Bills/Categories	✓ Deleted	✓ Deleted
User Preferences	Preserved	✓ Deleted
OAuth Tokens	Preserved	✓ Deleted
User Account	Preserved	Preserved

Batch API Endpoints

Handle batch API request processing.

Base Path

/api/v1/batch

Finish Batch Processing

Signal completion of a batch operation.

curl -X POST "https://your-firefly-instance.com/api/v1/batch/finish" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

This endpoint is used internally by batch processing systems. Refer to Firefly III documentation for batch API usage.

Export Use Cases

Full Data Backup

Export all data types for complete backup:

#!/bin/bash

BASE_URL="https://your-firefly-instance.com/api/v1/data/export"
TOKEN="YOUR_ACCESS_TOKEN"
DATE=$(date +%Y-%m-%d)

# Export all data types
for TYPE in accounts bills budgets categories piggy-banks recurring rules tags; do
  curl -X GET "${BASE_URL}/${TYPE}" \
    -H "Authorization: Bearer ${TOKEN}" \
    -o "${DATE}-${TYPE}.csv"
done

# Export transactions for current year
curl -X GET "${BASE_URL}/transactions?start=2024-01-01&end=2024-12-31" \
  -H "Authorization: Bearer ${TOKEN}" \
  -o "${DATE}-transactions.csv"

Monthly Transaction Export

Export transactions for a specific month:

curl -X GET "https://your-firefly-instance.com/api/v1/data/export/transactions?start=2024-11-01&end=2024-11-30" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -o 2024-11-transactions.csv

Account Consolidation

Move all transactions when closing an account:

curl -X POST "https://your-firefly-instance.com/api/v1/data/bulk/transactions" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "query": {
      "where": {"account_id": "5"},
      "update": {"account_id": "1"}
    }
  }'

Security Considerations

Bulk operations and data deletion require appropriate permissions:

Bulk updates: MANAGE_TRANSACTIONS role
Data export: READ_ONLY role or higher
Data destroy/purge: Account owner only

Pre-Deletion Checklist

Before using destroy or purge:

✓ Export all data for backup
✓ Verify exports are complete and valid
✓ Confirm you want to delete everything
✓ Understand the operation is irreversible
✓ Consider using destroy before purge

Rate Limiting

Export operations may take time for large datasets:

Transaction exports: 10-60 seconds for 1000s of transactions
Other exports: Usually < 5 seconds

Export endpoints don’t have pagination - they return complete datasets.

CSV Format

Exported CSV files include:

Header row with column names
UTF-8 encoding
Comma-separated values
Quoted strings where necessary
Date format: YYYY-MM-DD

Error Handling

Missing Parameters

{
  "message": "The given data was invalid.",
  "errors": {
    "start": ["The start field is required."]
  }
}

Invalid Account ID

{
  "message": "The given data was invalid.",
  "errors": {
    "account_id": ["The selected account id is invalid."]
  }
}

Insufficient Permissions

{
  "message": "This action is unauthorized."
}

Limitations

Bulk operations currently only support account-to-account transaction moves
No partial restore from exports (must use web interface or manual import)
CSV exports are one-way (export only, no import via API)
Destroy/purge operations affect only current user’s data

Next Steps

Webhooks API

Configure real-time event notifications

Search API

Search and filter data

​Overview

​Bulk Operations

​Base Path

​Bulk Update Transactions

​Response

​Data Export

​Base Path

​Export Accounts

​Export Bills

​Export Budgets

​Export Categories

​Export Piggy Banks

​Export Recurring Transactions

​Export Rules

​Export Tags

​Export Transactions

​Export Response Format

​Data Destruction

​Base Path

​Destroy All Data

​What Gets Deleted

​What Gets Preserved

​Data Purge

​Base Path

​Purge All Data

​Purge vs Destroy

​Batch API Endpoints

​Base Path

​Finish Batch Processing

​Export Use Cases

​Full Data Backup

​Monthly Transaction Export

​Account Consolidation

​Security Considerations

​Pre-Deletion Checklist

​Rate Limiting

​CSV Format

​Error Handling

​Missing Parameters

​Invalid Account ID

​Insufficient Permissions

​Limitations

​Next Steps

Webhooks API

Search API

Overview

Bulk Operations

Base Path

Bulk Update Transactions

Response

Data Export

Base Path

Export Accounts

Export Bills

Export Budgets

Export Categories

Export Piggy Banks

Export Recurring Transactions

Export Rules

Export Tags

Export Transactions

Export Response Format

Data Destruction

Base Path

Destroy All Data

What Gets Deleted

What Gets Preserved

Data Purge

Base Path

Purge All Data

Purge vs Destroy

Batch API Endpoints

Base Path

Finish Batch Processing

Export Use Cases

Full Data Backup

Monthly Transaction Export

Account Consolidation

Security Considerations

Pre-Deletion Checklist

Rate Limiting

CSV Format

Error Handling

Missing Parameters

Invalid Account ID

Insufficient Permissions

Limitations

Next Steps