Financial administrations

List all the user groups available to this user.

GET

https://firefly.example.com/api/v1/user-groups

List all the user groups available to this user. These are essentially the 'financial administrations' that Firefly III supports.

curl -X GET 'https://firefly.example.com/api/v1/user-groups' \
  -H 'X-Trace-Id: 40c71bbb-c676-4f24-83cf-cc725d7d7a00' \
  -H 'Authorization: Bearer YOUR_TOKEN'

const response = await fetch('https://firefly.example.com/api/v1/user-groups', {
  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/user-groups',
    headers={
        'X-Trace-Id': '40c71bbb-c676-4f24-83cf-cc725d7d7a00',
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)

{
  "data": [
    {
      "type": "user_groups",
      "id": "2",
      "attributes": {
        "created_at": "2026-10-01T00:00:00+00:00",
        "updated_at": "2026-10-01T00:00:00+00:00",
        "in_use": false,
        "can_see_members": true,
        "title": "demo@firefly",
        "primary_currency_id": "12",
        "primary_currency_code": "EUR",
        "primary_currency_symbol": "$",
        "primary_currency_decimal_places": 2,
        "members": [
          {
            "user_id": "5",
            "user_email": "james@firefly-iii.org",
            "you": false,
            "roles": [
              "ro"
            ]
          }
        ]
      },
      "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.

Response

200OKUserGroupArray

A list of user groups.

Response fields application/vnd.api+json

dataArray<UserGroupRead>required

Show child attributes

typestringrequired

Immutable value

Example

user_groups

idstringrequired

Example

attributesUserGroupReadAttributesrequired

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

in_usebooleanread only

Is this user group ('financial administration') currently the active administration?

Example

false

can_see_membersbooleanread only

Can the current user see the members of this user group?

Example

true

titlestring

Title of the user group. By default, it is the same as the user's email address.

Example

demo@firefly

primary_currency_idstringread only

Returns the primary currency ID of the user group.

Example

primary_currency_codestring

Returns the primary currency code of the user group.

Example

EUR

primary_currency_symbolstringread only

Returns the primary currency symbol of the user group.

Example

primary_currency_decimal_placesinteger<int32>read only

Returns the primary currency decimal places of the user group.

Example

membersArray<UserGroupReadMembers>

Show child attributes

user_idstringread only

The ID of the member.

Example

user_emailstring<email>read only

The email address of the member

Example

james@firefly-iii.org

youbooleanread only

Is this you? (the current user)

Example

false

rolesArray<UserGroupReadRole>romng_trxmng_metaread_budgetsread_piggiesread_subscriptionsread_rulesread_recurringread_webhooksread_currenciesmng_budgetsmng_piggiesmng_subscriptionsmng_rulesmng_recurringmng_webhooksmng_currenciesview_reportsview_membershipsfullowner

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.