API reference

Bank accounts and cards

Each bank account and card a connection reads, and the GL account it posts to by date, remapped from a date.

GET/v1/external_accountsList the bank accounts and cards the books read
GET/v1/external_accounts/orderGet the order the Bank accounts page lists banks in
PUT/v1/external_accounts/orderPut the Bank accounts page's banks or accounts in order
GET/v1/external_accounts/{external_account_id}Get a bank account or card
PATCH/v1/external_accounts/{external_account_id}Post a bank account or card to another GL account from a date
PUT/v1/external_accounts/{external_account_id}/visibilityHide a bank account or card on the Bank accounts page, or show it

Guides: See your bank accounts and cards, Connect your banks, cards, payroll and revenue

List the bank accounts and cards the books read

GET/v1/external_accounts

client.externalAccounts.list()

The bank accounts and cards these books' connections read, in the order they were found, each with the GL account it posts to today, the GL accounts it posted to by date, the balance the provider last reported, and the company whose books it feeds.

Parameters

Name	Type	Description
`connection_id`Query	string or null	An id that starts with `conn_`.
`limit`Query	integer	Page size, 1–200. Default 50
`cursor`Query	string or null	The `next_cursor` of the previous page.

Response

200ExternalAccountList

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/external_accounts" \
  -H "Authorization: Bearer $LEDGERIT_TOKEN"

Get the order the Bank accounts page lists banks in

GET/v1/external_accounts/order

client.externalAccounts.getOrder()

The order these books' Bank accounts page lists its banks, and each bank's accounts, in (decision 0179).

Response

200DisplayOrderOut

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/external_accounts/order" \
  -H "Authorization: Bearer $LEDGERIT_TOKEN"

Put the Bank accounts page's banks or accounts in order

PUT/v1/external_accounts/order

client.externalAccounts.setOrder()

Put the banks, one bank's accounts, or both, in a new order on the Bank accounts page. Each list is the whole order of what it covers; a bank or account left out keeps its place after the listed ones. An account list names one bank's accounts only, since a position means something only beside its siblings. Sending the same order again changes nothing, so a retried request is safe.

Request body

DisplayOrderIn

Response

200DisplayOrderOut

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 PUT "https://api.ledgerit.ai/v1/external_accounts/order" \
  -H "Authorization: Bearer $LEDGERIT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'

Get a bank account or card

GET/v1/external_accounts/{external_account_id}

client.externalAccounts.get()

One bank account or card these books' connections read, with the GL accounts it posts to by date.

Parameters

Name	Type	Description
`external_account_id`Path · Required	string	An id that starts with `acct_`.

Response

200SourceAccountOut

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/external_accounts/{external_account_id}" \
  -H "Authorization: Bearer $LEDGERIT_TOKEN"

Post a bank account or card to another GL account from a date

PATCH/v1/external_accounts/{external_account_id}· Idempotent

client.externalAccounts.remap()

Post a bank account or card to another GL account, from a date or for good (decision 0088).

With effective_from, a row dated that day or later lands in the new GL account and an earlier one, arriving late, keeps to the account mapped then. Without it, everything from the next sync on lands in the new one. What is already in the books stays where it was posted: to move it, reverse or refile those entries. A remap never reaches into a locked month: a date in one, or replacing a mapping that starts in one, is refused with period_closed (decision 0096). A bank account posts to an asset account and a card to a liability account; the other side is refused, because it would invert the account. Naming the mapping it already has changes nothing, so a retried request is safe.

Parameters

Name	Type	Description
`external_account_id`Path · Required	string	An id that starts with `acct_`.

Request body

SourceAccountChange

Response

200SourceAccountOut

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 PATCH "https://api.ledgerit.ai/v1/external_accounts/{external_account_id}" \
  -H "Authorization: Bearer $LEDGERIT_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"account_id":"…"}'

Hide a bank account or card on the Bank accounts page, or show it

