API reference

Documents

The receipts and invoices behind transactions, and which transactions each supports.

GET/v1/documentsList receipts and invoices with what they support
POST/v1/documentsUpload a receipt or invoice
GET/v1/documents/{document_id}Get a receipt or invoice
DELETE/v1/documents/{document_id}Delete an uploaded document
POST/v1/documents/{document_id}/bill_readingRead a document as a vendor's bill, for the bill form
GET/v1/documents/{document_id}/linkGet a short-lived link to a document's file
POST/v1/documents/{document_id}/linksAttach a document to a transaction
DELETE/v1/documents/{document_id}/links/{event_id}Detach a document from a transaction

Guides: Enter and approve vendor bills, Find receipts and invoices

List receipts and invoices with what they support

GET/v1/documents

client.documents.list()

The receipts and invoices behind these books, newest first, each with the transactions it supports.

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.
`matched`Query	boolean or null	True for documents that support a transaction, false for those still waiting for one. Absent is both.
`kind`Query	string or null	Only this kind: one of receipt, invoice.
`billed`Query	boolean or null	True for documents a bill was entered from, false for those no bill names yet: with `kind=invoice`, the vendors' bills still to enter. Absent is both.
`q`Query	string or null	Only documents whose text matches: the description of a transaction they support, or the merchant read off them. Case does not matter.
`counterparty_id`Query	string or null	An id that starts with `party_`.

Response

200DocumentPage

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

Upload a receipt or invoice

POST/v1/documents· Idempotent

client.documents.create()

Keep a receipt or invoice. A PDF or a photo; the same file twice is one document. A receipt is read for its merchant, date, total, currency and tax in the background, and attached to the one transaction those match — or to event_id straight away, when given. An invoice waits under the bills to enter instead.

Response

201DocumentRecordOut

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/documents" \
  -H "Authorization: Bearer $LEDGERIT_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)"

Get a receipt or invoice

GET/v1/documents/{document_id}

client.documents.get()

One receipt or invoice, and the transactions it supports. A document merged into an earlier copy of the same file answers as that copy.

Parameters

Name	Type	Description
`document_id`Path · Required	string	An id that starts with `doc_`.

Response

200DocumentRecordOut

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

Delete an uploaded document

DELETE/v1/documents/{document_id}

client.documents.delete()

Delete a receipt a person uploaded, with what was read off it and its file — the wrong file, or one sent twice. Only one that supports no transaction: detach it first. A document a connection filed comes back with its next sync, so it is detached instead, never deleted. The file is removed in the background, shortly after.

Parameters

Name	Type	Description
`document_id`Path · Required	string	An id that starts with `doc_`.

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

Read a document as a vendor's bill, for the bill form

POST/v1/documents/{document_id}/bill_reading

client.documents.readBill()

Read a document as a vendor's bill, for the bill form: the vendor, their number for it, its date and due date, its total, currency and tax, and its line items, each with how sure the reader was. The vendor's name is matched to a counterparty of these books when exactly one has it. Read once per reader version: asking again returns the same reading. Takes a few seconds the first time. reader_unavailable when no model can be reached; nothing is stored then, so ask again later.

Parameters

Name	Type	Description
`document_id`Path · Required	string	An id that starts with `doc_`.

Response

200BillReadingOut

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/documents/{document_id}/bill_reading" \
  -H "Authorization: Bearer $LEDGERIT_TOKEN"

Get a short-lived link to a document's file

GET/v1/documents/{document_id}/link

client.documents.downloadLink()

A short-lived link to the document's file: our own copy when we hold one, else the provider's link. Open it promptly; it expires.

Parameters

Name	Type	Description
`document_id`Path · Required	string	An id that starts with `doc_`.

Response

200DocumentLink

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/documents/{document_id}/link" \
  -H "Authorization: Bearer $LEDGERIT_TOKEN"

Attach a document to a transaction

POST/v1/documents/{document_id}/links· Idempotent

client.documents.attach()

Attach a document to a transaction as its evidence. Attaching it again changes nothing.

Parameters

Name	Type	Description
`document_id`Path · Required	string	An id that starts with `doc_`.

Request body

LinkIn

Response

201DocumentRecordOut

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

