API reference

Counterparties

The vendors and customers money moves between.

GET/v1/counterpartiesList the counterparties with their activity
POST/v1/counterpartiesAdd a counterparty
GET/v1/counterparties/{counterparty_id}Get a counterparty
PATCH/v1/counterparties/{counterparty_id}Change a counterparty
DELETE/v1/counterparties/{counterparty_id}Delete a counterparty
PUT/v1/counterparties/{counterparty_id}/logoUpload a counterparty's logo
DELETE/v1/counterparties/{counterparty_id}/logoRemove a counterparty's uploaded logo
POST/v1/counterparties/{counterparty_id}/mergeMerge a counterparty into another
GET/v1/counterparties/{counterparty_id}/monthsGet a counterparty's activity month by month

Guides: Keep track of vendors and customers

List the counterparties with their activity

GET/v1/counterparties

client.counterparties.list()

Everyone money moved to or from, by name, with how many transactions name them and how much went each way. Ones merged into another are left out: they are that other one now.

Parameters

Name	Type	Description
`limit`Query	integer	Page size, 1–200. Default 50
`cursor`Query	string or null	The `next_cursor` of the previous page.
`q`Query	string or null	Only counterparties whose name contains this, ignoring case.
`role`Query	string or null	Only those holding this role: customers, vendors, investors… One of `customer`, `vendor`, `employee`, `investor`, `lender`, `founder`

Response

200CounterpartyPage

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

Add a counterparty

POST/v1/counterparties· Idempotent

client.counterparties.create()

Add a counterparty no feed has named yet.

Refused with counterparty_conflict when one by the same name exists ("Acme, Inc." and "Acme" are the same name); edit that one instead.

Request body

NewCounterparty

Response

201CounterpartyOut

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/counterparties" \
  -H "Authorization: Bearer $LEDGERIT_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"name":"…"}'

Get a counterparty

GET/v1/counterparties/{counterparty_id}

client.counterparties.get()

One counterparty, with their activity in these books. One that was merged answers too, with merged_into_id naming where it went.

Parameters

Name	Type	Description
`counterparty_id`Path · Required	string	An id that starts with `party_`.

Response

200CounterpartyOut

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

Change a counterparty

PATCH/v1/counterparties/{counterparty_id}· Idempotent

client.counterparties.update()

Rename a counterparty, mark them a customer or vendor, or record their terms. A rename keeps the slug, so the next sync still finds them under the name the bank prints.

Parameters

Name	Type	Description
`counterparty_id`Path · Required	string	An id that starts with `party_`.

Request body

CounterpartyChanges

Response

200CounterpartyOut

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/counterparties/{counterparty_id}" \
  -H "Authorization: Bearer $LEDGERIT_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{}'

Delete a counterparty

DELETE/v1/counterparties/{counterparty_id}

client.counterparties.delete()

Remove a counterparty, and any merged into them. Their transactions stay in the books and name nobody; a later sync that sees the same merchant adds them again.

Parameters

Name	Type	Description
`counterparty_id`Path · Required	string	An id that starts with `party_`.

Response

204No content

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 DELETE "https://api.ledgerit.ai/v1/counterparties/{counterparty_id}" \
  -H "Authorization: Bearer $LEDGERIT_TOKEN"

Upload a counterparty's logo

PUT/v1/counterparties/{counterparty_id}/logo· Idempotent

client.counterparties.setLogo()

Upload a logo for a counterparty, replacing any uploaded before. It is shown instead of the one found on their website, in these books only.

The image type is read from the bytes, not from the upload's declared type: PNG, JPEG or WebP, never SVG. It is redrawn as a square PNG of 128 pixels at most. Refused with payload_too_large over 1 MB and unsupported_image for anything else, or an image under 32 pixels. Uploading the same image again changes nothing.

Parameters

Name	Type	Description
`counterparty_id`Path · Required	string	An id that starts with `party_`.

Response

200CounterpartyOut

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/counterparties/{counterparty_id}/logo" \
  -H "Authorization: Bearer $LEDGERIT_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)"

Remove a counterparty's uploaded logo

DELETE/v1/counterparties/{counterparty_id}/logo· Idempotent

client.counterparties.removeLogo()

Remove the logo uploaded for a counterparty. They show the one found on their website again, or their initials while there is none. Removing an upload that is not there succeeds and changes nothing.

Parameters

Name	Type	Description
`counterparty_id`Path · Required	string	An id that starts with `party_`.

Response

200CounterpartyOut

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 DELETE "https://api.ledgerit.ai/v1/counterparties/{counterparty_id}/logo" \
  -H "Authorization: Bearer $LEDGERIT_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)"

Merge a counterparty into another

POST/v1/counterparties/{counterparty_id}/merge· Idempotent

client.counterparties.merge()

Merge a counterparty into another: one company the bank printed two ways. Answers with the one kept.

Its transactions, rules, provider ids and drafts move to the one kept, which becomes a customer or vendor if this one was and takes whatever this one knew that it did not. This one stays as an alias: posted lines keep naming it, the list leaves it out, and the next sync that prints its name files to the one kept. A merge is not undone.

Merging again into the same one answers the same. Refused with counterparty_not_mergeable into itself, into one that was itself merged, or away from one with invoices, bills, payments, credit notes, open items, payment destinations or financing — merge the other way round.

Parameters

Name	Type	Description
`counterparty_id`Path · Required	string	An id that starts with `party_`.

