# Returns the trial balance for one entity, accounting book and window.

`POST /accounting/reports/trial-balance/search`

Group: Accounting › Reports › Trial Balances · Operation ID: `searchTrialBalance`

Returns one row per account that has a balance or a movement in the window, for one entity and one accounting book. The rows are the whole chart of accounts, so they include the leaf accounts that hold postings and the grouping accounts that roll them up. A grouping row repeats the sums of its descendants, so add up only the rows where isGroupingAccount is false, or use totals, which is summed from the leaves alone. When total debits do not equal total credits, the response still comes back in full, with a TRIAL_BALANCE_DOES_NOT_TIE_OUT warning. The report is not paginated: it is bounded by the chart of accounts, and a partial page would not tie out.

[Open in the interactive reference](https://docs.api.lensing.ai/?op=searchTrialBalance)

## Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `Api-Version` | header | `"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. |
| `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. |
| `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. |
| `startDate` | string (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. |
| `endDate` | string (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. |
| `dateAxis` | string, one of `"postingDate"`, `"accountingPeriod"` | 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. |

Example:

```json
{
  "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 of 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. |
| `items[].accountNumber` | string | yes | The account number, as defined by the chart of accounts. Rows are ordered by it. |
| `items[].accountName` | string | no | The name of the account. Absent when the account has none recorded. |
| `items[].accountType` | string | no | The type of the account. Possible values: 'asset', 'liability', 'equity', 'income', 'costOfGoodsSold', 'expense', 'otherIncome', 'otherExpense'. |
| `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. |
| `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. |
| `items[].functionalStartingBalance` | string (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. |
| `items[].functionalDebit` | string (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. |
| `items[].functionalCredit` | string (decimal) | yes | Total credit movements within the window, in reportingCurrency. Always present, and zero when there was no movement. Never negative. |
| `items[].functionalEndingBalance` | string (decimal) | yes | The account's balance at the close of endDate, in reportingCurrency. functionalEndingBalance = functionalStartingBalance + functionalDebit - functionalCredit. |
| `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` | string (decimal) | yes | The sum of functionalStartingBalance over the leaf rows. Zero in a balanced ledger. |
| `totals.functionalDebit` | string (decimal) | yes | The sum of functionalDebit over the leaf rows. Equals functionalCredit when the report ties out. |
| `totals.functionalCredit` | string (decimal) | yes | The sum of functionalCredit over the leaf rows. |
| `totals.functionalEndingBalance` | string (decimal) | yes | The sum of functionalEndingBalance over the leaf rows. Zero in a balanced ledger. |
| `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. |
| `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. |

## 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 |

## Statuses

- `400` — Invalid request or business failure. Codes: INVALID_DATE_RANGE, ENTITY_NOT_FOUND, BOOK_NOT_FOUND, CONSOLIDATION_ACCOUNT_MAPPING_MISSING, CONSOLIDATION_RATES_NOT_CONFIGURED, EXCHANGE_RATE_NOT_FOUND, TRIAL_BALANCE_CALCULATION_FAILED
- `401` — Missing or invalid access token
- `403` — Not authorized
- `404` — Not found
- `429` — Too many requests
- `500` — Internal server error