API reference

Periods

The months of the books: soft-close, close and reopen them.

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

NameTypeDescription
limitQueryinteger

Page size, 1–200.

Default 50
cursorQuerystring or null

The next_cursor of the previous page.

statusQuerystring or null

Only open months, or only closed ones.

One of 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
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

NameTypeDescription
keyPath · Requiredstring

Response

200CloseStatusOut

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

NameTypeDescription
keyPath · Requiredstring

Request body

CloseRequest

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

NameTypeDescription
keyPath · Requiredstring

Response

200PeriodCloseList

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

NameTypeDescription
keyPath · Requiredstring

Response

200ClosePreviewOut

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

NameTypeDescription
keyPath · Requiredstring

Request body

ReopenRequest

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

NameTypeDescription
keyPath · Requiredstring

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

NameTypeDescription
dataRequiredarray of PeriodOut
has_moreRequiredboolean
next_cursorRequiredstring or null

CloseStatusOut

NameTypeDescription
accountsRequiredarray of AccountReconciliationOut
blockersRequiredarray of BlockerOut
can_closeRequiredboolean
checklistRequiredarray of ChecklistItemOut
close_runRequiredCloseRunSummaryOut 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_yearRequiredboolean

Whether the month ends a fiscal year, so closing it also carries the year's result into retained earnings.

currencyRequiredstring
open_exceptionsRequiredarray of ExceptionItemOut
periodRequiredPeriodOut
trial_balance_balancedRequiredboolean
trial_balance_differenceRequiredstring
unreviewed_transactionsRequiredinteger

CloseRequest

NameTypeDescription
forcebooleanDefault false

PeriodOut

NameTypeDescription
close_versioninteger

How many times the month has been closed; each close is kept (GET /periods/{key}/closes).

Default 0
closed_atRequiredstring (date-time) or null
closing_creditsRequiredstring or null
closing_debitsRequiredstring or null
ends_onRequiredstring (date)
fiscal_yearRequiredinteger

The fiscal year the month is in, named for the calendar year it ends in.

keyRequiredstring
locked_through_sequenceinteger or null

While closed: the book's posting sequence at the close. The month's figures are every entry up to it.

soft_closed_atstring (date-time) or null

When the month was soft-closed; null unless it is.

starts_onRequiredstring (date)
statusRequiredstringOne of open, soft_closed, locked

PeriodCloseList

NameTypeDescription
dataRequiredarray of PeriodCloseOut

ClosePreviewOut

NameTypeDescription
currencyRequiredstring

The books' currency, which every amount is in.

entriesRequiredarray 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_accrualsRequiredarray 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.

periodRequiredstring

The month, as YYYY-MM.

swingsRequiredarray 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

NameTypeDescription
reasonRequiredstring

AccountReconciliationOut

NameTypeDescription
account_idRequiredstring

An id that starts with gla_.

codeRequiredstring
covered_by_account_idstring or null

An id that starts with gla_.

differenceRequiredstring or null
includes_descendantsbooleanDefault false
is_balancedRequiredboolean
ledger_balanceRequiredstring or null
nameRequiredstring
reconciled_throughRequiredstring (date) or null
roleRequiredstring or null
statement_balanceRequiredstring or null

BlockerOut

NameTypeDescription
countRequiredinteger
kindRequiredstring
severityRequiredstring

ChecklistItemOut

One task as one month's close asks for it.

NameTypeDescription
assignee_emailRequiredstring or null

The owner's address in these books, when there is an owner.

assignee_idRequiredstring or null

An id that starts with usr_.

blockingRequiredboolean

Whether the month's close waits on it.

close_task_idRequiredstring or null

An id that starts with run_task_.

depends_on_idsRequiredarray of string

The tasks it waits on, by task_id.

detailsRequiredstring or null

How to do it, when the task says.

due_daysRequiredinteger or null

The task's due day, in days after each month ends, or null.

due_onRequiredstring (date) or null

The day it falls due for this month, or null for no due day.

is_overdueRequiredboolean

Not signed off, and its due day has passed.

noteRequiredstring or null

What the person who signed it off wrote beside it: the evidence.

signed_offRequiredboolean

Whether it is signed off for this month.

signed_off_atRequiredstring (date-time) or null

When it was signed off.

signed_off_byRequiredstring or null

An id that starts with usr_.

signed_off_by_emailRequiredstring or null

