Skip to main content

​
Overview

The Tags API allows you to create and manage tags for organizing transactions. Tags provide a flexible way to label transactions with multiple attributes, making it easy to filter and analyze your financial data.

​
List All Tags

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

​
Query Parameters

​
page
integer
Page number for pagination

​
Response Fields

​
id
integer
Tag ID
​
created_at
string
ISO 8601 timestamp of creation
​
updated_at
string
ISO 8601 timestamp of last update
​
tag
string
Tag name/text
​
date
string
Optional date associated with tag (YYYY-MM-DD)
​
description
string
Tag description
​
latitude
number
Geographic latitude
​
longitude
number
Geographic longitude
​
zoom_level
integer
Map zoom level

​
Create Tag

curl -X POST "https://demo.firefly-iii.org/api/v1/tags" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "tag": "vacation-2024",
    "date": "2024-07-01",
    "description": "Summer vacation expenses",
    "latitude": 40.7128,
    "longitude": -74.0060,
    "zoom_level": 10
  }'
Endpoint: POST /v1/tags

​
Request Body

​
tag
string
required
Tag name (1-1024 characters, must be unique)
​
description
string
Tag description (1-32,768 characters)
​
date
string
Date associated with tag (YYYY-MM-DD, after 1970-01-02, before 2038-01-17)
​
latitude
number
Geographic latitude (-90 to 90)
​
longitude
number
Geographic longitude (-180 to 180)
​
zoom_level
integer
Map zoom level (0-80)
Location Support:Tags support location information, making them useful for tracking expenses by place. This is particularly helpful for:
  • Travel expenses
  • Business trips
  • Location-based spending analysis

​
Get Tag by ID

curl -X GET "https://demo.firefly-iii.org/api/v1/tags/{tagOrId}" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Accept: application/json"
Endpoint: GET /v1/tags/{tagOrId} You can use either the tag ID (integer) or tag name (string) in the URL.

​
Examples

  • GET /v1/tags/42 - Get tag by ID
  • GET /v1/tags/vacation-2024 - Get tag by name

​
Update Tag

curl -X PUT "https://demo.firefly-iii.org/api/v1/tags/{tagOrId}" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "tag": "vacation-2024-europe",
    "description": "European vacation expenses"
  }'
Endpoint: PUT /v1/tags/{tagOrId} Accepts the same parameters as Create Tag. All fields are optional.

​
Delete Tag

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

​
Get Tag Transactions

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

​
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 Tag Attachments

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

​
Best Practices

​
Tag Naming Conventions

  1. Use lowercase with hyphens: vacation-2024, business-trip, client-acme
  2. Be descriptive but concise: Tags should be easy to read and understand at a glance
  3. Use categories for broad classification: Reserve tags for specific attributes or projects

​
Common Tag Uses

Projects and Events:
  • home-renovation
  • wedding-planning
  • vacation-japan-2024
Tax and Accounting:
  • tax-deductible
  • business-expense
  • reimbursable
People or Entities:
  • client-acme-corp
  • gift-for-mom
  • shared-with-roommate
Status or Workflow:
  • pending-reimbursement
  • needs-review
  • personal
  • work

​
Multiple Tags

Transactions can have multiple tags. Use this to create flexible classification systems: 
{
  "tags": [
    "business-expense",
    "tax-deductible",
    "client-acme",
    "q1-2024"
  ]
}

​
Tags vs Categories vs Budgets

  • Categories: Broad classification (what type of expense)
  • Budgets: Financial planning (how much to spend)
  • Tags: Flexible attributes (additional context)
Example transaction:
  • Category: Travel
  • Budget: Vacation
  • Tags: japan-2024, business-trip, reimbursable