Request body

MergeCounterparty

Response

200CounterpartyOut

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/counterparties/{counterparty_id}/merge" \
  -H "Authorization: Bearer $LEDGERIT_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"into_id":"…"}'

Get a counterparty's activity month by month

GET/v1/counterparties/{counterparty_id}/months

client.counterparties.months()

A counterparty's activity month by month: how many transactions, how much paid to them and how much received. The figures add up to the totals on the counterparty.

Parameters

Name	Type	Description
`counterparty_id`Path · Required	string	An id that starts with `party_`.

Response

200CounterpartyMonthsOut

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/counterparties/{counterparty_id}/months" \
  -H "Authorization: Bearer $LEDGERIT_TOKEN"

Objects

The objects these operations take and return.

CounterpartyPage

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

NewCounterparty

Name	Type	Description
`country`	string or null
`default_account_id`	string or null	An id that starts with `gla_`.
`email`	string or null
`is_customer`	boolean	Default false
`is_vendor`	boolean	Default false
`name`Required	string
`notes`	string or null
`payment_terms_days`	integer or null
`region`	string or null
`tax_classification`	string or null
`w9_received_on`	string (date) or null
`website`	string or null	Their website; their logo is looked for there.

CounterpartyOut

Name	Type	Description
`billing`Required	BillingCadenceOut or null	How often they bill, when their bills (or, with none, their charges) keep a monthly, quarterly or yearly rhythm; null when they keep none.
`categories`Required	array of CounterpartyCategoryOut	Every GL account their transactions are filed to, the most used first. A split transaction counts under none; one still waiting for review is not counted.
`country`Required	string or null
`created_at`Required	string (date-time)
`default_account_id`Required	string or null	An id that starts with `gla_`.
`email`Required	string or null
`first_transaction_on`Required	string (date) or null	The date of the earliest transaction naming them; null with none.
`found_logo_url`Required	string or null	The logo found on their website, whether or not an upload is shown instead: what they show once an uploaded logo is removed. Null for none.
`id`Required	string	An id that starts with `party_`.
`is_customer`Required	boolean
`is_vendor`Required	boolean
`last_transaction_on`Required	string (date) or null
`logo_source`Required	string or null	Where `logo_url` comes from: `uploaded`, a logo a person uploaded for them, which wins; `found`, the icon of their website, found by LedgerIt; null for none. One of `uploaded`, `found`
`logo_url`Required	string or null	Their logo, square PNG; null for none.
`merged_at`Required	string (date-time) or null	When it was merged, or null.
`merged_into_id`Required	string or null	An id that starts with `party_`.
`name`Required	string
`notes`Required	string or null
`payment_terms_days`Required	integer or null
`region`Required	string or null
`roles`Required	array of string	What they are to these books: customer, vendor, employee, investor, lender or founder. `is_customer` and `is_vendor` say the first two. One of `customer`, `vendor`, `employee`, `investor`, `lender`, `founder`
`slug`Required	string
`tax_classification`Required	string or null
`total_in`Required	string
`total_out`Required	string
`transaction_count`Required	integer
`updated_at`Required	string (date-time)
`w9_received_on`Required	string (date) or null
`website`Required	string or null	Their website, as a full URL with its scheme.

CounterpartyChanges

Only the fields sent change. Everything but name and the two roles is cleared by sending null; those three are typed without null and default to None only so that leaving one out means "unchanged".

Name	Type	Description
`country`	string or null
`default_account_id`	string or null	An id that starts with `gla_`.
`email`	string or null
`is_customer`	boolean
`is_vendor`	boolean
`name`	string
`notes`	string or null
`payment_terms_days`	integer or null
`region`	string or null
`tax_classification`	string or null
`w9_received_on`	string (date) or null
`website`	string or null	Their website. Changing it looks for their logo there again.

MergeCounterparty

Name	Type	Description
`into_id`Required	string	The counterparty to merge this one into. It is the one kept.

CounterpartyMonthsOut

Name	Type	Description
`data`Required	array of CounterpartyMonthOut	Every month from their first transaction to their last, oldest first; a month with nothing in it is there with zeros. Counts what `transaction_count`, `total_out` and `total_in` on the counterparty count.

BillingCadenceOut

How often a vendor bills these books, learned from what it billed (decision 0152): its last bills fell exactly this many months apart.

Name	Type	Description
`every_months`Required	integer	Months between its bills: 1, 3, 12 (monthly, quarterly, yearly).
`next_expected_on`Required	string (date)	When its next bill is due. In the past when it is late; the books' daily check asks about a late one so the month's cost can be accrued.
`usual_amount`Required	string	What a bill usually comes to, in the books' currency: the median of the bills that set its rhythm.
`usual_day`Required	integer	The day of the month its bill usually lands.

CounterpartyCategoryOut

A GL account this counterparty's transactions are filed to, and how many.

Name	Type	Description
`account_id`Required	string	The GL account they are filed to.
`transaction_count`Required	integer	Transactions naming them filed to it, counted as `transaction_count` is.

CounterpartyMonthOut

One calendar month of a counterparty's activity.

Name	Type	Description
`month`Required	string (date)	The first day of the month.
`total_in`Required	string	Received from them that month, in the books' currency, as a positive figure.
`total_out`Required	string	Paid to them that month, in the books' currency, as a positive figure.
`transaction_count`Required	integer	Transactions naming them that month.