Skip to main content

​
Overview

The Categories API allows you to create and manage categories for organizing your transactions. Categories help you group similar types of income and expenses for better financial insights.

​
List All Categories

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

​
Query Parameters

​
page
integer
Page number for pagination
​
start
string
Start date for spent/earned amounts (YYYY-MM-DD)
​
end
string
End date for spent/earned amounts (YYYY-MM-DD)

​
Response Fields

​
id
integer
Category ID
​
created_at
string
ISO 8601 timestamp of creation
​
updated_at
string
ISO 8601 timestamp of last update
​
name
string
Category name
​
notes
string
Category notes
​
object_has_currency_setting
boolean
Always false for categories (categories don’t have currency settings)
​
primary_currency_id
string
Primary currency ID
​
primary_currency_code
string
Primary currency code
​
primary_currency_name
string
Primary currency name
​
primary_currency_symbol
string
Primary currency symbol
​
primary_currency_decimal_places
integer
Decimal places for primary currency
​
spent
array
Array of spent amounts per currency (for date range if provided)
​
pc_spent
array
Array of spent amounts in primary currency
​
earned
array
Array of earned amounts per currency
​
pc_earned
array
Array of earned amounts in primary currency
​
transferred
array
Array of transferred amounts per currency
​
pc_transferred
array
Array of transferred amounts in primary currency

​
Create Category

curl -X POST "https://demo.firefly-iii.org/api/v1/categories" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Groceries",
    "notes": "Food and household items"
  }'
Endpoint: POST /v1/categories

​
Request Body

​
name
string
required
Category name (1-100 characters, must be unique)
​
notes
string
Category notes (max 32,768 characters with newlines supported)
Category names must be unique per user. Attempting to create a duplicate category will result in a validation error.

​
Get Category by ID

curl -X GET "https://demo.firefly-iii.org/api/v1/categories/{id}" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Accept: application/json"
Endpoint: GET /v1/categories/{id} Returns the same response fields as the List endpoint.

​
Query Parameters

​
start
string
Start date for calculating spent/earned amounts (YYYY-MM-DD)
​
end
string
End date for calculating spent/earned amounts (YYYY-MM-DD)

​
Update Category

curl -X PUT "https://demo.firefly-iii.org/api/v1/categories/{id}" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Food & Groceries",
    "notes": "Updated category for all food expenses"
  }'
Endpoint: PUT /v1/categories/{id} Accepts the same parameters as Create Category. All fields are optional.

​
Delete Category

curl -X DELETE "https://demo.firefly-iii.org/api/v1/categories/{id}" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Accept: application/json"
Endpoint: DELETE /v1/categories/{id} Deletes the category. Transactions associated with this category will have their category removed.
Deleting a category removes the category association from all transactions but does not delete the transactions themselves.

​
Get Category Transactions

curl -X GET "https://demo.firefly-iii.org/api/v1/categories/{id}/transactions" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Accept: application/json"
Endpoint: GET /v1/categories/{id}/transactions Returns all transactions associated with this category.

​
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
Transaction type filter: withdrawal, deposit, transfer

​
Get Category Attachments

curl -X GET "https://demo.firefly-iii.org/api/v1/categories/{id}/attachments" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Accept: application/json"
Endpoint: GET /v1/categories/{id}/attachments Returns all attachments associated with this category.

​
Best Practices

​
Category Organization

  1. Keep it simple: Don’t over-categorize. Use broad categories that make sense for your spending habits.
  2. Consistent naming: Use consistent naming conventions for similar categories.
  3. Common categories: Consider using these standard categories:
    • Food & Dining (Groceries, Restaurants)
    • Transportation (Gas, Public Transit, Parking)
    • Housing (Rent, Mortgage, Utilities)
    • Entertainment (Movies, Hobbies, Subscriptions)
    • Healthcare (Medical, Pharmacy, Insurance)
    • Shopping (Clothing, Electronics, Home)
    • Income (Salary, Freelance, Investment)
  4. Review regularly: Periodically review your categories to ensure they’re still relevant.

​
Using with Budgets

Categories and budgets serve different purposes:
  • Categories: Organize and track where money goes (descriptive)
  • Budgets: Set limits and control spending (prescriptive)
You can use both together for comprehensive financial management.