PUT/v1/external_accounts/{external_account_id}/visibility

client.externalAccounts.setVisibility()

Hide a bank account or card on the Bank accounts page, or show it again (decision 0179). Display only: a hidden account still syncs, posts and counts in every balance and report. Naming the state it is already in changes nothing, so a retried request is safe.

Parameters

Name	Type	Description
`external_account_id`Path · Required	string	An id that starts with `acct_`.

Request body

ExternalAccountVisibility

Response

200SourceAccountOut

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 PUT "https://api.ledgerit.ai/v1/external_accounts/{external_account_id}/visibility" \
  -H "Authorization: Bearer $LEDGERIT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"hidden":false}'

Objects

The objects these operations take and return.

ExternalAccountList

A page of the books' bank accounts and cards.

Name	Type	Description
`data`Required	array of SourceAccountOut
`has_more`Required	boolean
`next_cursor`Required	string or null

DisplayOrderOut

The order the books' Bank accounts page shows banks and accounts in.

Only what was placed is listed; anything else follows, in the order it was found. Accounts compare only within their own bank.

Name	Type	Description
`connection_ids`Required	array of string	The placed banks (connections), first to last.
`external_account_ids`Required	array of string	The placed accounts, first to last within each bank.

DisplayOrderIn

A new order for the banks on the Bank accounts page, for one bank's accounts, or both. Each list is the whole order of what it covers, first to last; either may be left out.

Name	Type	Description
`connection_ids`	array of string or null	Every bank (connection) in its new order.
`external_account_ids`	array of string or null	One bank's accounts in their new order. They must all come from one connection.

SourceAccountOut

One account a connection holds at its provider.

Name	Type	Description
`account_code`Required	string or null
`account_id`Required	string or null	An id that starts with `gla_`.
`account_name`Required	string or null
`connection_id`Required	string	The connection that reads it: its bank or card program.
`connection_label`Required	string or null	What tells two connections to one provider apart; for Plaid, the bank's name.
`currency`Required	string
`entity_id`Required	string	The company whose books it feeds.
`entity_name`Required	string
`gl_mappings`Required	array of GlMappingOut	Every GL account it has posted to and when, oldest first (decision 0088): a row posts to the one mapped on its own date. Empty if it was never mapped.
`hidden`Required	boolean	Folded away on the Bank accounts page (decision 0179). Display only: it still syncs and posts.
`id`Required	string	An id that starts with `acct_`.
`is_active`Required	boolean	False once the provider stops reporting it.
`kind`Required	string	`depository` (money held) or `credit` (a card: money owed).
`last_balance`Required	string or null	What the provider last said it holds.
`last_balance_at`Required	string (date-time) or null
`mask`Required	string or null	Its last digits, as the provider prints them.
`name`Required	string	What the provider calls it.
`ownership_status`Required	string	`pending` while it waits for a person to say which of the connection's companies it belongs to (a login that holds several); nothing is read from it until then. One of `confirmed`, `pending`
`provider`Required	string	What the connection connects: `mercury`, `brex`, `plaid`, …

SourceAccountChange

Name	Type	Description
`account_id`Required	string	The GL account what this account sends should post to: an open, postable asset account for a bank account, a liability account for a card.
`effective_from`	string (date) or null	Rows dated this day or later post to the new GL account; earlier ones keep to the one mapped before. Left out, every row from now on does, whatever its date.

ExternalAccountVisibility

Name	Type	Description
`hidden`Required	boolean	True folds the account away under its bank's hidden row on the Bank accounts page; false brings it back. Display only: it still syncs, posts and counts in every report.

GlMappingOut

Which GL account the account posted to over a span of dates.

Name	Type	Description
`account_code`Required	string or null
`account_id`Required	string	An id that starts with `gla_`.
`account_name`Required	string or null
`valid_from`Required	string (date) or null	The first day; null for the beginning of its history.
`valid_to`Required	string (date) or null	The day after the last; null while it still applies.