The address of whoever signed it off, while they are a member of these books.

task_idRequiredstring or null

An id that starts with task_.

titleRequiredstring

The task's title; on a closed month, as it stood when the month closed.

waits_on_idsRequiredarray of string

Of those, the ones not yet signed off this month: until they are, it cannot be.

CloseRunSummaryOut

One close of one month.

NameTypeDescription
created_atRequiredstring (date-time)

When the run started.

forcedRequiredboolean

Closed with the explicit override, with blocking tasks still open.

idRequiredstring

The run's id.

periodRequiredstring

The month it closes, like 2026-09.

reopened_atRequiredstring (date-time) or null

When the month was reopened after it.

signed_off_atRequiredstring (date-time) or null

When it was closed.

signed_off_byRequiredstring or null

An id that starts with usr_.

statusRequiredstring

open while the month's close is worked, closed once the month is locked with it, reopened once the month was reopened after it.

One of open, closed, reopened
tasks_doneRequiredinteger

How many of its tasks are signed off.

tasks_totalRequiredinteger

How many tasks it asks for.

through_sequenceRequiredinteger or null

Once closed, the posting sequence its figures reflect: every entry up to it is in the close. Null while open.

versionRequiredinteger

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.

NameTypeDescription
amountstring or null

The money at stake: the amount of the transaction it is about.

ask_reasonRequiredstring

Why it needs a person: needs_category, needs_receipt, needs_match, needs_business_intent, needs_approval or data_problem.

One of needs_category, needs_receipt, needs_match, needs_business_intent, needs_approval, data_problem
assigned_atstring (date-time) or null
assigned_tostring or null

An id that starts with usr_.

counterparty_idstring or null

An id that starts with party_.

counterparty_logo_urlstring 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_atRequiredstring (date-time)
currencystring or null

That amount's currency.

detailRequiredobject or null
escalated_atstring (date-time) or null

When it was last handed between the owner and the reviewer, either way (waiting_on says which); null if it never was.

escalated_bystring or null

An id that starts with usr_.

escalation_notestring or null

What they wrote with it, to the owner or to the reviewer.

idRequiredstring

An id that starts with exc_.

kindRequiredstring
occurred_onstring (date) or null

The day the transaction it is about happened. Null when it is not about a transaction.

paid_withstring 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_idstring or null

An id that starts with gla_.

paid_with_maskstring or null

The last digits of that account or card, when its provider gives them.

recommendationRecommendationOut or null

What the books would file it as. Null when they have no answer.

researched_atstring (date-time) or null

When the books last researched it before asking; null until they have.

resolution_notestring or null

What whoever resolved or dismissed it wrote.

resolved_atstring (date-time) or null
resolved_bystring or null

An id that starts with usr_.

severityRequiredstring
statusRequiredstring
subject_idRequiredstring

An id. Which resource it names is given by the field beside it.

subject_labelstring 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_typeRequiredstring
waiting_onRequiredstring

