Retrieve a trial balance

Operation ID: searchTrialBalance

Group: Accounting › Reports › Trial Balances

Open in the interactive reference

POST /accounting/reports/trial-balance/search

Read-only: A read that takes its filters in the body. Changes nothing, and ignores Idempotency-Key.

Retrieves the trial balance for one legal entity, book, and date range. The response has one item per account with a balance or a movement between startDate and endDate. The items cover the whole chart of accounts, so they include grouping accounts as well as the accounts below them.

A grouping account's figures repeat the sums of the accounts below it. To add up the report, sum only the items where isGroupingAccount is false, or use totals.

The report is not paginated, because a partial page would not balance.

Parameters

Name In Type Required Description
Api-Version header string · v1 yes The API version this request targets, named by its public identifier. Required on every request; omitting it, or naming a version this company does not have, is answered with 400. This document describes version v1.

Request body

Required, application/json: searchTrialBalanceInput.

Field Type Required Description
entityId string yes The entity to report on. When consolidated is false, only this entity's own postings are included. When true, this is the consolidating parent and the report covers its whole hierarchy. Exactly one entity per request. See id on GET base/entities. Example: "ebbe16c9-2c44-4a8e-a813-6ed5a78ffab3".
bookId string yes The accounting book to report on. It must belong to entityId. A book that belongs to another entity is reported as BOOK_NOT_FOUND. Exactly one book per request, because balances from different books are not comparable. See id on GET accounting/books/:id. Example: "8d534b26-2998-40dd-8727-9fe3f89ff503".
consolidated boolean yes Whether to return the consolidated trial balance for entityId and its hierarchy. When true, subsidiary balances are translated into the parent's currency and intercompany eliminations are applied. When false, only this entity's own trial balance is returned, with no translation and no elimination. Example: false.
startDate date yes The inclusive start of the reporting window. Format YYYY-MM-DD. functionalStartingBalance is the position immediately before this date. Interpreted on the axis named by dateAxis. Example: "2025-01-01".
endDate date yes The inclusive end of the reporting window. Format YYYY-MM-DD. functionalEndingBalance is the position at the close of this date. Interpreted on the axis named by dateAxis. Example: "2025-12-31".
dateAxis any yes Which axis the reporting window is measured on. 'postingDate' counts a movement on the date it was booked, the axis audit and reconciliation want. 'accountingPeriod' counts it in the period it was booked into, where budget comparisons belong. There is no default, because the two axes genuinely disagree for a line booked into an earlier period. One of: "postingDate", "accountingPeriod". Example: "postingDate". 
{
  "entityId": "ebbe16c9-2c44-4a8e-a813-6ed5a78ffab3",
  "bookId": "8d534b26-2998-40dd-8727-9fe3f89ff503",
  "consolidated": false,
  "startDate": "2025-01-01",
  "endDate": "2025-12-31",
  "dateAxis": "postingDate"
}

Response

200 Success

Under data (searchTrialBalanceOutput):

