Setting Tracking Group labels on bank transaction explanations via the API: is tracking_group_labels supported?

Documentation
1

Hi all,

We have a custom integration that imports daily totals from a payment processor’s CSV export into a FreeAgent bank account and then explains each transaction. It works like this:

  1. Upload the transactions with POST /v2/bank_transactions/statement?bank_account=xxx.
  2. List the account’s transactions for that date range with GET /v2/bank_transactions, and match each upload to what came back by date, amount and description.
  3. Explain each unexplained match against a chosen category with POST /v2/bank_transaction_explanations.

We’d now like to tag each explanation with a Tracking Group label, so the imported income shows up in the Tracking Groups report. The API docs don’t mention Tracking Groups. We’ve found an approach that seems to work, but we’d like to check that it’s correct and supported before relying on it.

  1. Listing tracking groups: GET /v2/tracking_groups seems to return the company’s groups, each with its labels nested inside.

  2. Reading tracking from an explanation: When an explanation has been tagged in the web app, GET /v2/bank_transaction_explanations/ includes this:

"tracking_groups": [
    {
      "name": "Example Group",
      "status": "active",
      "url": "https://api.freeagent.com/v2/tracking_groups/111",
      "labels": [
        {
          "name": "Example Label",
          "status": "active",
          "url": "https://api.freeagent.com/v2/tracking_group_labels/222"
        }
      ]
    }
  ]
  1. Writing tracking with tracking_group_labels: Sending a flat array of label URLs as tracking_group_labels seems to work when creating the explanations, e.g.
POST /v2/bank_transaction_explanations
  {
    "bank_transaction_explanation": {
      "bank_transaction": "https://api.freeagent.com/v2/bank_transactions/333",
      "dated_on": "2026-10-28",
      "description": "Example fees 28/10/2026",
      "gross_value": "0.45",
      "category": "https://api.freeagent.com/v2/categories/001",
      "tracking_group_labels": [
        "https://api.freeagent.com/v2/tracking_group_labels/222"
      ]
    }
  }

Questions

  1. Is tracking_group_labels the intended, supported way to set tracking on bank transaction explanations? Can we rely on it staying stable?
  2. Are there plans to document the Tracking Groups endpoints and attributes, and to add them to the changelog?
  3. If we update (PUT) the explanation, does tracking_group_labels replace all of an explanation’s labels, or add to them? Does sending an empty array clear them?

Thanks