Detach a document from a transaction

DELETE/v1/documents/{document_id}/links/{event_id}

client.documents.detach()

Detach a document from a transaction. The document stays, for anything else it supports.

Parameters

Name	Type	Description
`document_id`Path · Required	string	An id that starts with `doc_`.
`event_id`Path · Required	string	An id that starts with `txn_`.

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/documents/{document_id}/links/{event_id}" \
  -H "Authorization: Bearer $LEDGERIT_TOKEN"

Objects

The objects these operations take and return.

DocumentPage

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

DocumentRecordOut

A receipt or an invoice, and what it supports.

Name	Type	Description
`byte_size`Required	integer or null	The file's size in bytes, once our copy exists.
`content_type`Required	string or null	The file's media type, once known.
`created_at`Required	string (date-time)	When it reached these books.
`extraction`Required	ExtractionOut or null	What was read off it — merchant, date, total, currency and tax — once read.
`id`Required	string	An id that starts with `doc_`.
`kind`Required	string	One of receipt, invoice.
`source`Required	string	The connector it came from, such as `brex`, or `upload`.
`stored`Required	boolean	Whether our own copy exists. Open the file through the app either way.
`transactions`Required	array of SupportedTransactionOut	The transactions it supports, oldest first. Empty while it supports none.

BillReadingOut

What was read off a vendor's bill for the bill form (decision 0160). Data only: a person checks every field before the bill is saved, and nothing read reaches the books on its own. A field read with a confidence under 0.6 is not worth starting from.

Name	Type	Description
`bill_date`Required	ExtractedFieldOut	The bill's date, as YYYY-MM-DD.
`currency`Required	ExtractedFieldOut	The ISO 4217 code of the total.
`due_date`Required	ExtractedFieldOut	When it falls due, as YYYY-MM-DD, when the bill says.
`lines`Required	array of ReadLineOut	One per line item on the bill, in its order, at most 50.
`party_id`Required	string or null	An id that starts with `party_`.
`read`Required	boolean	Whether the document could be read as a bill at all.
`reader_version`Required	string	Which reader read it; the fields are comparable within one version.
`tax`Required	ExtractedFieldOut	The tax included, as a plain number.
`total`Required	ExtractedFieldOut	The total due, tax included, as a plain number.
`vendor`Required	ExtractedFieldOut	Who sent the bill, as printed.
`vendor_number`Required	ExtractedFieldOut	The vendor's own number for the bill.

DocumentLink

Name	Type	Description
`stored`Required	boolean
`url`Required	string

LinkIn

Name	Type	Description
`event_id`Required	string	The transaction the document is evidence for.

ExtractionOut

What the extractor read off the document. Data only: it is matched against transactions and shown, never acted on.

Name	Type	Description
`currency`Required	ExtractedFieldOut or null
`date`Required	ExtractedFieldOut or null
`extractor_version`Required	string
`merchant`Required	ExtractedFieldOut or null
`recorded_at`Required	string (date-time)
`tax`Required	ExtractedFieldOut or null
`total`Required	ExtractedFieldOut or null

SupportedTransactionOut

A transaction a document supports, as much as a list row names.

Name	Type	Description
`account_id`Required	string	The bank or card account it moved on.
`account_name`Required	string
`amount`Required	string	Unsigned; `event_type` says which way the money went.
`counterparty_logo_url`Required	string or null	Their logo, square PNG on our own storage; null for none.
`counterparty_name`Required	string or null	Who the money went to, when a source named them.
`currency`Required	string
`description`Required	string
`event_date`Required	string (date)
`event_type`Required	string	What kind of movement it was, such as `expense` or `income`.
`id`Required	string	The transaction; open it with `GET /transactions/{id}`.

ExtractedFieldOut

Name	Type	Description
`confidence`Required	number	How sure the reader was, from 0 to 1.
`location`Required	string or null	Where on the document it was read.
`value`Required	string or null	What was read, or null when the document does not show it.

ReadLineOut

Name	Type	Description
`amount`Required	string or null	What the line comes to, as a plain number; null when not shown.
`confidence`Required	number	How sure the reader was of the line, from 0 to 1.
`description`Required	string	What was billed on the line, as the bill words it.