API reference
Periods
The months of the books: soft-close, close and reopen them.
- GET
/v1/periodsList the months of the books - GET
/v1/periods/{key}Get a month's close status - POST
/v1/periods/{key}/closeClose (lock) a month - GET
/v1/periods/{key}/closesList every close of a month, reopenings included - GET
/v1/periods/{key}/previewPreview the entries closing a month would post - POST
/v1/periods/{key}/reopenReopen a closed month - POST
/v1/periods/{key}/soft_closeSoft-close a month: the feed waits while it is reviewed
Guides: Close the month
List the months of the books
GET/v1/periods
client.periods.list()
The months these books have, newest first. A month appears once
something is dated in it or it is closed; GET /periods/{key} describes
any month, listed or not.
Parameters
| Name | Type | Description |
|---|---|---|
limitQuery | integer | Page size, 1–200. |
cursorQuery | string or null | The |
statusQuery | string or null | Only open months, or only closed ones. open, soft_closed, locked |
Response
200PeriodPage
Errors
- 400
- The request was malformed or a parameter is invalid.
- 401
- No valid credential was sent.
- 403
- The credential or the member's role does not allow this.
- 404
- No such resource in this ledger.
- 409
- A conflicting request, e.g. one with the same Idempotency-Key still running.
- 422
- A well-formed request a business rule refused.
- 429
- Too many requests; retry after the Retry-After header.
- 500
- Something failed on our side; the request_id identifies it.
Example
curl "https://api.ledgerit.ai/v1/periods" \
-H "Authorization: Bearer $LEDGERIT_TOKEN"Get a month's close status
GET/v1/periods/{key}
client.periods.get()
Everything the close screen needs, in one call.
Deliberately one call: a close screen assembled from six requests shows six different moments, and the whole value of the page is that its parts agree.
Read-only, and open to viewers. It creates no period and raises or clears no exception: it once did both, so a viewer opening an old month created an open period there and blocked every later close. A month with no period yet is described as it would be created.
Parameters
| Name | Type | Description |
|---|---|---|
keyPath · Required | string |
Response
Errors
- 400
- The request was malformed or a parameter is invalid.
- 401
- No valid credential was sent.
- 403
- The credential or the member's role does not allow this.
- 404
- No such resource in this ledger.
- 409
- A conflicting request, e.g. one with the same Idempotency-Key still running.
- 422
- A well-formed request a business rule refused.
- 429
- Too many requests; retry after the Retry-After header.
- 500
- Something failed on our side; the request_id identifies it.
Example
curl "https://api.ledgerit.ai/v1/periods/{key}" \
-H "Authorization: Bearer $LEDGERIT_TOKEN"Close (lock) a month
POST/v1/periods/{key}/close
client.periods.close()
Close a period. Afterwards the ledger refuses to change anything in it.
Parameters
| Name | Type | Description |
|---|---|---|
keyPath · Required | string |
Request body
Response
200PeriodOut
Errors
- 400
- The request was malformed or a parameter is invalid.
- 401
- No valid credential was sent.
- 403
- The credential or the member's role does not allow this.
- 404
- No such resource in this ledger.
- 409
- A conflicting request, e.g. one with the same Idempotency-Key still running.
- 422
- A well-formed request a business rule refused.
- 429
- Too many requests; retry after the Retry-After header.
- 500
- Something failed on our side; the request_id identifies it.
Example
curl -X POST "https://api.ledgerit.ai/v1/periods/{key}/close" \
-H "Authorization: Bearer $LEDGERIT_TOKEN" \
-H "Content-Type: application/json" \
-d '{}'List every close of a month, reopenings included
GET/v1/periods/{key}/closes
client.periods.listCloses()
Every close of the month, oldest first, and the reopening that undid each one but the standing close. A reopen never erases a close: the figures it recorded stay here.
Parameters
| Name | Type | Description |
|---|---|---|
keyPath · Required | string |
Response
Errors
- 400
- The request was malformed or a parameter is invalid.
- 401
- No valid credential was sent.
- 403
- The credential or the member's role does not allow this.
- 404
- No such resource in this ledger.
- 409
- A conflicting request, e.g. one with the same Idempotency-Key still running.
- 422
- A well-formed request a business rule refused.
- 429
- Too many requests; retry after the Retry-After header.
- 500
- Something failed on our side; the request_id identifies it.
Example
curl "https://api.ledgerit.ai/v1/periods/{key}/closes" \
-H "Authorization: Bearer $LEDGERIT_TOKEN"Preview the entries closing a month would post
GET/v1/periods/{key}/preview
client.periods.previewClose()
The entries closing a month would post, before it is closed.
Each recognition schedule's share for the month (prepaids, deferred revenue, accruals and their releases, depreciation), interest on notes and venture debt, stock-based compensation and, in a fiscal year's last month, the year-end entry. They come from rehearsing the close itself and rolling it back, so they are exactly what Close month would post as the books stand now, and nothing is written. Refused like the close for a month still running or after a month still open; it needs the close's permission because it holds the close's locks while it runs.
With them, the accounts whose month swung from its usual month, read from the books as closing leaves them, each explained by what moved it: a schedule, a vendor or customer, or what posted the rest (decision 0148). And the vendors whose monthly, quarterly or yearly bill was due in the month and has not come, each with the Inbox item that accrues it (decisions 0149, 0152).
Parameters
| Name | Type | Description |
|---|---|---|
keyPath · Required | string |
Response
Errors
- 400
- The request was malformed or a parameter is invalid.
- 401
- No valid credential was sent.
- 403
- The credential or the member's role does not allow this.
- 404
- No such resource in this ledger.
- 409
- A conflicting request, e.g. one with the same Idempotency-Key still running.
- 422
- A well-formed request a business rule refused.
- 429
- Too many requests; retry after the Retry-After header.
- 500
- Something failed on our side; the request_id identifies it.
Example
curl "https://api.ledgerit.ai/v1/periods/{key}/preview" \
-H "Authorization: Bearer $LEDGERIT_TOKEN"Reopen a closed month
POST/v1/periods/{key}/reopen
client.periods.reopen()
Reopen a closed period, on the record.
Deliberately possible. A product that makes a real mistake in a closed month unfixable gets worked around with a compensating entry in the wrong period, which is worse than the restatement it was trying to prevent.
Parameters
| Name | Type | Description |
|---|---|---|
keyPath · Required | string |
Request body
Response
200PeriodOut
Errors
- 400
- The request was malformed or a parameter is invalid.
- 401
- No valid credential was sent.
- 403
- The credential or the member's role does not allow this.
- 404
- No such resource in this ledger.
- 409
- A conflicting request, e.g. one with the same Idempotency-Key still running.
- 422
- A well-formed request a business rule refused.
- 429
- Too many requests; retry after the Retry-After header.
- 500
- Something failed on our side; the request_id identifies it.
Example
curl -X POST "https://api.ledgerit.ai/v1/periods/{key}/reopen" \
-H "Authorization: Bearer $LEDGERIT_TOKEN" \
-H "Content-Type: application/json" \
-d '{"reason":"…"}'Soft-close a month: the feed waits while it is reviewed
POST/v1/periods/{key}/soft_close
client.periods.softClose()
Soft-close a month that has ended: people can still post and correct
in it, but transactions from connected accounts wait until it reopens or
locks. Locking it is POST /periods/{key}/close; POST /periods/{key}/reopen opens it again.
Parameters
| Name | Type | Description |
|---|---|---|
keyPath · Required | string |
Response
200PeriodOut
Errors
- 400
- The request was malformed or a parameter is invalid.
- 401
- No valid credential was sent.
- 403
- The credential or the member's role does not allow this.
- 404
- No such resource in this ledger.
- 409
- A conflicting request, e.g. one with the same Idempotency-Key still running.
- 422
- A well-formed request a business rule refused.
- 429
- Too many requests; retry after the Retry-After header.
- 500
- Something failed on our side; the request_id identifies it.
Example
curl -X POST "https://api.ledgerit.ai/v1/periods/{key}/soft_close" \
-H "Authorization: Bearer $LEDGERIT_TOKEN"Objects
The objects these operations take and return.
PeriodPage
| Name | Type | Description |
|---|---|---|
dataRequired | array of PeriodOut | |
has_moreRequired | boolean | |
next_cursorRequired | string or null |
CloseStatusOut
| Name | Type | Description |
|---|---|---|
accountsRequired | array of AccountReconciliationOut | |
blockersRequired | array of BlockerOut | |
can_closeRequired | boolean | |
checklistRequired | array of ChecklistItemOut | |
close_runRequired | CloseRunSummaryOut or null | The month's newest close run: the one being worked, or the close that stands. Null while the month's close has not started. |
closes_fiscal_yearRequired | boolean | Whether the month ends a fiscal year, so closing it also carries the year's result into retained earnings. |
currencyRequired | string | |
open_exceptionsRequired | array of ExceptionItemOut | |
periodRequired | PeriodOut | |
trial_balance_balancedRequired | boolean | |
trial_balance_differenceRequired | string | |
unreviewed_transactionsRequired | integer |
CloseRequest
| Name | Type | Description |
|---|---|---|
force | boolean | Default false |
PeriodOut
| Name | Type | Description |
|---|---|---|
close_version | integer | How many times the month has been closed; each close is kept ( |
closed_atRequired | string (date-time) or null | |
closing_creditsRequired | string or null | |
closing_debitsRequired | string or null | |
ends_onRequired | string (date) | |
fiscal_yearRequired | integer | The fiscal year the month is in, named for the calendar year it ends in. |
keyRequired | string | |
locked_through_sequence | integer or null | While closed: the book's posting sequence at the close. The month's figures are every entry up to it. |
soft_closed_at | string (date-time) or null | When the month was soft-closed; null unless it is. |
starts_onRequired | string (date) | |
statusRequired | string | One of open, soft_closed, locked |
PeriodCloseList
| Name | Type | Description |
|---|---|---|
dataRequired | array of PeriodCloseOut |
ClosePreviewOut
| Name | Type | Description |
|---|---|---|
currencyRequired | string | The books' currency, which every amount is in. |
entriesRequired | array of ClosePreviewEntryOut | What closing the month would post, in the order it would post it. Empty when it would post nothing, and for a month already closed. |
missing_accrualsRequired | array of MissingAccrualOut | The vendors the books' daily check found missing from the month, still unanswered: each bills monthly, quarterly or yearly, was due in this month and has not billed, so its cost may need accruing before the month is closed. The largest usual bill first. |
periodRequired | string | The month, as |
swingsRequired | array of AccountSwingOut | The income-statement accounts whose month, as closing leaves it, is more than 50% and more than 2000 (in the books' currency) away from the average of the 3 months before: the largest change first, each with what moved it. Closing entries are left out. |
ReopenRequest
| Name | Type | Description |
|---|---|---|
reasonRequired | string |
AccountReconciliationOut
| Name | Type | Description |
|---|---|---|
account_idRequired | string | An id that starts with |
codeRequired | string | |
covered_by_account_id | string or null | An id that starts with |
differenceRequired | string or null | |
includes_descendants | boolean | Default false |
is_balancedRequired | boolean | |
ledger_balanceRequired | string or null | |
nameRequired | string | |
reconciled_throughRequired | string (date) or null | |
roleRequired | string or null | |
statement_balanceRequired | string or null |
BlockerOut
| Name | Type | Description |
|---|---|---|
countRequired | integer | |
kindRequired | string | |
severityRequired | string |
ChecklistItemOut
One task as one month's close asks for it.
| Name | Type | Description |
|---|---|---|
assignee_emailRequired | string or null | The owner's address in these books, when there is an owner. |
assignee_idRequired | string or null | An id that starts with |
blockingRequired | boolean | Whether the month's close waits on it. |
close_task_idRequired | string or null | An id that starts with |
depends_on_idsRequired | array of string | The tasks it waits on, by |
detailsRequired | string or null | How to do it, when the task says. |
due_daysRequired | integer or null | The task's due day, in days after each month ends, or null. |
due_onRequired | string (date) or null | The day it falls due for this month, or null for no due day. |
is_overdueRequired | boolean | Not signed off, and its due day has passed. |
noteRequired | string or null | What the person who signed it off wrote beside it: the evidence. |
signed_offRequired | boolean | Whether it is signed off for this month. |
signed_off_atRequired | string (date-time) or null | When it was signed off. |
signed_off_byRequired | string or null | An id that starts with |
signed_off_by_emailRequired | string or null | The address of whoever signed it off, while they are a member of these books. |
task_idRequired | string or null | An id that starts with |
titleRequired | string | The task's title; on a closed month, as it stood when the month closed. |
waits_on_idsRequired | array of string | Of those, the ones not yet signed off this month: until they are, it cannot be. |
CloseRunSummaryOut
One close of one month.
| Name | Type | Description |
|---|---|---|
created_atRequired | string (date-time) | When the run started. |
forcedRequired | boolean | Closed with the explicit override, with blocking tasks still open. |
idRequired | string | The run's id. |
periodRequired | string | The month it closes, like 2026-09. |
reopened_atRequired | string (date-time) or null | When the month was reopened after it. |
signed_off_atRequired | string (date-time) or null | When it was closed. |
signed_off_byRequired | string or null | An id that starts with |
statusRequired | string |
open, closed, reopened |
tasks_doneRequired | integer | How many of its tasks are signed off. |
tasks_totalRequired | integer | How many tasks it asks for. |
through_sequenceRequired | integer or null | Once closed, the posting sequence its figures reflect: every entry up to it is in the close. Null while open. |
versionRequired | integer | Which close of the month this is: 1 the first time, 2 after one reopening, and so on. |
ExceptionItemOut
An exception as the queue lists it: with what it is about, by name.
| Name | Type | Description |
|---|---|---|
amount | string or null | The money at stake: the amount of the transaction it is about. |
ask_reasonRequired | string | Why it needs a person: needs_category, needs_receipt, needs_match, needs_business_intent, needs_approval, data_problem |
assigned_at | string (date-time) or null | |
assigned_to | string or null | An id that starts with |
counterparty_id | string or null | An id that starts with |
counterparty_logo_url | string or null | The logo of whoever it is about: the counterparty it names, the transaction's or the counterparty itself. Null for none, or initials. |
created_atRequired | string (date-time) | |
currency | string or null | That amount's currency. |
detailRequired | object or null | |
escalated_at | string (date-time) or null | When it was last handed between the owner and the reviewer, either way ( |
escalated_by | string or null | An id that starts with |
escalation_note | string or null | What they wrote with it, to the owner or to the reviewer. |
idRequired | string | An id that starts with |
kindRequired | string | |
occurred_on | string (date) or null | The day the transaction it is about happened. Null when it is not about a transaction. |
paid_with | string or null | The name of the bank account or card the transaction came from, as its provider names it. Null when it is not about a transaction, or nothing connected reported it. |
paid_with_account_id | string or null | An id that starts with |
paid_with_mask | string or null | The last digits of that account or card, when its provider gives them. |
recommendation | RecommendationOut or null | What the books would file it as. Null when they have no answer. |
researched_at | string (date-time) or null | When the books last researched it before asking; null until they have. |
resolution_note | string or null | What whoever resolved or dismissed it wrote. |
resolved_at | string (date-time) or null | |
resolved_by | string or null | An id that starts with |
severityRequired | string | |
statusRequired | string | |
subject_idRequired | string | An id. Which resource it names is given by the field beside it. |
subject_label | string or null | The record as a person names it: a transaction's description, an account's code and name. Null for the books as a whole, or a record that is gone. |
subject_typeRequired | string | |
waiting_onRequired | string | Whose answer it waits for: agent, reviewer, owner, third_party |
PeriodCloseOut
| Name | Type | Description |
|---|---|---|
closed_atRequired | string (date-time) | |
closed_byRequired | string or null | An id that starts with |
closing_creditsRequired | string | |
closing_debitsRequired | string | |
forcedRequired | boolean | Closed past blockers, deliberately. |
locked_through_sequenceRequired | integer | The book's posting sequence at this close: the month as closed is every entry up to it. |
reopeningRequired | ReopeningOut or null | What undid this close, if something did. Null for the standing close. |
versionRequired | integer | 1 for the first close, then one more per re-close. |
ClosePreviewEntryOut
An entry the close would post. It has no id or number: it is not in the books until the month is closed.
| Name | Type | Description |
|---|---|---|
amountRequired | string | The total of one side; both are equal. |
descriptionRequired | string | |
entry_dateRequired | string (date) | |
linesRequired | array of ClosePreviewLineOut | Its lines, debits first. |
originsRequired | array of EntryOriginOut | The schedule it is a share of, when it is one; otherwise empty. |
sourceRequired | string | What would post it: |
MissingAccrualOut
A vendor whose bill was due in this month by the rhythm it keeps (monthly, quarterly or yearly) and has not come: a cost the month may need accrued before it is closed (decisions 0149, 0152).
| Name | Type | Description |
|---|---|---|
amountRequired | string | Its usual bill: the median of the bills that set its rhythm, what approving accrues unless another estimate is named. |
counterparty_idRequired | string | The vendor. |
counterparty_nameRequired | string | Its name. |
every_monthsRequired | integer | Months between its bills: 1, 3, 12 (monthly, quarterly, yearly). |
exception_idRequired | string | The Inbox item asking about it. |
logo_url | string or null | Its logo, when it has one; null for initials. |
recommendationRequired | RecommendationOut or null | The expense account, and department, its charges are filed to: where approving accrues it. Null when its charges are not filed yet, so approving names one. |
usual_dayRequired | integer | The day of the month its charge usually lands. |
AccountSwingOut
An income-statement account whose month is far from its usual month.
| Name | Type | Description |
|---|---|---|
account_codeRequired | string | |
account_idRequired | string | An id that starts with |
account_nameRequired | string | |
amountRequired | string | The month's movement, what closing posts included, signed by the account's normal balance: revenue and expense both positive. |
driversRequired | array of SwingDriverOut | What moved it, the largest change first; at most 3. |
usualRequired | string | The average of the 3 months before. |
RecommendationOut
What the books would file an item's transaction as.
| Name | Type | Description |
|---|---|---|
account_codeRequired | string | Its code, such as |
account_idRequired | string | The GL account recommended. |
account_nameRequired | string | Its name. |
confidence | string or null | 0 to 1: the model's confidence, or the share of the payee's earlier filings that went to this account. Null when nothing measures it. |
counterparty_id | string or null | An id that starts with |
counterparty_name | string or null | Their name. |
department_id | string or null | An id that starts with |
department_name | string or null | That department's name. |
evidence | array of EvidenceOut | What the books found when they researched the item: the payee's earlier filings, its default account, rules that nearly matched, the receipt, similar transactions. Empty until it is researched. |
proposal_id | string or null | An id that starts with |
reasoning | string or null | One line on why. |
sourceRequired | string | Where it came from: rule, model, history |
spread | SpreadOut or null | The prepaid spread proposed, when the payment buys more than a month. |
times_filed | integer | How many of the payee's earlier transactions were filed here. |
ReopeningOut
| Name | Type | Description |
|---|---|---|
reasonRequired | string | |
reopened_atRequired | string (date-time) | |
reopened_byRequired | string or null | An id that starts with |
ClosePreviewLineOut
One line of an entry the close would post.
| Name | Type | Description |
|---|---|---|
account_codeRequired | string | |
account_idRequired | string | An id that starts with |
account_nameRequired | string | |
amountRequired | string | |
dimensionsRequired | array of LineDimensionOut | The line's value for each dimension it names, by key. |
directionRequired | string | One of debit, credit |
EntryOriginOut
What an entry was posted from: the step back from the books toward the evidence.
| Name | Type | Description |
|---|---|---|
descriptionRequired | string | |
idRequired | string | The transaction's id, or the schedule's. |
kindRequired | string |
transaction, schedule |
SwingDriverOut
Part of an account's month, by what it came from.
| Name | Type | Description |
|---|---|---|
amountRequired | string | Its part of the month, signed like the account's. |
idRequired | string | The schedule's id, the counterparty's, or the journal source for |
kindRequired | string |
schedule, counterparty, source |
logo_url | string or null | A counterparty's logo, when it has one; null for initials. |
nameRequired | string or null | The schedule's description or the counterparty's name; null for a source. |
usualRequired | string | Its part of the usual month: the average of the months before. |
EvidenceOut
One thing the books knew about a transaction when it was researched.
| Name | Type | Description |
|---|---|---|
account_code | string or null | The account it points to: its code. |
account_name | string or null | That account's name. |
count | integer or null | For |
kindRequired | string | What it is: prior_filings, counterparty_default, rule_near_miss, document, source_record, similar_transaction |
noteRequired | string | The line the model was shown, in English. |
ref | string or null | The record it is about, by kind: a GL account, a rule, a document, a source record or a transaction. |
since | string or null | For |
text | string or null | The words quoted: what a receipt says, the card program's category, the rule's name or the other transaction's description. |
SpreadOut
A prepaid spread: the payment covers this many months from start.
| Name | Type | Description |
|---|---|---|
monthsRequired | integer | How many months the payment covers. |
startRequired | string (date) | The first month it covers (its first day). |
LineDimensionOut
| Name | Type | Description |
|---|---|---|
dimension_idRequired | string | An id that starts with |
dimension_keyRequired | string | The dimension's key, e.g. |
dimension_nameRequired | string | |
value_codeRequired | string | |
value_idRequired | string | An id that starts with |
value_nameRequired | string |