Field Type Required Description
items array<object> yes One row per account that has a balance or a movement in scope, ordered by account number. The rows are the whole chart of accounts, so read isGroupingAccount before summing. An empty array when no account has a balance or movement in the window.
items[].accountId string yes The account this row reports on. See id on GET accounting/accounts/:id. Example: "0383f7c4-6176-4dc3-89e7-48c49511070f".
items[].accountNumber string yes The account number, as defined by the chart of accounts. Rows are ordered by it. Example: "111101".
items[].accountName string no The name of the account. Absent when the account has none recorded. Example: "Chase Checking".
items[].accountType string no The type of the account. Possible values: 'asset', 'liability', 'equity', 'income', 'costOfGoodsSold', 'expense', 'otherIncome', 'otherExpense'. Example: "asset".
items[].isGroupingAccount boolean yes Whether this is a grouping (rollup) account. Its four figures are the sums of its descendants and are already counted in its children's rows, so sum only the rows where this is false, or use totals. Example: false.
items[].parentAccountId string no The grouping account this row rolls up into. Absent at the root of the chart of accounts. See id on GET accounting/accounts/:id. Example: "64e38cef-4809-47b8-b014-59065920d070".
items[].functionalStartingBalance decimal yes The account's balance immediately before startDate, in reportingCurrency. Positive is a debit balance, negative a credit balance. Zero at the start of a fiscal year for an income or expense account, because the year-end rollover moves the prior year's result into retained earnings. Example: "0".
items[].functionalDebit decimal yes Total debit movements within the window, in reportingCurrency. Always present, and zero when there was no movement. Never negative, because a reversal is booked as a credit. Example: "5000701.99".
items[].functionalCredit decimal yes Total credit movements within the window, in reportingCurrency. Always present, and zero when there was no movement. Never negative. Example: "503350.02".
items[].functionalEndingBalance decimal yes The account's balance at the close of endDate, in reportingCurrency. functionalEndingBalance = functionalStartingBalance + functionalDebit - functionalCredit. Example: "4497351.97".
totals object yes The report's column totals, in reportingCurrency, summed over the leaf rows only. functionalDebit and functionalCredit here are the two figures a trial balance compares.
totals.functionalStartingBalance decimal yes The sum of functionalStartingBalance over the leaf rows. Zero in a balanced ledger. Example: "0".
totals.functionalDebit decimal yes The sum of functionalDebit over the leaf rows. Equals functionalCredit when the report ties out. Example: "6156388.01".
totals.functionalCredit decimal yes The sum of functionalCredit over the leaf rows. Example: "6156388.01".
totals.functionalEndingBalance decimal yes The sum of functionalEndingBalance over the leaf rows. Zero in a balanced ledger. Example: "0".
tiesOut boolean yes Whether totals.functionalDebit equals totals.functionalCredit, computed from the figures in this response. When false, the response is still returned in full, with a TRIAL_BALANCE_DOES_NOT_TIE_OUT warning. Example: true.
reportingCurrency string yes The currency every amount in this response is expressed in. Format ISO 4217, for example 'USD'. When consolidated is false this is the entity's own functional currency, and when true it is the consolidating parent's. Example: "USD". 
{
  "data": {
    "items": [
      {
        "accountId": "0383f7c4-6176-4dc3-89e7-48c49511070f",
        "accountNumber": "111101",
        "accountName": "Chase Checking",
        "accountType": "asset",
        "isGroupingAccount": false,
        "parentAccountId": "64e38cef-4809-47b8-b014-59065920d070",
        "functionalStartingBalance": "0",
        "functionalDebit": "5000701.99",
        "functionalCredit": "503350.02",
        "functionalEndingBalance": "4497351.97"
      }
    ],
    "totals": {
      "functionalStartingBalance": "0",
      "functionalDebit": "6156388.01",
      "functionalCredit": "6156388.01",
      "functionalEndingBalance": "0"
    },
    "tiesOut": true,
    "reportingCurrency": "USD"
  },
  "diagnostics": [
    {
      "code": "TRIAL_BALANCE_DOES_NOT_TIE_OUT",
      "message": "<message>",
      "severity": "error",
      "path": [
        "<path>"
      ],
      "details": {
        "functionalDebit": "19.99",
        "functionalCredit": "19.99",
        "difference": "19.99"
      }
    }
  ]
}

Errors

Code Status
INVALID_DATE_RANGE 400
ENTITY_NOT_FOUND 400
BOOK_NOT_FOUND 400
CONSOLIDATION_ACCOUNT_MAPPING_MISSING 400
CONSOLIDATION_RATES_NOT_CONFIGURED 400
EXCHANGE_RATE_NOT_FOUND 400
TRIAL_BALANCE_CALCULATION_FAILED 400

Advisories

Warnings and information a successful response can carry under diagnostics:

Statuses