Financial administrations

Update an existing user group.

PUT

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

Used to update a single user group. The available fields are still limited.

curl -X PUT 'https://firefly.example.com/api/v1/user-groups/1' \
  -H 'X-Trace-Id: 40c71bbb-c676-4f24-83cf-cc725d7d7a00' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "title": "New user group title",
  "primary_currency_id": "1",
  "primary_currency_code": "EUR"
}'

const body = `{
  "title": "New user group title",
  "primary_currency_id": "1",
  "primary_currency_code": "EUR"
}`;

const response = await fetch('https://firefly.example.com/api/v1/user-groups/1', {
  method: 'PUT',
  headers: {
    'X-Trace-Id': '40c71bbb-c676-4f24-83cf-cc725d7d7a00',
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();

import requests

body = '''{
  "title": "New user group title",
  "primary_currency_id": "1",
  "primary_currency_code": "EUR"
}'''

response = requests.put(
    'https://firefly.example.com/api/v1/user-groups/1',
    data=body.encode('utf-8'),
    headers={
        'X-Trace-Id': '40c71bbb-c676-4f24-83cf-cc725d7d7a00',
        'Authorization': 'Bearer YOUR_TOKEN',
        'Content-Type': 'application/json',
    },
)
print(response.text)

Request Body

{
  "title": "New user group title",
  "primary_currency_id": "1",
  "primary_currency_code": "EUR"
}

{
  "title": "New user group title",
  "primary_currency_id": "1",
  "primary_currency_code": "EUR"
}

{
  "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"
    }
  }
}

{
  "message": "Bad Request",
  "exception": "BadRequestHttpException"
}

{
  "message": "Unauthenticated",
  "exception": "AuthenticationException"
}

{
  "message": "Resource not found",
  "exception": "NotFoundHttpException"
}

{
  "message": "The given data was invalid.",
  "errors": {
    "email": [
      "string"
    ],
    "force": [
      "string"
    ],
    "blocked": [
      "string"
    ],
    "field": [
      "string"
    ],
    "role": [
      "string"
    ],
    "blocked_code": [
      "string"
    ],
    "name": [
      "string"
    ],
    "type": [
      "string"
    ],
    "iban": [
      "string"
    ],
    "start": [
      "string"
    ],
    "end": [
      "string"
    ],
    "date": [
      "string"
    ]
  }
}

{
  "message": "Internal Exception",
  "exception": "InternalException"
}

Body

JSON array or form-data with new user group information. See the model for the exact specifications.

application/json,application/x-www-form-urlencodedUserGroupUpdate

titlestringrequired

A descriptive title for the user group.

Example

New user group title

primary_currency_idstring

Use either primary_currency_id or primary_currency_code. This will set the primary currency for the user group ('financial administration').

Example

primary_currency_codestring

Use either primary_currency_id or primary_currency_code. This will set the primary currency for the user group ('financial administration').

Example

EUR

Parameters

idstringrequiredpath

The ID of the account.

Response

200OKUserGroupSingle

Updated user group is stored, result is in the response

Response fields application/vnd.api+json

dataUserGroupReadrequired

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

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

422Unprocessable EntityValidationErrorResponse

Validation error. The body will have the exact details.

Response fields application/json

messagestring

Example

The given data was invalid.

errorsobject

Show child attributes

emailArray<string>

forceArray<string>

blockedArray<string>

fieldArray<string>

roleArray<string>

blocked_codeArray<string>

nameArray<string>

typeArray<string>

ibanArray<string>

startArray<string>

endArray<string>

dateArray<string>

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.