--- title: "List the live chart of accounts" method: GET path: "/books/ledgers" tags: ["Books"] --- # List the live chart of accounts `GET /books/ledgers` ## Request - Base URL: `https://api.mercury.com/api/v1` - URL: `https://api.mercury.com/api/v1/books/ledgers` - Auth: HTTP bearer - TypeScript: (a function with typed inputs; its response is checked against the schema) Lists the ledgers, i.e. general ledger (GL) accounts, in the organization's live chart of accounts, sorted by name. Each ledger has its `id`, `name`, `sortCode` (account number), `type`, `subType`, `debitCredit` (natural balance), `financialAccountType` (set when the ledger represents a bank or card account), and `parentId` (use it to reconstruct the hierarchy). Each ledger also says which changes the system allows before you write: `isRequired` and `requiredLedgerPurpose` mark required ledgers, which the accounting system needs and which can't be deleted; `editable` says whether line entries can be manually added to or removed from the ledger; `deletable` says whether it can be deleted now, and when it can't, `deleteBlockedReason` says why: `required`, `hasActivity` (it has line entries), `linkedSource` (it is linked to a bank or card account), or `integrationMapped` (an invoicing, commerce, or Plaid integration is mapped to it). Filter with type, subType, debitCredit, and ids; filters combine, so a ledger must match all of them. Results are paginated: pass a response's nextPageToken as pageToken to fetch the next page. To read one ledger by ID, use getBooksLedger. ## Query parameters - `booksId` string, uuid: The Books instance to act on. Must be the token organization's own instance, which it defaults to. - `type` 'asset' | 'liability' | 'equity' | 'revenue' | 'expense': Only return ledgers of this type. - `subType` 'currentAssets' | 'nonCurrentAssets' | 'transfersBetweenAccounts' | 'uncategorizedAssets' | 'currentLiabilities' | 'nonCurrentLiabilities' | 'equity' | 'operatingRevenues' | 'otherIncome' | 'costOfGoodsSold' | 'operatingExpenses' | 'otherExpenses' | 'retainedEarnings': Only return ledgers of this sub-type. - `debitCredit` 'debit' | 'credit': Only return ledgers with this natural balance. - `ids` string[]: Comma-separated list of at most 100 distinct ledger IDs. Only return these ledgers. Every ID must belong to the Books instance. - `pageToken` string: token for pagination - `limit` integer: The maximum number of accounts to return per page, from 1 to 1000. ## Response `200` - GetBooksAPILedgersResponse: Response containing a paginated list of ledgers in the organization's live chart of accounts. - `ledgers` BooksAPILedger[], required: The ledgers on this page. Use each ledger's @parentId@ to reconstruct hierarchy. - `debitCredit` 'debit' | 'credit', required: Whether the ledger has a natural debit or credit balance. - `deletable` boolean, required: Whether the ledger can be deleted now. A ledger can't be deleted if it is required, has line entries, is linked to a bank or card account, or has an integration (invoicing, commerce, or a linked Plaid account) mapped to it. `deleteBlockedReason` says which. - `deleteBlockedReason` 'required' | 'hasActivity' | 'linkedSource' | 'integrationMapped', nullable: Why the ledger can't be deleted. Absent when `deletable` is true. When several reasons apply, only one is given: `required` first, then `linkedSource` for a ledger fed by a Mercury account, since neither can be fixed. Fixing any other reason may reveal another. - `editable` boolean, required: Whether line entries can be manually added to or removed from the ledger, for example by categorizing a transaction to it. False for ledgers whose activity a system controls, such as Mercury bank and card account ledgers and the accounts receivable and accounts payable required ledgers. - `financialAccountType` 'bankAccount' | 'creditCard' | 'payments' | 'payroll' | 'loan' | 'prepaidCard' | 'accountsReceivable' | 'accountsPayable' | 'investment' | 'treasury', nullable: The real-world financial account represented by this ledger, if any. - `id` string, base58 (max length 22), required: The stable identifier for the ledger. - `isRequired` boolean, required: Whether the ledger is a required ledger, which the accounting system needs to operate. Required ledgers can't be deleted, and only their `name`, `sortCode`, and `parentId` can be changed. - `name` string, size < 256, required: The ledger's display name. - `openingBalance` number, double, nullable: The ledger's opening balance in its natural direction (`debitCredit`): positive is a balance on the ledger's natural side, negative on the opposite side. Absent when the ledger has no opening balance. Returned by getBooksLedgers and getBooksLedger only; absent from the ledgers in create and update results. Set or clear it with setBooksLedgerOpeningBalances. - `parentId` string, base58 (max length 22), nullable: The identifier of the ledger's parent, if it is nested. - `requiredLedgerPurpose` 'uncatInflow' | 'uncatOutflow' | 'accountTransfers' | 'openingBalances' | 'accountsReceivable' | 'accountsPayable' | 'wagesExpense' | 'bonusExpense' | 'commissionsExpense' | 'contractorExpense' | 'employeeReimbursements' | 'severanceExpense' | 'payrollTaxExpense' | 'employerBenefitsExpense' | 'healthInsuranceExpense' | 'wagesPayable' | 'payrollTaxPayable' | 'employeeBenefitLiabilities' | 'payrollLiabilities' | 'payrollAdjustmentsClearing' | 'retainedEarnings' | 'currentYearEarnings' | 'benefitsExpense' | 'donationsExpense' | 'benefitsPayable' | 'payrollTaxAccruals' | 'stockExerciseClearing' | 'payrollClearing', nullable: The system function a required ledger fulfills, such as holding uncategorized inflows. Absent for ledgers that aren't required. - `sortCode` string, size < 21, required: The ledger/account number used for chart ordering and template mapping. - `subType` 'currentAssets' | 'nonCurrentAssets' | 'transfersBetweenAccounts' | 'uncategorizedAssets' | 'currentLiabilities' | 'nonCurrentLiabilities' | 'equity' | 'operatingRevenues' | 'otherIncome' | 'costOfGoodsSold' | 'operatingExpenses' | 'otherExpenses' | 'retainedEarnings', required: The ledger's more specific accounting classification. It must belong to the ledger's `type`: `asset`: `currentAssets`, `nonCurrentAssets`, `transfersBetweenAccounts`, `uncategorizedAssets`; `liability`: `currentLiabilities`, `nonCurrentLiabilities`; `equity`: `equity`, `retainedEarnings`; `revenue`: `operatingRevenues`, `otherIncome`; `expense`: `costOfGoodsSold`, `operatingExpenses`, `otherExpenses`. A child ledger has the same type and sub-type as its parent. - `type` 'asset' | 'liability' | 'equity' | 'revenue' | 'expense', required: The ledger's top-level accounting classification. A sub-ledger has the same type as the root of its hierarchy. - `nextPageToken` string, nullable: Token to fetch the next page of results - `prevPageToken` string, nullable: Token to fetch the previous page of results ## Other responses - `400`: Invalid `limit` or `pageToken` or `ids` or `debitCredit` or `subType` or `type` or `booksId` ## Changes - **2026-11-03** `95c77a617769`: 1 info - endpoint added [Operation history](https://skmtc.dev/mercurytechnologies/apis/mercury-api/changes/books/ledgers/get.md) --- [API](https://skmtc.dev/mercurytechnologies/apis/mercury-api.md) - [All operations](https://skmtc.dev/mercurytechnologies/apis/mercury-api/llms.txt) - [OpenAPI document](https://skmtc.dev/mercurytechnologies/apis/mercury-api/revisions/95c77a617769?raw)