Read General Ledger

POST /accounting/reports/general-ledger

Group: Accounting › Reports › General Ledger · Operation ID: readGeneralLedger

Returns the general ledger for one book and entity over a bounded window: the posted journal entry lines and the lines the ledger derives so the statements tie out. It reports movements only, with no opening, closing or running balance. It is not paginated, so narrow the request until it returns in one response, or it fails with RESULT_TOO_LARGE.

Open in the interactive reference

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: readGeneralLedgerInput.

Field Type Required Description
bookId string yes The accounting book to read. Exactly one book per request. An adjustment book automatically includes its base book. See id on GET accounting/books/:id.
entityId string yes The entity to read. When consolidated is false, this is the posting entity. When true, this is the consolidating parent, and the response covers its whole hierarchy, with each line also carrying preConsolidationEntityId naming the child that posted it. Exactly one entity per request. See id on GET base/entities.
consolidated boolean yes Whether to return the consolidated ledger for entityId and its hierarchy. When true, amounts are also translated into the parent's currency and elimination and CTA lines appear. When false, this returns the entity's own ledger with no translation, elimination or CTA.
postingDate object no A window on the posting date, the date a line was booked. Supply exactly one of postingDate or accountingPeriod. Both bounds are inclusive. The window may span at most 366 days.
postingDate.start string (date) yes The inclusive start of the window. Use format YYYY-MM-DD.
postingDate.end string (date) yes The inclusive end of the window. Use format YYYY-MM-DD.
accountingPeriod object no A window on the accounting period, the period a line was booked into. Supply exactly one of postingDate or accountingPeriod. Both bounds are inclusive. The resolved period dates may span at most 366 days.
accountingPeriod.startPeriodId string yes The first accounting period in the window. See accountingPeriodId on GET accounting/accounting-periods.
accountingPeriod.endPeriodId string yes The last accounting period in the window, read the same way.
filters object no Narrows which lines are returned, pushed down into the ledger computation wherever the ledger can express it. Derived amounts stay honest: a filter naming a derived line's offset account, such as CTA, translation elimination or retained earnings, is computed across every line in scope, and a filter that excludes those accounts drops those lines rather than returning a partial figure. Because derived lines carry almost no dimensions, any dimension filter drops nearly every retained-earnings, elimination and CTA line, so the returned lines no longer sum to a balanced ledger and the response carries a RESULT_DOES_NOT_TIE_OUT warning. lineOrigins is applied to the computed result rather than pushed down, as are tags on a dimension the ledger does not index.
filters.accountIds array of string no Restrict to these accounts. Naming a derived line's offset account returns that line with its amount computed across all accounts. Omitting it drops the line, so a partial CTA is never returned. See id on GET accounting/accounts/:id.
filters.lineOrigins array of string, one of "posted", "retainedEarnings", "elimination", "cta", "ctaElimination" no Restrict to these kinds of line. Omit for all kinds. Pass ['posted'] for posted journal entry lines only, excluding everything the ledger derives.
filters.reportingTags array of object no Restrict to lines carrying all of these dimension values. This is the one dimension filter: every dimension is filtered here, whether the ledger stores it as a column, such as department, business unit, value center, employee, customer or vendor, or as a tag, such as a custom dimension, team, location or region. Naming two values of the same dimension matches nothing, since a line has one value per dimension. A value that does not exist matches nothing rather than failing.
filters.reportingTags[].dimensionCode string yes The reporting dimension this filter is for. It determines which model modelId points to. Accepted values: 'department', 'businessUnit', 'team', 'location', 'region', 'employee', 'vendor', 'customer', 'valueCenter', 'custom'.
filters.reportingTags[].modelId string yes The dimension record this filter points to, on the model that dimensionCode names.
dimensions array of string, one of "accounts", "entities", "periods", "books", "reportingTagDimensions" no Which dimension dictionaries to return in dimensions. Omit for all of them, or pass an empty array for none. This never changes the lines: every id is always present on every line. An unrecognized name fails input validation.

Example:

{
  "bookId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "entityId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "consolidated": true,
  "postingDate": {
    "start": "2026-01-15",
    "end": "2026-01-15"
  },
  "accountingPeriod": {
    "startPeriodId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "endPeriodId": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
  },
  "filters": {
    "accountIds": [
      "<accountIds>"
    ],
    "lineOrigins": [
      "posted"
    ],
    "reportingTags": [
      {
        "dimensionCode": "<dimensionCode>",
        "modelId": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
      }
    ]
  },
  "dimensions": [
    "accounts"
  ]
}

Response

200 Success

Under data (readGeneralLedgerOutput):