Whose answer it waits for: agent, reviewer (the books' accountant or firm), owner (the business) or third_party.

One of agent, reviewer, owner, third_party

PeriodCloseOut

NameTypeDescription
closed_atRequiredstring (date-time)
closed_byRequiredstring or null

An id that starts with usr_.

closing_creditsRequiredstring
closing_debitsRequiredstring
forcedRequiredboolean

Closed past blockers, deliberately.

locked_through_sequenceRequiredinteger

The book's posting sequence at this close: the month as closed is every entry up to it.

reopeningRequiredReopeningOut or null

What undid this close, if something did. Null for the standing close.

versionRequiredinteger

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.

NameTypeDescription
amountRequiredstring

The total of one side; both are equal.

descriptionRequiredstring
entry_dateRequiredstring (date)
linesRequiredarray of ClosePreviewLineOut

Its lines, debits first.

originsRequiredarray of EntryOriginOut

The schedule it is a share of, when it is one; otherwise empty.

sourceRequiredstring

What would post it: schedule (a recognition schedule's share, an accrual or its release, depreciation), financing (interest on notes and venture debt, stock-based compensation) or closing (the year-end entry).

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).

NameTypeDescription
amountRequiredstring

Its usual bill: the median of the bills that set its rhythm, what approving accrues unless another estimate is named.

counterparty_idRequiredstring

The vendor.

counterparty_nameRequiredstring

Its name.

every_monthsRequiredinteger

Months between its bills: 1, 3, 12 (monthly, quarterly, yearly).

exception_idRequiredstring

The Inbox item asking about it. POST /exceptions/{id}/approve accrues it; dismissing it says the month owes nothing.

logo_urlstring or null

Its logo, when it has one; null for initials.

recommendationRequiredRecommendationOut 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_dayRequiredinteger

The day of the month its charge usually lands.

AccountSwingOut

An income-statement account whose month is far from its usual month.

NameTypeDescription
account_codeRequiredstring
account_idRequiredstring

An id that starts with gla_.

account_nameRequiredstring
amountRequiredstring

The month's movement, what closing posts included, signed by the account's normal balance: revenue and expense both positive.

driversRequiredarray of SwingDriverOut

What moved it, the largest change first; at most 3.

usualRequiredstring

The average of the 3 months before.

RecommendationOut

What the books would file an item's transaction as.

NameTypeDescription
account_codeRequiredstring

Its code, such as 6100.

account_idRequiredstring

The GL account recommended.

account_nameRequiredstring

Its name.

confidencestring 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_idstring or null

An id that starts with party_.

counterparty_namestring or null

Their name.

department_idstring or null

An id that starts with dimv_.

department_namestring or null

That department's name.

evidencearray 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_idstring or null

An id that starts with prop_.

reasoningstring or null

One line on why.

sourceRequiredstring

Where it came from: rule, model, or history (the payee's earlier filings, or its default account).

One of rule, model, history
spreadSpreadOut or null

The prepaid spread proposed, when the payment buys more than a month.

times_filedinteger

How many of the payee's earlier transactions were filed here.

Default 0

ReopeningOut

NameTypeDescription
reasonRequiredstring
reopened_atRequiredstring (date-time)
reopened_byRequiredstring or null

An id that starts with usr_.

ClosePreviewLineOut

One line of an entry the close would post.

NameTypeDescription
account_codeRequiredstring
account_idRequiredstring

An id that starts with gla_.

account_nameRequiredstring
amountRequiredstring
dimensionsRequiredarray of LineDimensionOut

The line's value for each dimension it names, by key.

directionRequiredstringOne of debit, credit

EntryOriginOut

What an entry was posted from: the step back from the books toward the evidence.

NameTypeDescription
descriptionRequiredstring
idRequiredstring

The transaction's id, or the schedule's.

kindRequiredstring

transaction: a bank, card or processor movement that was filed. schedule: one period of a recognition schedule.

One of transaction, schedule

SwingDriverOut

Part of an account's month, by what it came from.

NameTypeDescription
amountRequiredstring

Its part of the month, signed like the account's.

idRequiredstring

The schedule's id, the counterparty's, or the journal source for source.

kindRequiredstring

schedule: the shares of one recognition schedule (a spread, an accrual, depreciation). counterparty: what was posted for one vendor or customer. source: entries with neither, by what posted them (manual, financing, …).

One of schedule, counterparty, source
logo_urlstring or null

A counterparty's logo, when it has one; null for initials.

nameRequiredstring or null

The schedule's description or the counterparty's name; null for a source.

usualRequiredstring

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.

NameTypeDescription
account_codestring or null

The account it points to: its code.

account_namestring or null

That account's name.

countinteger or null

For prior_filings: how many times.

kindRequiredstring

What it is: prior_filings (the payee filed here before), counterparty_default (the account a person set for the payee), rule_near_miss (a rule whose pattern matched but whose conditions did not), document (an attached receipt or invoice), source_record (what the card program said) or similar_transaction (another payee's transaction like it).

One of prior_filings, counterparty_default, rule_near_miss, document, source_record, similar_transaction
noteRequiredstring

The line the model was shown, in English.

refstring or null

The record it is about, by kind: a GL account, a rule, a document, a source record or a transaction.

sincestring or null

For prior_filings, the first such filing; for similar_transaction, its date. ISO 8601.

textstring 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.

NameTypeDescription
monthsRequiredinteger

How many months the payment covers.

startRequiredstring (date)

The first month it covers (its first day).

LineDimensionOut

NameTypeDescription
dimension_idRequiredstring

An id that starts with dim_.

dimension_keyRequiredstring

The dimension's key, e.g. department.

dimension_nameRequiredstring
value_codeRequiredstring
value_idRequiredstring

An id that starts with dimv_.

value_nameRequiredstring