Field Type Required Description
lines array of object yes The ledger's movements, ordered by posting date, then journal entry, then line. The ids on each line resolve in dimensions. A posted line has journalEntryLineId and journalEntryId to reach the underlying record. A derived line is computed per request and has no id of its own.
lines[].lineOrigin string, one of "posted", "retainedEarnings", "elimination", "cta", "ctaElimination" yes What kind of line this is, and the only field always present. 'posted' is a persisted journal entry line. The rest are derived by the ledger. 'elimination', 'cta' and 'ctaElimination' appear only when consolidated is true.
lines[].accountId string yes The account this line posts to. A derived line lands on the offset account configured for its accounting process, so this is always set. Resolve it in dimensions.accounts.
lines[].entityId string yes The entity this line belongs to. Resolve it in dimensions.entities.
lines[].postingPeriodId string yes The accounting period this line is booked into. Resolve it in dimensions.periods.
lines[].postingDate string (date) yes The posting date. Format YYYY-MM-DD. For a derived line this is the date the ledger assigns it, usually the end of the period it balances.
lines[].bookId string yes The accounting book this line belongs to. Resolve it in dimensions.books.
lines[].journalEntryLineId string no The unique identifier for the posted journal entry line. Present only when lineOrigin is 'posted'.
lines[].journalEntryId string no The journal entry this line belongs to. Present only when lineOrigin is 'posted'. See id on GET accounting/journal-entries/:id.
lines[].journalEntryLineReference string no A human-readable reference to this line within its journal entry. Present only when lineOrigin is 'posted', and can be absent on some posted lines, as the INCOMPLETE_TRANSACTION_REFERENCES warning reports.
lines[].transactionReference string no A reference to the business transaction that produced this line. Present only when lineOrigin is 'posted', and can be absent, as INCOMPLETE_TRANSACTION_REFERENCES reports.
lines[].lineType string no The classification of this line within its journal entry, for example 'standard', 'tax', 'offset' or 'fxRoundingDifference'. A system-assigned value. Absent on a derived line.
lines[].description string no The line description.
lines[].intercompanyPartnerId string no The intercompany counterparty for this line. Set on an intercompany line.
lines[].reportingTags array of object no Every dimension value on this line, one entry each: department, business unit, value center, employee, customer and vendor, alongside any custom dimension. Absent when the line has no dimension, which is normal for a derived line. Resolve each entry in dimensions.reportingTagDimensions.
lines[].reportingTags[].dimensionCode string yes The reporting dimension this value is for. Possible values: 'department', 'businessUnit', 'team', 'location', 'region', 'employee', 'vendor', 'customer', 'valueCenter', 'custom'. Every custom dimension uses the code 'custom', and dimensions.reportingTagDimensions names which one a value belongs to.
lines[].reportingTags[].modelId string yes The dimension record this value points to, on the model that dimensionCode names.
lines[].transactionalCurrency string no The currency the business event happened in. Format ISO 4217, for example 'USD'. Absent on a derived line, which has no transactional amount.
lines[].transactionalDebit string (decimal) no The debit in the transactional currency. A line has either a debit or a credit, not both.
lines[].transactionalCredit string (decimal) no The credit in the transactional currency. A line has either a debit or a credit, not both.
lines[].transactionalAmount string (decimal) no transactionalDebit minus transactionalCredit. Negative for a net credit. To read it in an account's natural direction, with revenue and expense both positive, multiply by the sign that normalBalance implies on the account in dimensions.accounts.
lines[].functionalDebit string (decimal) no The debit in the posting entity's own currency. The currency is functionalCurrency on the entity in dimensions.entities, since it does not vary per line.
lines[].functionalCredit string (decimal) no The credit in the posting entity's own currency.
lines[].functionalAmount string (decimal) no functionalDebit minus functionalCredit.
lines[].functionalExchangeRate string (decimal) no The rate used to convert the transactional amount into the functional currency. Absent on a derived line, which has no transactional amount.
lines[].consolidatedDebit string (decimal) no The debit in the consolidating parent's currency. Present only when consolidated is true. The currency is consolidationCurrency at the top of this response, since it is the same for every line.
lines[].consolidatedCredit string (decimal) no The credit in the consolidating parent's currency. Present only when consolidated is true.
lines[].consolidatedAmount string (decimal) no consolidatedDebit minus consolidatedCredit. Present only when consolidated is true.
lines[].consolidationExchangeRate string (decimal) no The rate used to convert the functional amount into the consolidation currency. Which rate this is depends on the account's exchangeRateType in dimensions.accounts. Present only when consolidated is true.
lines[].preConsolidationAccountId string no The account this line was posted to before consolidation account mapping. Present only when consolidated is true and the account was mapped. Resolve it in dimensions.accounts, which contains both the mapped and the pre-consolidation accounts.
lines[].preConsolidationEntityId string no The child entity that posted this line, before it rolled into the parent. Present only when consolidated is true. Resolve it in dimensions.entities.
lines[].preConsolidationPostingPeriodId string no The period this line sat in before it was re-dated into the parent's fiscal calendar. Differs from postingPeriodId when the parent and child keep different calendars. Present only when consolidated is true. Resolve it in dimensions.periods.
dimensions object yes Display values for the ids on the lines, each appearing once however many lines reference it. A collection is present only when its name was in the dimensions input, which defaults to all of them. Accounts, entities and periods contain both the consolidated and the pre-consolidation records, so every id on every line resolves.
dimensions.accounts array of object no The accounts referenced by any line, including pre-consolidation source accounts. The field names follow the accounts endpoint, so you can join the two without a mapping table.
dimensions.accounts[].id string yes The unique identifier for the account. See id on GET accounting/accounts/:id.
dimensions.accounts[].accountNumber string yes The account number.
dimensions.accounts[].accountName string yes The name of the account.
dimensions.accounts[].accountType string yes The top-level classification of the account. Possible values: 'asset', 'liability', 'equity', 'income', 'costOfGoodsSold', 'expense', 'otherIncome', 'otherExpense'.
dimensions.accounts[].accountSubType string no A finer classification within accountType. Possible values: 'bank', 'accountsReceivable', 'fixedAsset', 'cip', 'prepaidExpenses', 'deferredExpenses', 'otherCurrentAsset', 'otherAsset', 'unbilledReceivable', 'longTermAsset', 'accountsPayable', 'creditCard', 'deferredRevenue', 'otherCurrentLiability', 'longTermLiability', 'equity', 'income', 'costOfGoodsSold', 'expense', 'otherIncome', 'otherExpense', 'otherComprehensiveIncome'. Absent when none is assigned.
dimensions.accounts[].normalBalance string, one of "debit", "credit" yes Whether the account's natural direction is a debit or a credit. Multiply a signed amount by +1 for 'debit' and -1 for 'credit' to read it with revenue and expense both positive.
dimensions.accounts[].exchangeRateType string, one of "current", "average", "historical" no Which rate translates this account's functional amounts into the consolidation currency.
dimensions.entities array of object no The entities referenced by any line, including pre-consolidation child entities.
dimensions.entities[].id string yes The unique identifier for the entity. See id on GET base/entities.
dimensions.entities[].entityName string yes The name of the entity.
dimensions.entities[].functionalCurrency string no The entity's own currency, the currency of every functional amount on its lines. Format ISO 4217, for example 'USD'.
dimensions.periods array of object no The accounting periods referenced by any line, including pre-consolidation periods.
dimensions.periods[].id string yes The unique identifier for the accounting period. See accountingPeriodId on GET accounting/accounting-periods.
dimensions.periods[].periodName string yes The period name, as its fiscal calendar defines it.
dimensions.periods[].fiscalYear string yes The fiscal year this period belongs to.
dimensions.periods[].startDate string (date) yes The first day of the period. Format YYYY-MM-DD.
dimensions.periods[].endDate string (date) yes The last day of the period. Format YYYY-MM-DD.
dimensions.books array of object no The books referenced by any line: the requested book, and its base book when an adjustment book was requested.
dimensions.books[].id string yes The unique identifier for the accounting book. See id on GET accounting/books/:id.
dimensions.books[].name string yes The name of the book.
dimensions.books[].bookType string, one of "full", "adjustment" yes Whether this book is a full book or an adjustment book. An adjustment book has only the deltas layered over its base book, so read it together with its base and add the two rather than read either alone.
dimensions.books[].accountingStandard string no The accounting standard this book reports under, by name, for example 'IFRS', 'US GAAP' or a local standard. A tenant defines its own standards, so treat an unrecognized value as data rather than an error. Absent on a book that declares none.
dimensions.reportingTagDimensions array of object no Every dimension record referenced by a reportingTags entry on any line, named once however many lines reference it. One list for every dimension: department, business unit, value center, employee, customer, vendor, team, location, region and the custom dimensions all resolve here, so adding a dimension adds entries rather than a collection. A record that has since been deactivated is still named, because a posted line legitimately references one.
dimensions.reportingTagDimensions[].dimensionCode string yes The reporting dimension this record is for, matching the dimensionCode on the lines' reportingTags. Possible values: 'department', 'businessUnit', 'team', 'location', 'region', 'employee', 'vendor', 'customer', 'valueCenter', 'custom'.
dimensions.reportingTagDimensions[].modelId string yes The dimension record this entry describes, matching the modelId on the lines' reportingTags. The pair (dimensionCode, modelId) is the key.
dimensions.reportingTagDimensions[].code string no The record's own business code, such as a department number, a customer number or a value center code. Absent for a dimension that keeps no code.
dimensions.reportingTagDimensions[].name string yes The display name of the dimension record.
dimensions.reportingTagDimensions[].customDimensionId string no The custom dimension this record belongs to. Present only for a 'custom' value, where several dimensions share one model and are told apart only by this. See id on GET base/custom-dimensions.
consolidationCurrency string no The consolidating parent's currency, the currency of every consolidated amount in this response. Stated once because it is the same for every line. Format ISO 4217, for example 'USD'. Present only when consolidated is true.

Errors

Code Status
RESULT_TOO_LARGE 400
WINDOW_TOO_LONG 400
DATE_RANGE_REQUIRED 400
AMBIGUOUS_DATE_FILTER 400
ENTITY_NOT_FOUND 400
BOOK_NOT_FOUND 400
PERIOD_NOT_FOUND 400
CONSOLIDATION_ACCOUNTS_NOT_CONFIGURED 400
CONSOLIDATION_ACCOUNT_MAPPING_MISSING 400
CONSOLIDATION_RATES_NOT_CONFIGURED 400
EXCHANGE_RATE_NOT_FOUND 400

Statuses