MCP tool reference

Every tool that an Oscar client can get over MCP. The server lists to each caller only the tools that its role, its scopes and the client capabilities of the company allow.

View as Markdown

Alerts

list_alerts

List alerts
ReadPermissionbooks.read

What a person of the company must act on, with the last day to act: a VAT registration, a KMD or TSD deadline, a sales invoice to issue, an exchange rate that was refused or corrected, an entry to re-rate.

The alerts of the company, newest first.

A list answers {items, next_cursor}; pass next_cursor back as cursor for the next page.

company_idstringRequired
The id of the company, from list_companies.
cursorstring
The pagination cursor value.
kind"depreciation_blocked" | "ecb_rate_corrected" | "ecb_rate_refused" | "fx_rate_early" | "invoice_issue_due" | "kmd_due" | "market_rate_refused" | "tsd_due" | "vat_limited_registration_due" | "vat_registration_due" | "vat_registration_near"
Only this kind.
limitinteger
Number of results to return per page.
state"dismissed" | "open" | "resolved"
Only this state.
Arguments
ArgumentTypeRequiredDescription
company_idstringYesThe id of the company, from list_companies.
cursorstringNoThe pagination cursor value.
kind"depreciation_blocked" | "ecb_rate_corrected" | "ecb_rate_refused" | "fx_rate_early" | "invoice_issue_due" | "kmd_due" | "market_rate_refused" | "tsd_due" | "vat_limited_registration_due" | "vat_registration_due" | "vat_registration_near"NoOnly this kind.
limitintegerNoNumber of results to return per page.
state"dismissed" | "open" | "resolved"NoOnly this state.

Allocations

allocate

Allocate an open item
WritePermissionallocations.write

A discount, a write-off or a rounding over 100 minor units (adjustment_kind), two different amounts in one foreign currency, or an FX difference over a tenth of the base value is a judgement of a person: propose it with propose_judgement.

Runs the core command allocate. Permission: allocations.write.

Send an idempotency_key and reuse it when you retry: the same key and the same arguments return the first outcome with replayed=true instead of running the command twice.

If the answer is the error human_actor_required, a person must decide: call propose_judgement with the same command and its full payload.

company_idstringRequired
The id of the company, from list_companies.
kind"payment" | "refund" | "credit_offset" | "prepayment_apply"
Default `payment`. * `payment` - payment * `refund` - refund * `credit_offset` - credit_offset * `prepayment_apply` - prepayment_apply
item_line_idstringRequired
counter_line_idstringRequired
item_minorintegerRequired
counter_minorinteger | null
rate_source"statement" | "rate_table" | "manual" | "same" | null
adjustment_kind"none" | "discount" | "writeoff" | "rounding"
Default `none`. * `none` - none * `discount` - discount * `writeoff` - writeoff * `rounding` - rounding
adjustment_base_minorinteger | null
effective_datestring (date)Required
origin"human" | "matcher" | "import" | "migration"
Default `human`. * `human` - human * `matcher` - matcher * `import` - import * `migration` - migration
confidencestring (decimal) | null | string
notestring | null
idempotency_keystring
Optional. A key of your choice, 1 to 255 printable ASCII characters. The same key with the same arguments replays the first outcome.
Arguments
ArgumentTypeRequiredDescription
company_idstringYesThe id of the company, from list_companies.
kind"payment" | "refund" | "credit_offset" | "prepayment_apply"NoDefault `payment`. * `payment` - payment * `refund` - refund * `credit_offset` - credit_offset * `prepayment_apply` - prepayment_apply
item_line_idstringYes
counter_line_idstringYes
item_minorintegerYes
counter_minorinteger | nullNo
rate_source"statement" | "rate_table" | "manual" | "same" | nullNo
adjustment_kind"none" | "discount" | "writeoff" | "rounding"NoDefault `none`. * `none` - none * `discount` - discount * `writeoff` - writeoff * `rounding` - rounding
adjustment_base_minorinteger | nullNo
effective_datestring (date)Yes
origin"human" | "matcher" | "import" | "migration"NoDefault `human`. * `human` - human * `matcher` - matcher * `import` - import * `migration` - migration
confidencestring (decimal) | null | stringNo
notestring | nullNo
idempotency_keystringNoOptional. A key of your choice, 1 to 255 printable ASCII characters. The same key with the same arguments replays the first outcome.

get_settlement

Get the settlement of invoices
ReadPermissionbooks.read

How far each invoice is settled, or one invoice with invoice_id.

company_idstringRequired
The id of the company, from list_companies.
invoice_idstring
The settlement of this invoice only.
Arguments
ArgumentTypeRequiredDescription
company_idstringYesThe id of the company, from list_companies.
invoice_idstringNoThe settlement of this invoice only.

unallocate

Reverse an allocation
WritePermissionallocations.write

Runs the core command unallocate. Permission: allocations.write. The path carries allocation_id.

Send an idempotency_key and reuse it when you retry: the same key and the same arguments return the first outcome with replayed=true instead of running the command twice.

If the answer is the error human_actor_required, a person must decide: call propose_judgement with the same command and its full payload.

allocation_idstringRequired
A core id (ULID).
company_idstringRequired
The id of the company, from list_companies.
reasonstring | null
idempotency_keystring
Optional. A key of your choice, 1 to 255 printable ASCII characters. The same key with the same arguments replays the first outcome.
Arguments
ArgumentTypeRequiredDescription
allocation_idstringYesA core id (ULID).
company_idstringYesThe id of the company, from list_companies.
reasonstring | nullNo
idempotency_keystringNoOptional. A key of your choice, 1 to 255 printable ASCII characters. The same key with the same arguments replays the first outcome.

Bank

apply_money_in_rules

Apply the money-in rules
WritePermissionbank.classify

Books the card charges and refunds of a Stripe feed in a date range that no rule explained yet, with the rules in force (mode unclassified). Mode reclassify redoes receipts after a rule changed; it is a judgement of a person, so propose it with propose_judgement and a reason.

Runs the core command apply_money_in_rules. Permission: bank.classify.

Send an idempotency_key and reuse it when you retry: the same key and the same arguments return the first outcome with replayed=true instead of running the command twice.

If the answer is the error human_actor_required, a person must decide: call propose_judgement with the same command and its full payload.

company_idstringRequired
The id of the company, from list_companies.
bank_account_idstringRequired
tostring (date)Required
The last booking date, inclusive.
mode"unclassified" | "reclassify"Required
* `unclassified` - unclassified * `reclassify` - reclassify
reasonstring | null
fromstring (date)Required
The first booking date, inclusive.
idempotency_keystring
Optional. A key of your choice, 1 to 255 printable ASCII characters. The same key with the same arguments replays the first outcome.
Arguments
ArgumentTypeRequiredDescription
company_idstringYesThe id of the company, from list_companies.
bank_account_idstringYes
tostring (date)YesThe last booking date, inclusive.
mode"unclassified" | "reclassify"Yes* `unclassified` - unclassified * `reclassify` - reclassify
reasonstring | nullNo
fromstring (date)YesThe first booking date, inclusive.
idempotency_keystringNoOptional. A key of your choice, 1 to 255 printable ASCII characters. The same key with the same arguments replays the first outcome.

get_bank_transaction

Get a bank transaction
ReadPermissionbooks.read

One bank transaction with its source row, entries, allocations, the judgement on it, and its files.

bank_transaction_idstringRequired
The core ULID of the object, 26 characters.
company_idstringRequired
The id of the company, from list_companies.
Arguments
ArgumentTypeRequiredDescription
bank_transaction_idstringYesThe core ULID of the object, 26 characters.
company_idstringYesThe id of the company, from list_companies.

list_bank_accounts

List bank accounts
ReadPermissionbooks.read

The bank feeds with their ledger account, transaction count and ledger balance. Ordered by label.

A list answers {items, next_cursor}; pass next_cursor back as cursor for the next page.

company_idstringRequired
The id of the company, from list_companies.
activeboolean | null
Active (true) or inactive (false) bank accounts only.
cursorstring
The `next_cursor` of the previous page. Omit it for the first page.
limitinteger
The page size, 1 to 200. Default 50.
Arguments
ArgumentTypeRequiredDescription
company_idstringYesThe id of the company, from list_companies.
activeboolean | nullNoActive (true) or inactive (false) bank accounts only.
cursorstringNoThe `next_cursor` of the previous page. Omit it for the first page.
limitintegerNoThe page size, 1 to 200. Default 50.

list_bank_transactions

List bank transactions
ReadPermissionbooks.read

The bank transactions with their settlement status, derived on read. Ordered by booking date.

has_document and file_ids name the uploaded files that explain a transaction (an upload with bank_transaction_id). to_explain=true lists the payments to explain: money out still open that no file explains.

A list answers {items, next_cursor}; pass next_cursor back as cursor for the next page.

company_idstringRequired
The id of the company, from list_companies.
bank_account_idstring
Transactions of this bank account only.
cursorstring
The `next_cursor` of the previous page. Omit it for the first page.
date_fromstring (date)
The earliest booking date, inclusive.
date_tostring (date)
The latest booking date, inclusive.
direction"in" | "out"
Money in or money out only. * `in` - in * `out` - out
has_documentboolean | null
Only transactions an uploaded file explains (true) or that none explains (false).
limitinteger
The page size, 1 to 200. Default 50.
ordering"booking_date" | "-booking_date" | "amount" | "-amount" | "counterparty" | "-counterparty"
`booking_date` (the default) is oldest first, `-booking_date` newest first. `amount` orders by the amount that moved (the absolute `total_minor`), `counterparty` by the payee (`party_name`, else `counterparty_name`) in any case. A leading `-` is descending. The id breaks ties. * `booking_date` - booking_date * `-booking_date` - -booking_date * `amount` - amount * `-amount` - -amount * `counterparty` - counterparty * `-counterparty` - -counterparty
party_idstring
Transactions of this party only.
qstring
Keywords: the transactions whose payee (`party_name`, `counterparty_name`) or details (`description`, `reference`) contain this text, in any case. Trimmed; empty is no filter.
statement_idstring
Transactions of this statement only.
status"unmatched" | "part_matched" | "matched" | "exempted" | "classified" | "transfer_matched" | "transfer_unmatched" | "posted" | "open"
Transactions with this status; `open` is `unmatched` and `part_matched`. * `unmatched` - unmatched * `part_matched` - part_matched * `matched` - matched * `exempted` - exempted * `classified` - classified * `transfer_matched` - transfer_matched * `transfer_unmatched` - transfer_unmatched * `posted` - posted * `open` - open
to_explainboolean | null
The payments to explain (true): money out still open (`status` `open`) that no uploaded file explains. Excludes `status`, `direction` and `has_document`.
Arguments
ArgumentTypeRequiredDescription
company_idstringYesThe id of the company, from list_companies.
bank_account_idstringNoTransactions of this bank account only.
cursorstringNoThe `next_cursor` of the previous page. Omit it for the first page.
date_fromstring (date)NoThe earliest booking date, inclusive.
date_tostring (date)NoThe latest booking date, inclusive.
direction"in" | "out"NoMoney in or money out only. * `in` - in * `out` - out
has_documentboolean | nullNoOnly transactions an uploaded file explains (true) or that none explains (false).
limitintegerNoThe page size, 1 to 200. Default 50.
ordering"booking_date" | "-booking_date" | "amount" | "-amount" | "counterparty" | "-counterparty"No`booking_date` (the default) is oldest first, `-booking_date` newest first. `amount` orders by the amount that moved (the absolute `total_minor`), `counterparty` by the payee (`party_name`, else `counterparty_name`) in any case. A leading `-` is descending. The id breaks ties. * `booking_date` - booking_date * `-booking_date` - -booking_date * `amount` - amount * `-amount` - -amount * `counterparty` - counterparty * `-counterparty` - -counterparty
party_idstringNoTransactions of this party only.
qstringNoKeywords: the transactions whose payee (`party_name`, `counterparty_name`) or details (`description`, `reference`) contain this text, in any case. Trimmed; empty is no filter.
statement_idstringNoTransactions of this statement only.
status"unmatched" | "part_matched" | "matched" | "exempted" | "classified" | "transfer_matched" | "transfer_unmatched" | "posted" | "open"NoTransactions with this status; `open` is `unmatched` and `part_matched`. * `unmatched` - unmatched * `part_matched` - part_matched * `matched` - matched * `exempted` - exempted * `classified` - classified * `transfer_matched` - transfer_matched * `transfer_unmatched` - transfer_unmatched * `posted` - posted * `open` - open
to_explainboolean | nullNoThe payments to explain (true): money out still open (`status` `open`) that no uploaded file explains. Excludes `status`, `direction` and `has_document`.

list_money_in_rules

List the money-in rules of a feed
ReadPermissionbooks.read

The rules that turn the card charges of a Stripe feed into receipts. A person adds, changes, reorders or removes a rule: propose set_money_in_rule, reorder_money_in_rules or remove_money_in_rule with propose_judgement.

The standing money-in rules of a payment provider feed, with the version in force on as_of.

The active rules come first, in the order the books evaluate them on a charge, then the removed ones. Each rule carries every version. A rule is written with POST money-in-rules (set_money_in_rule, a person with bank.classify).

company_idstringRequired
The id of the company, from list_companies.
as_ofstring (date)
The day of `in_force` and of the order. Default: today.
bank_account_idstringRequired
A payment provider feed (provider `stripe`).
Arguments
ArgumentTypeRequiredDescription
company_idstringYesThe id of the company, from list_companies.
as_ofstring (date)NoThe day of `in_force` and of the order. Default: today.
bank_account_idstringYesA payment provider feed (provider `stripe`).

match_transfer

Match a transfer
WritePermissionbank.classify

Runs the core command match_transfer. Permission: bank.classify.

Send an idempotency_key and reuse it when you retry: the same key and the same arguments return the first outcome with replayed=true instead of running the command twice.

If the answer is the error human_actor_required, a person must decide: call propose_judgement with the same command and its full payload.

company_idstringRequired
The id of the company, from list_companies.
out_transaction_idstringRequired
in_transaction_idstringRequired
notestring | null
idempotency_keystring
Optional. A key of your choice, 1 to 255 printable ASCII characters. The same key with the same arguments replays the first outcome.
Arguments
ArgumentTypeRequiredDescription
company_idstringYesThe id of the company, from list_companies.
out_transaction_idstringYes
in_transaction_idstringYes
notestring | nullNo
idempotency_keystringNoOptional. A key of your choice, 1 to 255 printable ASCII characters. The same key with the same arguments replays the first outcome.

set_transaction_party

Set the party of a bank transaction
WritePermissionbank.classify

Runs the core command set_transaction_party. Permission: bank.classify. The path carries bank_transaction_id.

Send an idempotency_key and reuse it when you retry: the same key and the same arguments return the first outcome with replayed=true instead of running the command twice.

If the answer is the error human_actor_required, a person must decide: call propose_judgement with the same command and its full payload.

bank_transaction_idstringRequired
A core id (ULID).
company_idstringRequired
The id of the company, from list_companies.
party_idstring | null
sourcestringRequired
idempotency_keystring
Optional. A key of your choice, 1 to 255 printable ASCII characters. The same key with the same arguments replays the first outcome.
Arguments
ArgumentTypeRequiredDescription
bank_transaction_idstringYesA core id (ULID).
company_idstringYesThe id of the company, from list_companies.
party_idstring | nullNo
sourcestringYes
idempotency_keystringNoOptional. A key of your choice, 1 to 255 printable ASCII characters. The same key with the same arguments replays the first outcome.

Companies

get_company

Get a company
ReadPermissionorganization.read

One company: name, legal data and state.

Return the company.

company_idstringRequired
The id of the company, from list_companies.
Arguments
ArgumentTypeRequiredDescription
company_idstringYesThe id of the company, from list_companies.

list_companies

List companies
ReadPermissionorganization.read

The companies of the organization this connection is bound to. Start here: every other tool takes the company_id of one of them. Only a company in state ready has books.

One page of the companies, newest first.

A list answers {items, next_cursor}; pass next_cursor back as cursor for the next page.

cursorstring
The pagination cursor value.
limitinteger
Number of results to return per page.
Arguments
ArgumentTypeRequiredDescription
cursorstringNoThe pagination cursor value.
limitintegerNoNumber of results to return per page.

Dividends

get_dividend_report

Get the dividends of a payment month
ReadPermissionbooks.read

The dividends paid in one month: the data of TSD annex 7 and form INF 1.

The dividends paid in a month: the data of TSD annex 7 and form INF 1.

A dividend is booked at its declaration, but taxed in the month of its payment. The view reads the payments of the month (the allocations that settle a recipient's dividend payable) and gives annex 7 part I (code 7008, the taxable dividends; code 7217, the income tax at 22/78; code 7200), part II (the balance of exempt dividends received, code 7310) and one INF 1 line for each recipient paid. findings names what a person should check. A period that is not one calendar month is 400. The TSD and INF 1 files are made elsewhere.

company_idstringRequired
The id of the company, from list_companies.
period_fromstring (date)Required
The first day of the month.
period_tostring (date)Required
The last day of the same month.
Arguments
ArgumentTypeRequiredDescription
company_idstringYesThe id of the company, from list_companies.
period_fromstring (date)YesThe first day of the month.
period_tostring (date)YesThe last day of the same month.

Documents

get_document_record

Get a document record
ReadPermissionbooks.read

One document record with the invoices, statements, events and VAT returns that refer to it.

company_idstringRequired
The id of the company, from list_companies.
document_idstringRequired
The core ULID of the object, 26 characters.
Arguments
ArgumentTypeRequiredDescription
company_idstringYesThe id of the company, from list_companies.
document_idstringYesThe core ULID of the object, 26 characters.

get_inbox

Get the invoice inbox
ReadPermissiondocuments.read

The private address the company forwards supplier invoices to, the counts of the last 30 days and the Gmail search strings. The first read makes the address.

The private forwarding address of the company, made on the first read, and what came in.

Also the Gmail search strings to paste into a Gmail filter, and the newest Gmail forwarding confirmation that oscarai forwarded to the Gmail address that asked for it (never its code or link).

company_idstringRequired
The id of the company, from list_companies.
Arguments
ArgumentTypeRequiredDescription
company_idstringYesThe id of the company, from list_companies.

list_document_records

List document records
ReadPermissionbooks.read

The document records of the books. Ordered by creation; ordering=-created_at is newest first.

referenced=false lists the documents nothing in the books refers to yet: the uploads still to book. bank_feed=false leaves out the statements the bank feed stored (its JSON files), bank_feed=true lists only them. file_id and download_url name the stored file.

A list answers {items, next_cursor}; pass next_cursor back as cursor for the next page.

company_idstringRequired
The id of the company, from list_companies.
bank_feedboolean | null
Only the statements the bank feed stored (true) or every document but them (false). A statement a person uploaded is never a bank feed statement.
cursorstring
The `next_cursor` of the previous page. Omit it for the first page.
kind"invoice" | "receipt" | "credit_note" | "statement" | "contract" | "other"
Documents of this kind only. * `invoice` - invoice * `receipt` - receipt * `credit_note` - credit_note * `statement` - statement * `contract` - contract * `other` - other
limitinteger
The page size, 1 to 200. Default 50.
ordering"created_at" | "-created_at"
`created_at` (the default) is oldest first, `-created_at` newest first. The id breaks ties. * `created_at` - created_at * `-created_at` - -created_at
received_fromstring (date)
The earliest received date, inclusive. Leaves out documents without one.
received_tostring (date)
The latest received date, inclusive. Leaves out documents without one.
referencedboolean | null
Only documents the books refer to (true: booked) or that nothing refers to yet (false: to book).
sha256string
The SHA-256 of the file, lowercase hex.
Arguments
ArgumentTypeRequiredDescription
company_idstringYesThe id of the company, from list_companies.
bank_feedboolean | nullNoOnly the statements the bank feed stored (true) or every document but them (false). A statement a person uploaded is never a bank feed statement.
cursorstringNoThe `next_cursor` of the previous page. Omit it for the first page.
kind"invoice" | "receipt" | "credit_note" | "statement" | "contract" | "other"NoDocuments of this kind only. * `invoice` - invoice * `receipt` - receipt * `credit_note` - credit_note * `statement` - statement * `contract` - contract * `other` - other
limitintegerNoThe page size, 1 to 200. Default 50.
ordering"created_at" | "-created_at"No`created_at` (the default) is oldest first, `-created_at` newest first. The id breaks ties. * `created_at` - created_at * `-created_at` - -created_at
received_fromstring (date)NoThe earliest received date, inclusive. Leaves out documents without one.
received_tostring (date)NoThe latest received date, inclusive. Leaves out documents without one.
referencedboolean | nullNoOnly documents the books refer to (true: booked) or that nothing refers to yet (false: to book).
sha256stringNoThe SHA-256 of the file, lowercase hex.

list_inbound_emails

List inbound emails
ReadPermissiondocuments.read

The mails the invoice inbox received, newest first: the sender, the result, the files with their draft, and the attachments not kept.

One page of the received mails, newest first: the sender, the outcome, the files, the attachments not kept.

A list answers {items, next_cursor}; pass next_cursor back as cursor for the next page.

company_idstringRequired
The id of the company, from list_companies.
cursorstring
The pagination cursor value.
limitinteger
Number of results to return per page.
Arguments
ArgumentTypeRequiredDescription
company_idstringYesThe id of the company, from list_companies.
cursorstringNoThe pagination cursor value.
limitintegerNoNumber of results to return per page.

record_document

Record a document
WritePermissiondocuments.write

Runs the core command record_document. Permission: documents.write.

Send an idempotency_key and reuse it when you retry: the same key and the same arguments return the first outcome with replayed=true instead of running the command twice.

If the answer is the error human_actor_required, a person must decide: call propose_judgement with the same command and its full payload.

company_idstringRequired
The id of the company, from list_companies.
sha256stringRequired
kindstringRequired
filenamestringRequired
media_typestringRequired
size_bytesintegerRequired
storage_refstringRequired
legacy_sha1string | null
received_onstring (date) | null | string
document_datestring (date) | null | string
The date the document was issued; it starts the retention periods.
retention_untilstring (date) | null | string
A later retention date the caller needs; the core computes its own and keeps the later.
legal_holdboolean
idempotency_keystring
Optional. A key of your choice, 1 to 255 printable ASCII characters. The same key with the same arguments replays the first outcome.
Arguments
ArgumentTypeRequiredDescription
company_idstringYesThe id of the company, from list_companies.
sha256stringYes
kindstringYes
filenamestringYes
media_typestringYes
size_bytesintegerYes
storage_refstringYes
legacy_sha1string | nullNo
received_onstring (date) | null | stringNo
document_datestring (date) | null | stringNoThe date the document was issued; it starts the retention periods.
retention_untilstring (date) | null | stringNoA later retention date the caller needs; the core computes its own and keeps the later.
legal_holdbooleanNo
idempotency_keystringNoOptional. A key of your choice, 1 to 255 printable ASCII characters. The same key with the same arguments replays the first outcome.

Employees

get_employee

Get an employee
ReadPermissionbooks.read

The personal code is masked.

One employee, with every employment (the TÖR id and state, the suspensions) and the absences.

company_idstringRequired
The id of the company, from list_companies.
employee_idstringRequired
Arguments
ArgumentTypeRequiredDescription
company_idstringYesThe id of the company, from list_companies.
employee_idstringYes

get_employee_submission

Get the status of an employee submission
ReadPermissionbooks.read

One submission: its status, the review, the TÖR id once TÖR registered it, and the messages of TÖR.

One submission: its status, the reason of a refusal, TÖR's messages, the TÖR id once registered.

company_idstringRequired
The id of the company, from list_companies.
submission_idstringRequired
Arguments
ArgumentTypeRequiredDescription
company_idstringYesThe id of the company, from list_companies.
submission_idstringYes

list_employee_submissions

List employee submissions
ReadPermissionbooks.read

The new employees and changes submitted for the firm to review: submitted, approved, registered in TÖR, applied (a change TÖR does not hold, such as the salary) or rejected.

One page of the submissions, newest first, with their status and the reason of a refusal.

A list answers {items, next_cursor}; pass next_cursor back as cursor for the next page.

company_idstringRequired
The id of the company, from list_companies.
cursorstring
The pagination cursor value.
limitinteger
Number of results to return per page.
Arguments
ArgumentTypeRequiredDescription
company_idstringYesThe id of the company, from list_companies.
cursorstringNoThe pagination cursor value.
limitintegerNoNumber of results to return per page.

list_employees

List employees
ReadPermissionbooks.read

The employee register, filled from TÖR, the employment register of the Tax and Customs Board.

One page of the employees, newest first, each with the facts of its newest employment.

source tor_external and registered_outside mark what TÖR showed that was not made through OscarAI. The personal code is masked.

A list answers {items, next_cursor}; pass next_cursor back as cursor for the next page.

company_idstringRequired
The id of the company, from list_companies.
cursorstring
The pagination cursor value.
limitinteger
Number of results to return per page.
Arguments
ArgumentTypeRequiredDescription
company_idstringYesThe id of the company, from list_companies.
cursorstringNoThe pagination cursor value.
limitintegerNoNumber of results to return per page.

submit_employee

Submit an employee or a change
WritePermissionemployees.submit

Submits a new employee, another employment, a change, a suspension or an end of an employment. Nothing reaches TÖR yet: the accounting firm reviews the submission, and only on its approval registers the event in TÖR. Read the outcome with get_employee_submission.

Submit a new employee, a new employment, a change, a suspension or an end, for the firm to review.

Staff review it; on approval OscarAI registers the event in TÖR. The personal code of a new employee is sealed and never returned. The event is checked as TÖR checks it (400 tor_invalid_event).

Send an idempotency_key and reuse it when you retry: the same key and the same arguments return the first outcome with replayed=true instead of running the command twice.

company_idstringRequired
The id of the company, from list_companies.
kind"new_employee" | "new_employment" | "change" | "suspension" | "end"Required
* `new_employee` - New employee * `new_employment` - New employment * `change` - Change * `suspension` - Suspension * `end` - End
employee_idstring
A new employment: the employee.
employment_idstring
A change, a suspension, an end: the employment.
employeeobject
The person of a new employee, or the changed fields of an employee.
employmentobject
The employment of a start, or the changed fields of an employment.
suspensionobject
A suspension of an employment.
endobject
The end of an employment.
event_datestring (date)
A change: the day it applies from. Default today.
idempotency_keystring
Optional. A key of your choice, 1 to 255 printable ASCII characters. The same key with the same arguments replays the first outcome.
Arguments
ArgumentTypeRequiredDescription
company_idstringYesThe id of the company, from list_companies.
kind"new_employee" | "new_employment" | "change" | "suspension" | "end"Yes* `new_employee` - New employee * `new_employment` - New employment * `change` - Change * `suspension` - Suspension * `end` - End
employee_idstringNoA new employment: the employee.
employment_idstringNoA change, a suspension, an end: the employment.
employeeobjectNoThe person of a new employee, or the changed fields of an employee.
employmentobjectNoThe employment of a start, or the changed fields of an employment.
suspensionobjectNoA suspension of an employment.
endobjectNoThe end of an employment.
event_datestring (date)NoA change: the day it applies from. Default today.
idempotency_keystringNoOptional. A key of your choice, 1 to 255 printable ASCII characters. The same key with the same arguments replays the first outcome.

Fixed assets

get_depreciation_status

Get the depreciation status
ReadPermissionbooks.read

What run_depreciation through a month would post, per asset, and the months it cannot post and why (a locked or missing period, or no usage recorded).

What a depreciation run through through would post, per asset, and the months it could not post and why.

through defaults to the month before the current month, the month the daily job posts. A blocked month (period_locked, no_period, usage_missing) needs a person.

company_idstringRequired
The id of the company, from list_companies.
throughstring
The last month, `YYYY-MM`. Default: the month before the current month. At most 12 months after the current month.
Arguments
ArgumentTypeRequiredDescription
company_idstringYesThe id of the company, from list_companies.
throughstringNoThe last month, `YYYY-MM`. Default: the month before the current month. At most 12 months after the current month.

get_fixed_asset

Get a fixed asset
ReadPermissionbooks.read

One asset: its components with the estimate in force and the next charge, its events, usage, opening amounts and the invoice lines linked to it.

One fixed asset: its components with their estimate and next charge, its events, usage and linked invoice lines.

The amounts are on as_of (default today); the months before its month are due.

company_idstringRequired
The id of the company, from list_companies.
fixed_asset_idstringRequired
The core ULID of the object, 26 characters.
as_ofstring (date)
The day of the amounts; the months before its month are due. Default: today.
Arguments
ArgumentTypeRequiredDescription
company_idstringYesThe id of the company, from list_companies.
fixed_asset_idstringYesThe core ULID of the object, 26 characters.
as_ofstring (date)NoThe day of the amounts; the months before its month are due. Default: today.

get_fixed_asset_movements

Get the fixed asset movement table
ReadPermissionbooks.read

The movement table of the notes for a date range, per kind of asset, and its agreement with the ledger.

The movement table of the fixed assets of a range (EE-FA-033), by taxonomy, and its agreement with the ledger.

Each column has the cost and the accumulated amounts at the start and at the end, the additions, the depreciation, the impairments and their reversals, the disposals, the reclassifications and the fair value changes. gl_agreement compares each asset account with the register.

company_idstringRequired
The id of the company, from list_companies.
date_fromstring (date)Required
The first day of the range.
date_tostring (date)Required
The last day of the range.
Arguments
ArgumentTypeRequiredDescription
company_idstringYesThe id of the company, from list_companies.
date_fromstring (date)YesThe first day of the range.
date_tostring (date)YesThe last day of the range.

get_fixed_asset_schedule

Get the depreciation schedule of a fixed asset
ReadPermissionbooks.read

Each month of each component: posted, due or projected, with the charge, the accumulated depreciation and the carrying amount.

The depreciation schedule of a fixed asset: each month of each component, posted, due or projected.

Without month_from and month_to it covers the useful life from the first month; at most 1200 months. A posted month names its entry.

company_idstringRequired
The id of the company, from list_companies.
fixed_asset_idstringRequired
The core ULID of the object, 26 characters.
as_ofstring (date)
The day the due months end at: the months before its month are due. Default: today.
month_fromstring
The first month, `YYYY-MM`. Default: the first month of depreciation.
month_tostring
The last month, `YYYY-MM`. Default: the end of the useful life. At most 1200 months.
Arguments
ArgumentTypeRequiredDescription
company_idstringYesThe id of the company, from list_companies.
fixed_asset_idstringYesThe core ULID of the object, 26 characters.
as_ofstring (date)NoThe day the due months end at: the months before its month are due. Default: today.
month_fromstringNoThe first month, `YYYY-MM`. Default: the first month of depreciation.
month_tostringNoThe last month, `YYYY-MM`. Default: the end of the useful life. At most 1200 months.

list_fixed_asset_groups

List fixed asset groups
ReadPermissionbooks.read

The groups in force: class, accounts and the default method and useful life.

The fixed asset groups in force: their class, accounts and default estimate. Ordered by code.

company_idstringRequired
The id of the company, from list_companies.
onstring (date)
The day the groups are in force on. Default: the latest version of each group.
Arguments
ArgumentTypeRequiredDescription
company_idstringYesThe id of the company, from list_companies.
onstring (date)NoThe day the groups are in force on. Default: the latest version of each group.

list_fixed_assets

List fixed assets
ReadPermissionbooks.read

The fixed asset register: each asset with its group, class, status, cost, accumulated depreciation and impairment and carrying amount on a day (default today), and the totals.

The fixed asset register: each asset with its group, status and amounts on as_of (default today).

Ordered by code. totals sums every asset the filters keep. The register is internal; the Advanced part of the app reads it.

A list answers {items, next_cursor}; pass next_cursor back as cursor for the next page.

company_idstringRequired
The id of the company, from list_companies.
as_ofstring (date)
The day of the amounts. Default: today in the time zone of the books.
class"tangible" | "intangible" | "investment_property"
Assets of this class only. * `tangible` - tangible * `intangible` - intangible * `investment_property` - investment_property
cursorstring
The `next_cursor` of the previous page. Omit it for the first page.
groupstring
The code of a fixed asset group.
limitinteger
The page size, 1 to 200. Default 50.
status"planned" | "in_use" | "withdrawn" | "disposed"
Assets in this status only. * `planned` - planned * `in_use` - in_use * `withdrawn` - withdrawn * `disposed` - disposed
Arguments
ArgumentTypeRequiredDescription
company_idstringYesThe id of the company, from list_companies.
as_ofstring (date)NoThe day of the amounts. Default: today in the time zone of the books.
class"tangible" | "intangible" | "investment_property"NoAssets of this class only. * `tangible` - tangible * `intangible` - intangible * `investment_property` - investment_property
cursorstringNoThe `next_cursor` of the previous page. Omit it for the first page.
groupstringNoThe code of a fixed asset group.
limitintegerNoThe page size, 1 to 200. Default 50.
status"planned" | "in_use" | "withdrawn" | "disposed"NoAssets in this status only. * `planned` - planned * `in_use` - in_use * `withdrawn` - withdrawn * `disposed` - disposed

preview_depreciation

Preview a depreciation schedule
ReadPermissionbooks.read

The first 24 months and the total of a draft estimate (cost, ready-for-use date, method, life or rate). It writes nothing.

The first 24 months and the total of a draft estimate, under the depreciation policy in force. It writes nothing.

company_idstringRequired
The id of the company, from list_companies.
cost_minorintegerRequired
The cost, in cents.
method"straight_line" | "diminishing_balance" | "units_of_production" | "none"Required
* `straight_line` - straight_line * `diminishing_balance` - diminishing_balance * `units_of_production` - units_of_production * `none` - none
rate_bpsinteger
ready_for_use_datestring (date)Required
residual_value_minorinteger
useful_life_monthsinteger
Arguments
ArgumentTypeRequiredDescription
company_idstringYesThe id of the company, from list_companies.
cost_minorintegerYesThe cost, in cents.
method"straight_line" | "diminishing_balance" | "units_of_production" | "none"Yes* `straight_line` - straight_line * `diminishing_balance` - diminishing_balance * `units_of_production` - units_of_production * `none` - none
rate_bpsintegerNo
ready_for_use_datestring (date)Yes
residual_value_minorintegerNo
useful_life_monthsintegerNo

Invoices

cancel_invoice

Cancel a draft invoice
WritePermissioninvoices.post_purchase or invoices.writeinvoices.post_purchaseorinvoices.write

Runs the core command cancel_invoice. Permission: invoices.write for a sales invoice, invoices.post_purchase for a purchase invoice. The path carries invoice_id.

Send an idempotency_key and reuse it when you retry: the same key and the same arguments return the first outcome with replayed=true instead of running the command twice.

If the answer is the error human_actor_required, a person must decide: call propose_judgement with the same command and its full payload.

company_idstringRequired
The id of the company, from list_companies.
invoice_idstringRequired
A core id (ULID).
reasonstringRequired
idempotency_keystring
Optional. A key of your choice, 1 to 255 printable ASCII characters. The same key with the same arguments replays the first outcome.
Arguments
ArgumentTypeRequiredDescription
company_idstringYesThe id of the company, from list_companies.
invoice_idstringYesA core id (ULID).
reasonstringYes
idempotency_keystringNoOptional. A key of your choice, 1 to 255 printable ASCII characters. The same key with the same arguments replays the first outcome.

get_invoice

Get an invoice
ReadPermissionbooks.read

One invoice: its current revision with lines and documents, its revisions, its entries and its settlement.

company_idstringRequired
The id of the company, from list_companies.
invoice_idstringRequired
The core ULID of the object, 26 characters.
Arguments
ArgumentTypeRequiredDescription
company_idstringYesThe id of the company, from list_companies.
invoice_idstringYesThe core ULID of the object, 26 characters.

get_invoice_issue_deadlines

Get the sales invoices to issue
ReadPermissionbooks.read

The recorded sales invoices not issued yet whose supply has happened, with the last day to issue each: 7 days after the supply, or the 15th of the next month for an EU supply.

The recorded sales invoices to issue on as_of, with the last day to issue each (EE-VAT-018).

An invoice is issued within 7 calendar days after the supply, the end of a continuous supply, or the prepayment; an intra-Community supply or a service to a business in another EU state by the 15th of the next month. Only a supply made by as_of, on a day the company is VAT-registered, is listed. The daily reminder job raises an alert for each.

company_idstringRequired
The id of the company, from list_companies.
as_ofstring (date)Required
The day: the supplies made by it are due to be invoiced.
Arguments
ArgumentTypeRequiredDescription
company_idstringYesThe id of the company, from list_companies.
as_ofstring (date)YesThe day: the supplies made by it are due to be invoiced.

import_sales_invoice

Import a sales invoice issued elsewhere
WritePermissioninvoices.issue

Records, issues and posts it with its external number, in the series of its source.

Runs the core command import_sales_invoice. Permission: invoices.issue.

Send an idempotency_key and reuse it when you retry: the same key and the same arguments return the first outcome with replayed=true instead of running the command twice.

If the answer is the error human_actor_required, a person must decide: call propose_judgement with the same command and its full payload.

company_idstringRequired
The id of the company, from list_companies.
seriesstringRequired
The key of the external series, named after the source of the invoice: `stripe`, the name of the other software, or `manual`. 1 to 32 lower-case letters, digits, `_` or `-`.
numberstringRequired
The number the invoice carries. Unique in its series; never a number of the Oscar series.
kindstring
Default `invoice`; `credit_note` names `corrects_invoice_id`.
party_idstringRequired
corrects_invoice_idstring | null
seller_snapshotany | null
buyer_snapshotany | null
revisionobjectRequired
The facts of the invoice. `invoice_date` is the external issue date; `documents` holds the original document (role `original`).
idempotency_keystring
Optional. A key of your choice, 1 to 255 printable ASCII characters. The same key with the same arguments replays the first outcome.
Arguments
ArgumentTypeRequiredDescription
company_idstringYesThe id of the company, from list_companies.
seriesstringYesThe key of the external series, named after the source of the invoice: `stripe`, the name of the other software, or `manual`. 1 to 32 lower-case letters, digits, `_` or `-`.
numberstringYesThe number the invoice carries. Unique in its series; never a number of the Oscar series.
kindstringNoDefault `invoice`; `credit_note` names `corrects_invoice_id`.
party_idstringYes
corrects_invoice_idstring | nullNo
seller_snapshotany | nullNo
buyer_snapshotany | nullNo
revisionobjectYesThe facts of the invoice. `invoice_date` is the external issue date; `documents` holds the original document (role `original`).
idempotency_keystringNoOptional. A key of your choice, 1 to 255 printable ASCII characters. The same key with the same arguments replays the first outcome.

issue_invoice

Issue a sales invoice
WritePermissioninvoices.issue

Runs the core command issue_invoice. Permission: invoices.issue. The path carries invoice_id.

Send an idempotency_key and reuse it when you retry: the same key and the same arguments return the first outcome with replayed=true instead of running the command twice.

If the answer is the error human_actor_required, a person must decide: call propose_judgement with the same command and its full payload.

company_idstringRequired
The id of the company, from list_companies.
invoice_idstringRequired
A core id (ULID).
numberstring | null
Only under a `free` numbering policy.
seller_snapshotany | null
buyer_snapshotany | null
seller_addressstring | null
The seller's postal address frozen into the seller snapshot. Without it the API takes the company's address from the Business Register. A VAT-registered company issues no invoice without the seller's and the buyer's address: 400 `seller_address_missing` or `buyer_address_missing` (EE-VAT-020).
idempotency_keystring
Optional. A key of your choice, 1 to 255 printable ASCII characters. The same key with the same arguments replays the first outcome.
Arguments
ArgumentTypeRequiredDescription
company_idstringYesThe id of the company, from list_companies.
invoice_idstringYesA core id (ULID).
numberstring | nullNoOnly under a `free` numbering policy.
seller_snapshotany | nullNo
buyer_snapshotany | nullNo
seller_addressstring | nullNoThe seller's postal address frozen into the seller snapshot. Without it the API takes the company's address from the Business Register. A VAT-registered company issues no invoice without the seller's and the buyer's address: 400 `seller_address_missing` or `buyer_address_missing` (EE-VAT-020).
idempotency_keystringNoOptional. A key of your choice, 1 to 255 printable ASCII characters. The same key with the same arguments replays the first outcome.

list_invoices

List invoices
ReadPermissionbooks.read

The invoices, purchase and sales, with the header facts of their current revision and their settlement.

Oldest first by invoice date; ordering=-invoice_date is newest first. settlement filters by settlement_state: open is unpaid or part paid, overdue an open invoice due before today in the time zone of the books.

A list answers {items, next_cursor}; pass next_cursor back as cursor for the next page.

company_idstringRequired
The id of the company, from list_companies.
cursorstring
The `next_cursor` of the previous page. Omit it for the first page.
date_fromstring (date)
The earliest invoice date, inclusive.
date_tostring (date)
The latest invoice date, inclusive.
direction"purchase" | "sales"
Purchase or sales invoices only. * `purchase` - purchase * `sales` - sales
external_source_prefixstring
Imported invoices whose external series starts with this text: `stripe` selects every Stripe series.
kind"invoice" | "receipt" | "credit_note" | "prepayment"
Invoices of this kind only. * `invoice` - invoice * `receipt` - receipt * `credit_note` - credit_note * `prepayment` - prepayment
limitinteger
The page size, 1 to 200. Default 50.
needs_reviewboolean | null
Only invoices that need review (true) or that do not (false).
numberstring
The exact invoice number.
ordering"invoice_date" | "-invoice_date"
`invoice_date` (the default) is oldest first, `-invoice_date` newest first. The id breaks ties. * `invoice_date` - invoice_date * `-invoice_date` - -invoice_date
party_idstring
Invoices of this party only.
settlement"unposted" | "unpaid" | "part_paid" | "paid" | "open" | "overdue"
Invoices in this settlement state; `open` is `unpaid` and `part_paid`, `overdue` is an open invoice due before today. * `unposted` - unposted * `unpaid` - unpaid * `part_paid` - part_paid * `paid` - paid * `open` - open * `overdue` - overdue
state"recorded" | "issued" | "posted" | "cancelled" | "void"
Invoices in this state only. * `recorded` - recorded * `issued` - issued * `posted` - posted * `cancelled` - cancelled * `void` - void
Arguments
ArgumentTypeRequiredDescription
company_idstringYesThe id of the company, from list_companies.
cursorstringNoThe `next_cursor` of the previous page. Omit it for the first page.
date_fromstring (date)NoThe earliest invoice date, inclusive.
date_tostring (date)NoThe latest invoice date, inclusive.
direction"purchase" | "sales"NoPurchase or sales invoices only. * `purchase` - purchase * `sales` - sales
external_source_prefixstringNoImported invoices whose external series starts with this text: `stripe` selects every Stripe series.
kind"invoice" | "receipt" | "credit_note" | "prepayment"NoInvoices of this kind only. * `invoice` - invoice * `receipt` - receipt * `credit_note` - credit_note * `prepayment` - prepayment
limitintegerNoThe page size, 1 to 200. Default 50.
needs_reviewboolean | nullNoOnly invoices that need review (true) or that do not (false).
numberstringNoThe exact invoice number.
ordering"invoice_date" | "-invoice_date"No`invoice_date` (the default) is oldest first, `-invoice_date` newest first. The id breaks ties. * `invoice_date` - invoice_date * `-invoice_date` - -invoice_date
party_idstringNoInvoices of this party only.
settlement"unposted" | "unpaid" | "part_paid" | "paid" | "open" | "overdue"NoInvoices in this settlement state; `open` is `unpaid` and `part_paid`, `overdue` is an open invoice due before today. * `unposted` - unposted * `unpaid` - unpaid * `part_paid` - part_paid * `paid` - paid * `open` - open * `overdue` - overdue
state"recorded" | "issued" | "posted" | "cancelled" | "void"NoInvoices in this state only. * `recorded` - recorded * `issued` - issued * `posted` - posted * `cancelled` - cancelled * `void` - void

post_invoice

Post an invoice
WritePermissioninvoices.issue or invoices.post_purchaseinvoices.issueorinvoices.post_purchase

Runs the core command post_invoice. Permission: invoices.issue for a sales invoice, invoices.post_purchase for a purchase invoice. The path carries invoice_id.

Send an idempotency_key and reuse it when you retry: the same key and the same arguments return the first outcome with replayed=true instead of running the command twice.

If the answer is the error human_actor_required, a person must decide: call propose_judgement with the same command and its full payload.

company_idstringRequired
The id of the company, from list_companies.
invoice_idstringRequired
A core id (ULID).
cleared_by_bank_transaction_idstring | null
idempotency_keystring
Optional. A key of your choice, 1 to 255 printable ASCII characters. The same key with the same arguments replays the first outcome.
Arguments
ArgumentTypeRequiredDescription
company_idstringYesThe id of the company, from list_companies.
invoice_idstringYesA core id (ULID).
cleared_by_bank_transaction_idstring | nullNo
idempotency_keystringNoOptional. A key of your choice, 1 to 255 printable ASCII characters. The same key with the same arguments replays the first outcome.

record_invoice

Record an invoice
WritePermissioninvoices.write

Records a draft; post_invoice posts it.

Runs the core command record_invoice. Permission: invoices.write.

Send an idempotency_key and reuse it when you retry: the same key and the same arguments return the first outcome with replayed=true instead of running the command twice.

If the answer is the error human_actor_required, a person must decide: call propose_judgement with the same command and its full payload.

company_idstringRequired
The id of the company, from list_companies.
directionstringRequired
`sales` or `purchase`.
kindstring
Default `invoice`.
party_idstringRequired
numberstring | null
corrects_invoice_idstring | null
originstring
Default `human`.
revisionobjectRequired
The content of an invoice: one revision. A chosen `exchange_rate_id` is a human judgement.
idempotency_keystring
Optional. A key of your choice, 1 to 255 printable ASCII characters. The same key with the same arguments replays the first outcome.
Arguments
ArgumentTypeRequiredDescription
company_idstringYesThe id of the company, from list_companies.
directionstringYes`sales` or `purchase`.
kindstringNoDefault `invoice`.
party_idstringYes
numberstring | nullNo
corrects_invoice_idstring | nullNo
originstringNoDefault `human`.
revisionobjectYesThe content of an invoice: one revision. A chosen `exchange_rate_id` is a human judgement.
idempotency_keystringNoOptional. A key of your choice, 1 to 255 printable ASCII characters. The same key with the same arguments replays the first outcome.

revise_invoice

Revise an invoice
WritePermissioninvoices.write

Runs the core command revise_invoice. Permission: invoices.write. The path carries invoice_id.

Send an idempotency_key and reuse it when you retry: the same key and the same arguments return the first outcome with replayed=true instead of running the command twice.

If the answer is the error human_actor_required, a person must decide: call propose_judgement with the same command and its full payload.

company_idstringRequired
The id of the company, from list_companies.
invoice_idstringRequired
A core id (ULID).
reasonstringRequired
party_idstring | null
revisionobjectRequired
The content of an invoice: one revision. A chosen `exchange_rate_id` is a human judgement.
idempotency_keystring
Optional. A key of your choice, 1 to 255 printable ASCII characters. The same key with the same arguments replays the first outcome.
Arguments
ArgumentTypeRequiredDescription
company_idstringYesThe id of the company, from list_companies.
invoice_idstringYesA core id (ULID).
reasonstringYes
party_idstring | nullNo
revisionobjectYesThe content of an invoice: one revision. A chosen `exchange_rate_id` is a human judgement.
idempotency_keystringNoOptional. A key of your choice, 1 to 255 printable ASCII characters. The same key with the same arguments replays the first outcome.

Journal

get_books_head

Get the head of the books
ReadPermissionbooks.read

The head of the books: the commit_seq of the latest command, the version a client cache is built from.

company_idstringRequired
The id of the company, from list_companies.
Arguments
ArgumentTypeRequiredDescription
company_idstringYesThe id of the company, from list_companies.

get_entry

Get a journal entry
ReadPermissionbooks.read

One journal entry with its lines and its posting fingerprint.

company_idstringRequired
The id of the company, from list_companies.
entry_idstringRequired
The core ULID of the object, 26 characters.
Arguments
ArgumentTypeRequiredDescription
company_idstringYesThe id of the company, from list_companies.
entry_idstringYesThe core ULID of the object, 26 characters.

list_entries

List journal entries
ReadPermissionbooks.read

The posted and reversed journal entries, each with all its lines. Ordered by economic date.

ordering=-economic_date is newest first.

A list answers {items, next_cursor}; pass next_cursor back as cursor for the next page.

company_idstringRequired
The id of the company, from list_companies.
account_codestring
Entries with at least one line on this account.
bank_transaction_idstring
Entries posted from this bank transaction.
cursorstring
The `next_cursor` of the previous page. Omit it for the first page.
date_fromstring (date)
The earliest economic date, inclusive.
date_tostring (date)
The latest economic date, inclusive.
invoice_idstring
Entries posted from any revision of this invoice.
journal"purchases" | "sales" | "bank" | "general" | "opening" | "closing"
Entries of this journal only. * `purchases` - purchases * `sales` - sales * `bank` - bank * `general` - general * `opening` - opening * `closing` - closing
limitinteger
The page size, 1 to 200. Default 50.
ordering"economic_date" | "-economic_date"
`economic_date` (the default) is oldest first, `-economic_date` newest first. The id breaks ties. * `economic_date` - economic_date * `-economic_date` - -economic_date
party_idstring
Entries with at least one line naming this party.
periodstring
A period code (`2026-03`) or id.
source_idstring
Entries posted from this source row only.
source_kind"invoice_revision" | "bank_transaction" | "allocation" | "transaction_exemption" | "transaction_money_in" | "accounting_event" | "vat_return"
Entries posted from this kind of source only. * `invoice_revision` - invoice_revision * `bank_transaction` - bank_transaction * `allocation` - allocation * `transaction_exemption` - transaction_exemption * `transaction_money_in` - transaction_money_in * `accounting_event` - accounting_event * `vat_return` - vat_return
source_role"primary" | "reversal" | "replacement"
Entries with this role only. * `primary` - primary * `reversal` - reversal * `replacement` - replacement
state"posted" | "reversed"
Posted or reversed entries only. * `posted` - posted * `reversed` - reversed
Arguments
ArgumentTypeRequiredDescription
company_idstringYesThe id of the company, from list_companies.
account_codestringNoEntries with at least one line on this account.
bank_transaction_idstringNoEntries posted from this bank transaction.
cursorstringNoThe `next_cursor` of the previous page. Omit it for the first page.
date_fromstring (date)NoThe earliest economic date, inclusive.
date_tostring (date)NoThe latest economic date, inclusive.
invoice_idstringNoEntries posted from any revision of this invoice.
journal"purchases" | "sales" | "bank" | "general" | "opening" | "closing"NoEntries of this journal only. * `purchases` - purchases * `sales` - sales * `bank` - bank * `general` - general * `opening` - opening * `closing` - closing
limitintegerNoThe page size, 1 to 200. Default 50.
ordering"economic_date" | "-economic_date"No`economic_date` (the default) is oldest first, `-economic_date` newest first. The id breaks ties. * `economic_date` - economic_date * `-economic_date` - -economic_date
party_idstringNoEntries with at least one line naming this party.
periodstringNoA period code (`2026-03`) or id.
source_idstringNoEntries posted from this source row only.
source_kind"invoice_revision" | "bank_transaction" | "allocation" | "transaction_exemption" | "transaction_money_in" | "accounting_event" | "vat_return"NoEntries posted from this kind of source only. * `invoice_revision` - invoice_revision * `bank_transaction` - bank_transaction * `allocation` - allocation * `transaction_exemption` - transaction_exemption * `transaction_money_in` - transaction_money_in * `accounting_event` - accounting_event * `vat_return` - vat_return
source_role"primary" | "reversal" | "replacement"NoEntries with this role only. * `primary` - primary * `reversal` - reversal * `replacement` - replacement
state"posted" | "reversed"NoPosted or reversed entries only. * `posted` - posted * `reversed` - reversed

verify_books

Verify the books
ReadPermissionbooks.read

Runs the consistency checks of the books. Slow.

Return the findings of the verification job. An empty list means the books are consistent.

company_idstringRequired
The id of the company, from list_companies.
Arguments
ArgumentTypeRequiredDescription
company_idstringYesThe id of the company, from list_companies.

Parties

create_party

Create a party
WritePermissionparties.write

Runs the core command create_party. Permission: parties.write.

Send an idempotency_key and reuse it when you retry: the same key and the same arguments return the first outcome with replayed=true instead of running the command twice.

If the answer is the error human_actor_required, a person must decide: call propose_judgement with the same command and its full payload.

company_idstringRequired
The id of the company, from list_companies.
namestringRequired
kind"supplier" | "customer" | "employee" | "authority" | "group_company" | "other"Required
* `supplier` - supplier * `customer` - customer * `employee` - employee * `authority` - authority * `group_company` - group_company * `other` - other
countrystring | null
vat_areastring | null
vat_numberstring | null
reg_codestring | null
expects_documentboolean
Default true.
is_confirmedboolean
notesstring | null
external_keystring | null
The key of the party in another system, for example `stripe:acct_…:cus_…`. Unique; with it, a party with the same name is allowed.
private_personsboolean
The party pools private persons (card buyers): the KMD INF annex leaves it out. No registry code. Default false.
addressstring | null
The postal address printed on an invoice, one or more lines; the country is `country`. At most 500 characters.
emailstring | null
The email address of the party. Trimmed; blank is null. At most 254 characters, no whitespace, and exactly one `@` with text on both sides, else 400 `invalid_payload`.
phonestring | null
The phone number of the party. Trimmed; blank is null. At most 40 characters: digits, spaces and `+ - ( ) .`, with at least 5 digits, else 400 `invalid_payload`.
idempotency_keystring
Optional. A key of your choice, 1 to 255 printable ASCII characters. The same key with the same arguments replays the first outcome.
Arguments
ArgumentTypeRequiredDescription
company_idstringYesThe id of the company, from list_companies.
namestringYes
kind"supplier" | "customer" | "employee" | "authority" | "group_company" | "other"Yes* `supplier` - supplier * `customer` - customer * `employee` - employee * `authority` - authority * `group_company` - group_company * `other` - other
countrystring | nullNo
vat_areastring | nullNo
vat_numberstring | nullNo
reg_codestring | nullNo
expects_documentbooleanNoDefault true.
is_confirmedbooleanNo
notesstring | nullNo
external_keystring | nullNoThe key of the party in another system, for example `stripe:acct_…:cus_…`. Unique; with it, a party with the same name is allowed.
private_personsbooleanNoThe party pools private persons (card buyers): the KMD INF annex leaves it out. No registry code. Default false.
addressstring | nullNoThe postal address printed on an invoice, one or more lines; the country is `country`. At most 500 characters.
emailstring | nullNoThe email address of the party. Trimmed; blank is null. At most 254 characters, no whitespace, and exactly one `@` with text on both sides, else 400 `invalid_payload`.
phonestring | nullNoThe phone number of the party. Trimmed; blank is null. At most 40 characters: digits, spaces and `+ - ( ) .`, with at least 5 digits, else 400 `invalid_payload`.
idempotency_keystringNoOptional. A key of your choice, 1 to 255 printable ASCII characters. The same key with the same arguments replays the first outcome.

get_party

Get a party
ReadPermissionbooks.read

One party with its defaults and its roles.

company_idstringRequired
The id of the company, from list_companies.
party_idstringRequired
The core ULID of the object, 26 characters.
Arguments
ArgumentTypeRequiredDescription
company_idstringYesThe id of the company, from list_companies.
party_idstringYesThe core ULID of the object, 26 characters.

list_parties

List parties
ReadPermissionbooks.read

Customers, suppliers and other counterparties.

The parties, ordered by their cleaned name. Merged parties are left out unless asked for.

roles says what each party is to the company, from its kind, its invoices and its open purchase drafts; role filters on the roles the books derive (an open draft aside), and exclude_kind=employee leaves out the employees, as the list of customers and suppliers does.

A list answers {items, next_cursor}; pass next_cursor back as cursor for the next page.

company_idstringRequired
The id of the company, from list_companies.
cursorstring
The `next_cursor` of the previous page. Omit it for the first page.
exclude_kind"supplier" | "customer" | "employee" | "authority" | "group_company" | "other"
Leave out the parties of this kind: `employee` on the list of customers and suppliers. * `supplier` - supplier * `customer` - customer * `employee` - employee * `authority` - authority * `group_company` - group_company * `other` - other
external_keystring
The exact key of the party in another system.
include_mergedboolean | null
Include parties merged into another. Default false.
include_settled_externalboolean | null
Include the parties with a key in another system (a Stripe customer) that have no open item. Default false: the list leaves them out unless it is filtered by `search`, `reg_code`, `vat_number` or `external_key`.
kind"supplier" | "customer" | "employee" | "authority" | "group_company" | "other"
Parties of this kind only. * `supplier` - supplier * `customer` - customer * `employee` - employee * `authority` - authority * `group_company` - group_company * `other` - other
limitinteger
The page size, 1 to 200. Default 50.
reg_codestring
The exact registry code.
role"supplier" | "customer"
Only the parties that play this role, as `roles` derives it from the kind and the invoices. * `supplier` - supplier * `customer` - customer
searchstring
Text anywhere in the name, or in the cleaned matching key.
vat_numberstring
The exact VAT number.
Arguments
ArgumentTypeRequiredDescription
company_idstringYesThe id of the company, from list_companies.
cursorstringNoThe `next_cursor` of the previous page. Omit it for the first page.
exclude_kind"supplier" | "customer" | "employee" | "authority" | "group_company" | "other"NoLeave out the parties of this kind: `employee` on the list of customers and suppliers. * `supplier` - supplier * `customer` - customer * `employee` - employee * `authority` - authority * `group_company` - group_company * `other` - other
external_keystringNoThe exact key of the party in another system.
include_mergedboolean | nullNoInclude parties merged into another. Default false.
include_settled_externalboolean | nullNoInclude the parties with a key in another system (a Stripe customer) that have no open item. Default false: the list leaves them out unless it is filtered by `search`, `reg_code`, `vat_number` or `external_key`.
kind"supplier" | "customer" | "employee" | "authority" | "group_company" | "other"NoParties of this kind only. * `supplier` - supplier * `customer` - customer * `employee` - employee * `authority` - authority * `group_company` - group_company * `other` - other
limitintegerNoThe page size, 1 to 200. Default 50.
reg_codestringNoThe exact registry code.
role"supplier" | "customer"NoOnly the parties that play this role, as `roles` derives it from the kind and the invoices. * `supplier` - supplier * `customer` - customer
searchstringNoText anywhere in the name, or in the cleaned matching key.
vat_numberstringNoThe exact VAT number.

Payments

get_payment_connection

Get a payment connection
ReadPermissionpayments.read

Start here for a question about Stripe: the feeds (one bank account per currency) and their balances, the last sync run, the open checks and the number of unexplained card receipts.

One connection: its permissions, its feeds and their balances, the last run and the open checks.

company_idstringRequired
The id of the company, from list_companies.
connection_idstringRequired
The sqid of the connection.
Arguments
ArgumentTypeRequiredDescription
company_idstringYesThe id of the company, from list_companies.
connection_idstringYesThe sqid of the connection.

get_payment_sync_run

Get a sync run
ReadPermissionpayments.read

One sync run: its window, its counts and its checks.

company_idstringRequired
The id of the company, from list_companies.
connection_idstringRequired
The sqid of the connection.
run_idstringRequired
The sqid of the run.
Arguments
ArgumentTypeRequiredDescription
company_idstringYesThe id of the company, from list_companies.
connection_idstringYesThe sqid of the connection.
run_idstringYesThe sqid of the run.

get_stripe_document

Get a Stripe invoice or credit note of a connection
ReadPermissionpayments.read

One Stripe invoice or credit note: its import, its checks, its payments and refunds, and its document.

company_idstringRequired
The id of the company, from list_companies.
connection_idstringRequired
The sqid of the connection.
document_idstringRequired
The sqid of the import row.
Arguments
ArgumentTypeRequiredDescription
company_idstringYesThe id of the company, from list_companies.
connection_idstringYesThe sqid of the connection.
document_idstringYesThe sqid of the import row.

get_stripe_documents_summary

Get the summary of the Stripe invoices of a connection
ReadPermissionpayments.read

The Invoices tab: the import rows per state, the blocked ones per code, the payments, the last warnings.

company_idstringRequired
The id of the company, from list_companies.
connection_idstringRequired
The sqid of the connection.
Arguments
ArgumentTypeRequiredDescription
company_idstringYesThe id of the company, from list_companies.
connection_idstringYesThe sqid of the connection.

get_stripe_invoice_import

Get the Stripe import of an invoice
ReadPermissionbooks.read

For an invoice of the books whose external_source is stripe.

The Stripe import of one invoice of the books: its Stripe number and status, its Dashboard link, its PDF and its payments with their Stripe ids. 404 for an invoice that did not come from Stripe.

company_idstringRequired
The id of the company, from list_companies.
invoice_idstringRequired
The invoice in the books (a ULID).
Arguments
ArgumentTypeRequiredDescription
company_idstringYesThe id of the company, from list_companies.
invoice_idstringYesThe invoice in the books (a ULID).

list_payment_connections

List payment connections
ReadPermissionpayments.read

The Stripe connections of the company, with their status, the last sync and the count of open checks. No tool shows or changes the key of a connection.

The connections of the company, newest first, disconnected ones included.

A list answers {items, next_cursor}; pass next_cursor back as cursor for the next page.

company_idstringRequired
The id of the company, from list_companies.
cursorstring
limitinteger
Number of results to return per page.
Arguments
ArgumentTypeRequiredDescription
company_idstringYesThe id of the company, from list_companies.
cursorstringNo
limitintegerNoNumber of results to return per page.

list_payment_sync_runs

List the sync runs of a connection
ReadPermissionpayments.read

The sync runs of the connection, newest first, with their counts and checks.

A list answers {items, next_cursor}; pass next_cursor back as cursor for the next page.

company_idstringRequired
The id of the company, from list_companies.
connection_idstringRequired
The sqid of the connection.
cursorstring
Arguments
ArgumentTypeRequiredDescription
company_idstringYesThe id of the company, from list_companies.
connection_idstringYesThe sqid of the connection.
cursorstringNo

list_stripe_customers

List the Stripe customers of a connection
ReadPermissionpayments.read

A person links a Stripe customer to another party in Oscar; no tool does it.

The Stripe customers of the connection, each with its party, how it was linked and its invoice count.

A list answers {items, next_cursor}; pass next_cursor back as cursor for the next page.

company_idstringRequired
The id of the company, from list_companies.
connection_idstringRequired
The sqid of the connection.
cursorstring
Arguments
ArgumentTypeRequiredDescription
company_idstringYesThe id of the company, from list_companies.
connection_idstringYesThe sqid of the connection.
cursorstringNo

list_stripe_documents

List the Stripe invoices and credit notes of a connection
ReadPermissionpayments.read

Answers why a Stripe invoice is not in the books: each one with how far its import went. A blocked one carries its block_code; retry_stripe_import runs it again once its cause is fixed.

The Stripe invoices and credit notes of the connection and how far each import went, newest first.

state=blocked lists what waits for a person, with its block_code.

A list answers {items, next_cursor}; pass next_cursor back as cursor for the next page.

company_idstringRequired
The id of the company, from list_companies.
connection_idstringRequired
The sqid of the connection.
block_codestring
cursorstring
date_fromstring (date)
The earliest invoice date, inclusive.
date_tostring (date)
The latest invoice date, inclusive.
invoice_idstring
The core invoice (a ULID).
object_type"invoice" | "credit_note"
* `invoice` - Invoice * `credit_note` - Credit note
state"pending" | "blocked" | "document_stored" | "posted" | "zero" | "cancelled" | "before_cutover"
* `pending` - Pending * `blocked` - Blocked * `document_stored` - Document stored * `posted` - Posted * `zero` - Zero * `cancelled` - Cancelled * `before_cutover` - Before the cut-over
stripe_customer_idstring
Arguments
ArgumentTypeRequiredDescription
company_idstringYesThe id of the company, from list_companies.
connection_idstringYesThe sqid of the connection.
block_codestringNo
cursorstringNo
date_fromstring (date)NoThe earliest invoice date, inclusive.
date_tostring (date)NoThe latest invoice date, inclusive.
invoice_idstringNoThe core invoice (a ULID).
object_type"invoice" | "credit_note"No* `invoice` - Invoice * `credit_note` - Credit note
state"pending" | "blocked" | "document_stored" | "posted" | "zero" | "cancelled" | "before_cutover"No* `pending` - Pending * `blocked` - Blocked * `document_stored` - Document stored * `posted` - Posted * `zero` - Zero * `cancelled` - Cancelled * `before_cutover` - Before the cut-over
stripe_customer_idstringNo

list_stripe_fee_invoices

List the Stripe fee invoices of a connection
ReadPermissionpayments.read

The monthly fee invoices of the connection, newest month first (booked only when staff switched them on).

company_idstringRequired
The id of the company, from list_companies.
connection_idstringRequired
The sqid of the connection.
Arguments
ArgumentTypeRequiredDescription
company_idstringYesThe id of the company, from list_companies.
connection_idstringYesThe sqid of the connection.

list_stripe_payouts

List the Stripe payouts of a connection
ReadPermissionpayments.read

Each payout with its match to the line of the bank statement that received it.

The Stripe payouts of the connection, newest first, with their match and their summary.

A list answers {items, next_cursor}; pass next_cursor back as cursor for the next page.

company_idstringRequired
The id of the company, from list_companies.
connection_idstringRequired
The sqid of the connection.
cursorstring
match_state"pending" | "matched" | "ambiguous" | "not_found" | "failed_payout"
* `pending` - Pending * `matched` - Matched * `ambiguous` - Ambiguous * `not_found` - Not found * `failed_payout` - Failed payout
Arguments
ArgumentTypeRequiredDescription
company_idstringYesThe id of the company, from list_companies.
connection_idstringYesThe sqid of the connection.
cursorstringNo
match_state"pending" | "matched" | "ambiguous" | "not_found" | "failed_payout"No* `pending` - Pending * `matched` - Matched * `ambiguous` - Ambiguous * `not_found` - Not found * `failed_payout` - Failed payout

list_stripe_tax_mappings

List the Stripe tax mapping of a connection
ReadPermissionpayments.read

How each Stripe tax becomes a VAT code. A person confirms or changes a mapping in Oscar; no tool does it.

The tax mapping of the connection in order: the first active row that matches a Stripe tax wins.

company_idstringRequired
The id of the company, from list_companies.
connection_idstringRequired
The sqid of the connection.
Arguments
ArgumentTypeRequiredDescription
company_idstringYesThe id of the company, from list_companies.
connection_idstringYesThe sqid of the connection.

list_stripe_transactions

List the Stripe transactions of a connection
ReadPermissionpayments.read

Answers why a card sale is unexplained: each imported Stripe transaction with its classification, the reason (for example no rule matched, or a VAT rate that no rule maps) and the facts the rules read.

The imported Stripe transactions, newest first, with their classification, reason and facts.

classification=suspense&category=charge lists the unexplained card receipts; bank_transaction_id finds the Stripe data of one feed line.

A list answers {items, next_cursor}; pass next_cursor back as cursor for the next page.

company_idstringRequired
The id of the company, from list_companies.
connection_idstringRequired
The sqid of the connection.
bank_transaction_idstring
The line of the Stripe feed (a ULID).
categorystring
classification"rule" | "deferred" | "suspense" | "posted" | "conflict" | "allocated"
* `rule` - Rule receipt * `deferred` - Deferred * `suspense` - Suspense * `posted` - Posted * `conflict` - Conflict * `allocated` - Allocated
cursorstring
Arguments
ArgumentTypeRequiredDescription
company_idstringYesThe id of the company, from list_companies.
connection_idstringYesThe sqid of the connection.
bank_transaction_idstringNoThe line of the Stripe feed (a ULID).
categorystringNo
classification"rule" | "deferred" | "suspense" | "posted" | "conflict" | "allocated"No* `rule` - Rule receipt * `deferred` - Deferred * `suspense` - Suspense * `posted` - Posted * `conflict` - Conflict * `allocated` - Allocated
cursorstringNo

request_payment_sync

Sync a payment connection now
WritePermissionpayments.manage

Queues a sync of the Stripe connection now, instead of waiting for the hourly sync. It answers with a task_id; list_payment_sync_runs shows the run when it has finished. A repeat imports nothing twice.

Queue a sync run now. A run already waiting takes this request too (the same task_id).

409 connection_disconnected, stripe_revoked or connection_paused.

Send an idempotency_key and reuse it when you retry: the same key and the same arguments return the first outcome with replayed=true instead of running the command twice.

company_idstringRequired
The id of the company, from list_companies.
connection_idstringRequired
The sqid of the connection.
idempotency_keystring
Optional. A key of your choice, 1 to 255 printable ASCII characters. The same key with the same arguments replays the first outcome.
Arguments
ArgumentTypeRequiredDescription
company_idstringYesThe id of the company, from list_companies.
connection_idstringYesThe sqid of the connection.
idempotency_keystringNoOptional. A key of your choice, 1 to 255 printable ASCII characters. The same key with the same arguments replays the first outcome.

retry_stripe_import

Retry the import of a Stripe invoice
WritePermissioninvoices.write

Runs the import of a blocked Stripe invoice or credit note again, with the same rules, after its cause was fixed (a tax mapping, a key permission). A repeat imports nothing twice.

Run the import of a blocked Stripe invoice or credit note now, with the same rules.

Not a judgement: it reads the same facts and the current tax mapping again. The answer is the row after the attempt; it may still be blocked, with its new reason.

Send an idempotency_key and reuse it when you retry: the same key and the same arguments return the first outcome with replayed=true instead of running the command twice.

company_idstringRequired
The id of the company, from list_companies.
connection_idstringRequired
The sqid of the connection.
document_idstringRequired
The sqid of the import row.
idempotency_keystring
Optional. A key of your choice, 1 to 255 printable ASCII characters. The same key with the same arguments replays the first outcome.
Arguments
ArgumentTypeRequiredDescription
company_idstringYesThe id of the company, from list_companies.
connection_idstringYesThe sqid of the connection.
document_idstringYesThe sqid of the import row.
idempotency_keystringNoOptional. A key of your choice, 1 to 255 printable ASCII characters. The same key with the same arguments replays the first outcome.

Payroll

get_pay_run

Get a pay run
ReadPermissionbooks.read

The salary payments matched to a net pay become the payment lines of the TSD on the bank date.

One pay run with every employee: the inputs, the gross and the net, the net not paid yet, the payments.

company_idstringRequired
The id of the company, from list_companies.
pay_run_idstringRequired
Arguments
ArgumentTypeRequiredDescription
company_idstringYesThe id of the company, from list_companies.
pay_run_idstringYes

list_pay_runs

List pay runs
ReadPermissionbooks.read

The monthly payroll: gross pay, taxes and net pay per month.

One page of the pay runs, newest month first, with their totals and the net pay not paid yet.

A client sees the posted runs; firm staff also the drafts and the approved ones.

A list answers {items, next_cursor}; pass next_cursor back as cursor for the next page.

company_idstringRequired
The id of the company, from list_companies.
cursorstring
The pagination cursor value.
limitinteger
Number of results to return per page.
Arguments
ArgumentTypeRequiredDescription
company_idstringYesThe id of the company, from list_companies.
cursorstringNoThe pagination cursor value.
limitintegerNoNumber of results to return per page.

Periods

list_periods

List periods
ReadPermissionbooks.read

The accounting periods with their fiscal year, ordered by start date.

A list answers {items, next_cursor}; pass next_cursor back as cursor for the next page.

company_idstringRequired
The id of the company, from list_companies.
cursorstring
The `next_cursor` of the previous page. Omit it for the first page.
datestring (date)
The period that contains this date.
fiscal_yearstring
The fiscal year label (`2026`).
limitinteger
The page size, 1 to 200. Default 50.
state"open" | "soft_closed" | "locked"
Periods in this state only. * `open` - open * `soft_closed` - soft_closed * `locked` - locked
Arguments
ArgumentTypeRequiredDescription
company_idstringYesThe id of the company, from list_companies.
cursorstringNoThe `next_cursor` of the previous page. Omit it for the first page.
datestring (date)NoThe period that contains this date.
fiscal_yearstringNoThe fiscal year label (`2026`).
limitintegerNoThe page size, 1 to 200. Default 50.
state"open" | "soft_closed" | "locked"NoPeriods in this state only. * `open` - open * `soft_closed` - soft_closed * `locked` - locked

Proposals

get_proposal

Get a proposal
ReadPermissionbooks.read

One proposal.

company_idstringRequired
The id of the company, from list_companies.
proposal_idstringRequired
Arguments
ArgumentTypeRequiredDescription
company_idstringYesThe id of the company, from list_companies.
proposal_idstringYes

list_proposals

List proposals
ReadPermissionbooks.read

The judgements proposed for a person to confirm, with their status.

The proposals of the company, newest first. A status that is not a status is 400.

A list answers {items, next_cursor}; pass next_cursor back as cursor for the next page.

company_idstringRequired
The id of the company, from list_companies.
cursorstring
The pagination cursor value.
limitinteger
Number of results to return per page.
status"confirmed" | "pending" | "rejected"
Only the proposals in this status.
Arguments
ArgumentTypeRequiredDescription
company_idstringYesThe id of the company, from list_companies.
cursorstringNoThe pagination cursor value.
limitintegerNoNumber of results to return per page.
status"confirmed" | "pending" | "rejected"NoOnly the proposals in this status.

propose_judgement

Propose a judgement
WritePermissionallocations.write or bank.classify or parties.writeallocations.writeorbank.classifyorparties.write

Proposes a command that only a person may run: an exemption, a money-in classification or rule, a party default, a merge of two parties, a discount or a write-off on an allocation, a dimension rule, a period reopening, the facts of a dividend (the approved annual report, unpaid capital, a dividend received), a VAT registration or deregistration, a fixed asset group, a change of a depreciation estimate, an impairment or its reversal, a fair value of an investment property, a transfer or a withdrawal of a fixed asset, an undo of a fixed asset event, or any command answered with human_actor_required. Nothing changes in the books until a person with the permission confirms the proposal in Oscar; the command then runs as that person.

The judgement commands and their payload fields (* required):

  • change_exemption: bank_transaction_id*, counter_role*, reason*
  • change_money_in: bank_transaction_id*, kind*, reason*, refund_invoice_id, refund_bank_transaction_id
  • classify_money_in: bank_transaction_id*, kind*, reason*, refund_invoice_id, refund_bank_transaction_id
  • exempt: bank_transaction_id*, counter_role*, reason*
  • merge_party: party_id*, into_party_id*, reason*
  • record_annual_report: financial_year_end*, approved_on*, net_assets_minor*, share_capital_minor*, legal_reserve_minor*, other_undistributable_reserves_minor, distributable_reserves_minor, retained_earnings_minor*, unamortised_development_costs_minor, document_id
  • record_dividend_received: received_on*, payer_name*, payer_reg_code, payer_country*, party_id, amount_minor*, holding_bps*, payer_taxable*, non_cooperative_jurisdiction, from_profit_taxed_at_14_86, document_id
  • record_unpaid_capital: as_of*, unpaid_minor*, reason*, document_id
  • record_vat_registration: kind*, effective_from*, vat_number, note, document_id
  • remove_dimension_rule: rule_id*, reason
  • remove_exemption: bank_transaction_id*, reason*
  • remove_money_in: bank_transaction_id*, reason*
  • remove_money_in_rule: rule_id*, effective_from*, reason*
  • reopen_period: period*, reason
  • reorder_money_in_rules: bank_account_id*, effective_from*, rule_ids*, reason*
  • set_dimension_rule: target_kind*, invoice_line_id, bank_transaction_id, dimension_value_id*, percent_bps, amount_minor, currency, note
  • set_money_in_rule: bank_account_id*, rule_id, name*, effective_from*, position*, conditions, outcome*, reason*
  • set_party_default: party_id*, expense_role, vat_code, currency, payment_days, language
  • set_fixed_asset_group: code*, name*, name_en, taxonomy*, cost_account*, contra_account*, fair_value_account, in_progress_account*, default_method*, default_useful_life_months, depreciable*, effective_from*, reason*, class*
  • change_fixed_asset_estimate: fixed_asset_id*, component_id, effective_from*, method, useful_life_months, rate_bps, total_units, unit, residual_value_minor, reason*
  • impair_fixed_asset: fixed_asset_id*, component_id, date*, recoverable_amount_minor*, basis*, discount_rate_bps, reason*
  • reverse_fixed_asset_impairment: fixed_asset_id*, component_id, date*, recoverable_amount_minor*, basis*, discount_rate_bps, reason*
  • revalue_investment_property: fixed_asset_id*, date*, fair_value_minor*, method*, appraiser, independent_appraiser*, reason*
  • transfer_fixed_asset: fixed_asset_id*, date*, to_group*, to_measurement, fair_value_minor, estimate, reason*
  • withdraw_fixed_asset: fixed_asset_id*, date*, reason*
  • undo_fixed_asset_event: event_id*, reason*

Send an idempotency_key and reuse it when you retry: the same key and the same arguments return the first outcome with replayed=true instead of running the command twice.

company_idstringRequired
The id of the company, from list_companies.
command"add_fixed_asset_component" | "allocate" | "amend_vat_return" | "apply_money_in_rules" | "cancel_invoice" | "change_exemption" | "change_fixed_asset_estimate" | "change_money_in" | "classify_money_in" | "close_period" | "close_year" | "create_bank_account" | "create_dimension" | "create_dimension_value" | "create_fixed_asset" | "create_party" | "declare_dividend" | "discard_invoice" | "dispose_fixed_asset" | "exempt" | "impair_fixed_asset" | "import_rates" | "import_sales_invoice" | "import_statement" | "import_vat_template" | "issue_invoice" | "map_role" | "mark_return_filed" | "match_transfer" | "merge_party" | "migrate_chart" | "open_fiscal_year" | "post_event" | "post_invoice" | "prepare_vat_return" | "put_fixed_asset_in_use" | "record_annual_report" | "record_dividend_received" | "record_document" | "record_event" | "record_fixed_asset_usage" | "record_invoice" | "record_turnover_exclusion" | "record_unpaid_capital" | "record_vat_registration" | "register_opening_fixed_asset" | "remove_dimension_rule" | "remove_exemption" | "remove_money_in" | "remove_money_in_rule" | "reopen_period" | "reorder_money_in_rules" | "revalue_investment_property" | "reverse_fixed_asset_impairment" | "revise_invoice" | "run_depreciation" | "seed_chart" | "set_dimension_rule" | "set_fixed_asset_group" | "set_money_in_rule" | "set_party_address" | "set_party_default" | "set_policy" | "set_transaction_party" | "soft_close_period" | "transfer_fixed_asset" | "unallocate" | "undo_fixed_asset_event" | "void_invoice" | "withdraw_fixed_asset"Required
The command a person should run.
payloadobjectRequired
The full payload of the command: the ids that its tool takes as arguments (for example bank_transaction_id) and its body fields. Not company_id.
notestring
Why you propose it, for the person who decides.
idempotency_keystring
Optional. A key of your choice, 1 to 255 printable ASCII characters. The same key with the same arguments replays the first outcome.
Arguments
ArgumentTypeRequiredDescription
company_idstringYesThe id of the company, from list_companies.
command"add_fixed_asset_component" | "allocate" | "amend_vat_return" | "apply_money_in_rules" | "cancel_invoice" | "change_exemption" | "change_fixed_asset_estimate" | "change_money_in" | "classify_money_in" | "close_period" | "close_year" | "create_bank_account" | "create_dimension" | "create_dimension_value" | "create_fixed_asset" | "create_party" | "declare_dividend" | "discard_invoice" | "dispose_fixed_asset" | "exempt" | "impair_fixed_asset" | "import_rates" | "import_sales_invoice" | "import_statement" | "import_vat_template" | "issue_invoice" | "map_role" | "mark_return_filed" | "match_transfer" | "merge_party" | "migrate_chart" | "open_fiscal_year" | "post_event" | "post_invoice" | "prepare_vat_return" | "put_fixed_asset_in_use" | "record_annual_report" | "record_dividend_received" | "record_document" | "record_event" | "record_fixed_asset_usage" | "record_invoice" | "record_turnover_exclusion" | "record_unpaid_capital" | "record_vat_registration" | "register_opening_fixed_asset" | "remove_dimension_rule" | "remove_exemption" | "remove_money_in" | "remove_money_in_rule" | "reopen_period" | "reorder_money_in_rules" | "revalue_investment_property" | "reverse_fixed_asset_impairment" | "revise_invoice" | "run_depreciation" | "seed_chart" | "set_dimension_rule" | "set_fixed_asset_group" | "set_money_in_rule" | "set_party_address" | "set_party_default" | "set_policy" | "set_transaction_party" | "soft_close_period" | "transfer_fixed_asset" | "unallocate" | "undo_fixed_asset_event" | "void_invoice" | "withdraw_fixed_asset"YesThe command a person should run.
payloadobjectYesThe full payload of the command: the ids that its tool takes as arguments (for example bank_transaction_id) and its body fields. Not company_id.
notestringNoWhy you propose it, for the person who decides.
idempotency_keystringNoOptional. A key of your choice, 1 to 255 printable ASCII characters. The same key with the same arguments replays the first outcome.

Reconciliation

confirm_match_proposal

Confirm a match proposal
WritePermissionreconciliation.decide

Allocates the bank payment of the proposal to its invoices. A person's confirm also sets the party of the payment when it has none.

Allocate a pending match as the caller. A confirmed one is returned unchanged.

The body is optional. pairs gives the amount in the bank currency of a pair in another currency (counter_minor); that pair is allocated with rate_source manual, which needs a person (403 match_manual_rate_needs_person for an API key or an agent).

Send an idempotency_key and reuse it when you retry: the same key and the same arguments return the first outcome with replayed=true instead of running the command twice.

company_idstringRequired
The id of the company, from list_companies.
proposal_idstringRequired
The sqid of the match proposal.
pairsarray of object
Needed for a pair in another currency than the bank line when the bank gave no rate (`match_needs_rate`); allowed for one with a statement rate. Only a person may give it.
idempotency_keystring
Optional. A key of your choice, 1 to 255 printable ASCII characters. The same key with the same arguments replays the first outcome.
Arguments
ArgumentTypeRequiredDescription
company_idstringYesThe id of the company, from list_companies.
proposal_idstringYesThe sqid of the match proposal.
pairsarray of objectNoNeeded for a pair in another currency than the bank line when the bank gave no rate (`match_needs_rate`); allowed for one with a statement rate. Only a person may give it.
idempotency_keystringNoOptional. A key of your choice, 1 to 255 printable ASCII characters. The same key with the same arguments replays the first outcome.

list_match_proposals

List match proposals
ReadPermissionbooks.read

The matches of outgoing bank payments to open purchase invoices that the reconciliation matcher proposed or applied, with their status, tier, confidence and the reason a match waits for a person. A person decides one with confirm_match_proposal, reject_match_proposal or undo_match_proposal.

The match proposals of the company, newest first.

A list answers {items, next_cursor}; pass next_cursor back as cursor for the next page.

company_idstringRequired
The id of the company, from list_companies.
bank_transaction_idstring
Only the proposals of this bank transaction (its core id).
cursorstring
The pagination cursor value.
limitinteger
Number of results to return per page.
status"applying" | "auto_applied" | "confirmed" | "no_match" | "pending" | "rejected" | "superseded" | "undone"
Only the proposals in this status. Without it, every status but `no_match`.
Arguments
ArgumentTypeRequiredDescription
company_idstringYesThe id of the company, from list_companies.
bank_transaction_idstringNoOnly the proposals of this bank transaction (its core id).
cursorstringNoThe pagination cursor value.
limitintegerNoNumber of results to return per page.
status"applying" | "auto_applied" | "confirmed" | "no_match" | "pending" | "rejected" | "superseded" | "undone"NoOnly the proposals in this status. Without it, every status but `no_match`.

reject_match_proposal

Reject a match proposal
WritePermissionreconciliation.decide

Marks a wrong match, so the matcher does not propose it again.

Reject a pending match; nothing changes in the books. A rejected one is returned unchanged.

Send an idempotency_key and reuse it when you retry: the same key and the same arguments return the first outcome with replayed=true instead of running the command twice.

company_idstringRequired
The id of the company, from list_companies.
proposal_idstringRequired
The sqid of the match proposal.
idempotency_keystring
Optional. A key of your choice, 1 to 255 printable ASCII characters. The same key with the same arguments replays the first outcome.
Arguments
ArgumentTypeRequiredDescription
company_idstringYesThe id of the company, from list_companies.
proposal_idstringYesThe sqid of the match proposal.
idempotency_keystringNoOptional. A key of your choice, 1 to 255 printable ASCII characters. The same key with the same arguments replays the first outcome.

undo_match_proposal

Undo a match
WritePermissionreconciliation.decide

Reverses the allocations of the match.

Unallocate a match the matcher applied or a person confirmed. An undone one is returned unchanged.

Send an idempotency_key and reuse it when you retry: the same key and the same arguments return the first outcome with replayed=true instead of running the command twice.

company_idstringRequired
The id of the company, from list_companies.
proposal_idstringRequired
The sqid of the match proposal.
idempotency_keystring
Optional. A key of your choice, 1 to 255 printable ASCII characters. The same key with the same arguments replays the first outcome.
Arguments
ArgumentTypeRequiredDescription
company_idstringYesThe id of the company, from list_companies.
proposal_idstringYesThe sqid of the match proposal.
idempotency_keystringNoOptional. A key of your choice, 1 to 255 printable ASCII characters. The same key with the same arguments replays the first outcome.

Reference data

get_rate_usage

Get the rows that use an exchange rate
ReadPermissionbooks.read

The invoices and bank transactions whose entries use the rate of one day, currency and source, for example after the ECB corrected it.

The invoices and bank transactions whose live entries use one exchange rate.

When the ECB corrects a rate after the books took it, these are the rows to re-rate (EE-FX-001, EE-VAT-026). rate is null when the books hold no such rate.

company_idstringRequired
The id of the company, from list_companies.
currencystringRequired
The ISO code of the foreign currency.
rate_datestring (date)Required
The day of the rate.
source"ecb" | "market" | "bank" | "implied" | "manual"
The source of the rate. Default `ecb`. * `ecb` - ecb * `market` - market * `bank` - bank * `implied` - implied * `manual` - manual
Arguments
ArgumentTypeRequiredDescription
company_idstringYesThe id of the company, from list_companies.
currencystringYesThe ISO code of the foreign currency.
rate_datestring (date)YesThe day of the rate.
source"ecb" | "market" | "bank" | "implied" | "manual"NoThe source of the rate. Default `ecb`. * `ecb` - ecb * `market` - market * `bank` - bank * `implied` - implied * `manual` - manual

list_accounts

List accounts
ReadPermissionbooks.read

The chart of accounts.

The chart of accounts, ordered by code.

A list answers {items, next_cursor}; pass next_cursor back as cursor for the next page.

company_idstringRequired
The id of the company, from list_companies.
activeboolean | null
Active (true) or inactive (false) accounts only.
control_kind"payable" | "receivable" | "suspense_payable" | "suspense_receivable" | "bank" | "transit" | "vat"
Accounts with this control kind only. * `payable` - payable * `receivable` - receivable * `suspense_payable` - suspense_payable * `suspense_receivable` - suspense_receivable * `bank` - bank * `transit` - transit * `vat` - vat
cursorstring
The `next_cursor` of the previous page. Omit it for the first page.
limitinteger
The page size, 1 to 200. Default 50.
searchstring
A code prefix, or text anywhere in the name.
type"asset" | "liability" | "equity" | "income" | "expense"
Accounts of this type only. * `asset` - asset * `liability` - liability * `equity` - equity * `income` - income * `expense` - expense
Arguments
ArgumentTypeRequiredDescription
company_idstringYesThe id of the company, from list_companies.
activeboolean | nullNoActive (true) or inactive (false) accounts only.
control_kind"payable" | "receivable" | "suspense_payable" | "suspense_receivable" | "bank" | "transit" | "vat"NoAccounts with this control kind only. * `payable` - payable * `receivable` - receivable * `suspense_payable` - suspense_payable * `suspense_receivable` - suspense_receivable * `bank` - bank * `transit` - transit * `vat` - vat
cursorstringNoThe `next_cursor` of the previous page. Omit it for the first page.
limitintegerNoThe page size, 1 to 200. Default 50.
searchstringNoA code prefix, or text anywhere in the name.
type"asset" | "liability" | "equity" | "income" | "expense"NoAccounts of this type only. * `asset` - asset * `liability` - liability * `equity` - equity * `income` - income * `expense` - expense

list_dimensions

List dimensions
ReadPermissionbooks.read

The dimension axes, each with all its values. Ordered by code.

A list answers {items, next_cursor}; pass next_cursor back as cursor for the next page.

company_idstringRequired
The id of the company, from list_companies.
activeboolean | null
Active (true) or inactive (false) dimensions only.
cursorstring
The `next_cursor` of the previous page. Omit it for the first page.
kind"project" | "grant" | "client" | "department" | "other"
Dimensions of this kind only. * `project` - project * `grant` - grant * `client` - client * `department` - department * `other` - other
limitinteger
The page size, 1 to 200. Default 50.
Arguments
ArgumentTypeRequiredDescription
company_idstringYesThe id of the company, from list_companies.
activeboolean | nullNoActive (true) or inactive (false) dimensions only.
cursorstringNoThe `next_cursor` of the previous page. Omit it for the first page.
kind"project" | "grant" | "client" | "department" | "other"NoDimensions of this kind only. * `project` - project * `grant` - grant * `client` - client * `department` - department * `other` - other
limitintegerNoThe page size, 1 to 200. Default 50.

Reports

get_balance_sheet

Get the balance sheet
ReadPermissionbooks.read

The balance sheet at a date, in the Estonian scheme. The lines with no amount are left out unless omit_empty is false.

The balance sheet at a date (Estonian scheme 1), with an optional comparison date and a simplified grouping.

company_idstringRequired
The id of the company, from list_companies.
compare_datestring (date)
A second date to compare with, for example the end of the previous year.
datestring (date)Required
The day of the balance sheet.
omit_emptyboolean | null
Leave out the lines whose amount and comparison amount are both 0, and a heading with every row under it when none of its lines is kept. The totals, cash, receivables, issued capital, retained earnings and the profit for the year always show. Default false: the full scheme.
schemastring
A reporting schema key. Default the latest balance sheet schema of the books.
simplifiedboolean | null
Group the statement into a few rows. Default false: the full statutory scheme.
Arguments
ArgumentTypeRequiredDescription
company_idstringYesThe id of the company, from list_companies.
compare_datestring (date)NoA second date to compare with, for example the end of the previous year.
datestring (date)YesThe day of the balance sheet.
omit_emptyboolean | nullNoLeave out the lines whose amount and comparison amount are both 0, and a heading with every row under it when none of its lines is kept. The totals, cash, receivables, issued capital, retained earnings and the profit for the year always show. Default false: the full scheme.
schemastringNoA reporting schema key. Default the latest balance sheet schema of the books.
simplifiedboolean | nullNoGroup the statement into a few rows. Default false: the full statutory scheme.

get_chase_list

Get the chase list
ReadPermissionbooks.read

Every bank movement still in suspense: what to chase a document or a decision for.

company_idstringRequired
The id of the company, from list_companies.
Arguments
ArgumentTypeRequiredDescription
company_idstringYesThe id of the company, from list_companies.

get_general_ledger

Get the general ledger
ReadPermissionbooks.read

The general ledger: each account with its lines and running balance, in the base currency.

company_idstringRequired
The id of the company, from list_companies.
account_codestring
One account only.
date_fromstring (date)
The first day of the range, inclusive. Before it is the opening balance.
date_tostring (date)
The last day of the range, inclusive.
Arguments
ArgumentTypeRequiredDescription
company_idstringYesThe id of the company, from list_companies.
account_codestringNoOne account only.
date_fromstring (date)NoThe first day of the range, inclusive. Before it is the opening balance.
date_tostring (date)NoThe last day of the range, inclusive.

get_open_items

Get the open items
ReadPermissionbooks.read

Every open-item line with its residual, as of a date (as_of, default today), aged at that date.

company_idstringRequired
The id of the company, from list_companies.
account_codestring
Open items on this account only.
as_ofstring (date)
The residuals as of this date: the lines of entries dated by it, the allocations effective by it. Default today.
party_idstring
Open items of this party only.
Arguments
ArgumentTypeRequiredDescription
company_idstringYesThe id of the company, from list_companies.
account_codestringNoOpen items on this account only.
as_ofstring (date)NoThe residuals as of this date: the lines of entries dated by it, the allocations effective by it. Default today.
party_idstringNoOpen items of this party only.

get_profit_and_loss

Get the profit and loss statement
ReadPermissionbooks.read

The income statement of a period, in the Estonian scheme. The lines with no amount are left out unless omit_empty is false.

The income statement of a period (Estonian scheme 1, costs by type), with an optional comparison period and a simplified grouping.

company_idstringRequired
The id of the company, from list_companies.
compare_fromstring (date)
The first day of a period to compare with. Goes with `compare_to`.
compare_tostring (date)
The last day of a period to compare with. Goes with `compare_from`.
date_fromstring (date)Required
The first day of the period.
date_tostring (date)Required
The last day of the period.
omit_emptyboolean | null
Leave out the lines whose amount and comparison amount are both 0, and a heading with every row under it when none of its lines is kept. The totals, cash, receivables, issued capital, retained earnings and the profit for the year always show. Default false: the full scheme.
schemastring
A reporting schema key. Default the latest income statement schema of the books.
simplifiedboolean | null
Group the statement into a few rows. Default false: the full statutory scheme.
Arguments
ArgumentTypeRequiredDescription
company_idstringYesThe id of the company, from list_companies.
compare_fromstring (date)NoThe first day of a period to compare with. Goes with `compare_to`.
compare_tostring (date)NoThe last day of a period to compare with. Goes with `compare_from`.
date_fromstring (date)YesThe first day of the period.
date_tostring (date)YesThe last day of the period.
omit_emptyboolean | nullNoLeave out the lines whose amount and comparison amount are both 0, and a heading with every row under it when none of its lines is kept. The totals, cash, receivables, issued capital, retained earnings and the profit for the year always show. Default false: the full scheme.
schemastringNoA reporting schema key. Default the latest income statement schema of the books.
simplifiedboolean | nullNoGroup the statement into a few rows. Default false: the full statutory scheme.

get_trial_balance

Get the trial balance
ReadPermissionbooks.read

The trial balance of a date range or a period, in the base currency.

company_idstringRequired
The id of the company, from list_companies.
date_fromstring (date)
The first day of the range, inclusive. Before it is the opening balance.
date_tostring (date)
The last day of the range, inclusive.
periodstring
A period code (`2026-03`) or id. Excludes `date_from` and `date_to`.
Arguments
ArgumentTypeRequiredDescription
company_idstringYesThe id of the company, from list_companies.
date_fromstring (date)NoThe first day of the range, inclusive. Before it is the opening balance.
date_tostring (date)NoThe last day of the range, inclusive.
periodstringNoA period code (`2026-03`) or id. Excludes `date_from` and `date_to`.

get_tsd_activity

Get the TSD activity of a month
ReadPermissionbooks.read

Whether the books show, in one calendar month, a fact the TSD of that month declares: payroll or a dividend payment. The income tax on a dividend follows the payment month, not the decision month.

Whether the books show, in one calendar month, a fact that the TSD of that month declares.

The facts are a journal line on the payroll roles and a dividend payment (EE-CIT-012). The income tax on a dividend is declared in the TSD of the payment month, not of the decision month (EE-CIT-016), so the dividend payment covers it. The daily reminder job reminds of the TSD of a month only when one is true, or when the company is set to file a TSD every month (files_tsd_monthly, PL-010). A period that is not one calendar month is 400.

company_idstringRequired
The id of the company, from list_companies.
period_fromstring (date)Required
The first day of the month.
period_tostring (date)Required
The last day of the same month.
Arguments
ArgumentTypeRequiredDescription
company_idstringYesThe id of the company, from list_companies.
period_fromstring (date)YesThe first day of the month.
period_tostring (date)YesThe last day of the same month.

Tax account

get_tax_account

Get the tax account at EMTA
ReadPermissionbooks.read

The tax account of the company at the Estonian Tax and Customs Board (EMTA): the balance of the claims, the interest, the prepayment account, the open claims with their due dates, and a notice of a debt or of a claim due within 7 days. The amounts here are decimal strings in EUR, not minor units. access_status rights_missing means the company has not granted OscarAI access in e-MTA.

The tax account from the stored copy, with its as-of time, the access status and the notices.

Nothing is read from EMTA here: the copy is refreshed every night, after a filing or a tax payment, and by staff. Before the first refresh every amount is null and access_status is never.

company_idstringRequired
The id of the company, from list_companies.
Arguments
ArgumentTypeRequiredDescription
company_idstringYesThe id of the company, from list_companies.

VAT

get_invoice_listing

Get the KMD INF invoice listing
ReadPermissionbooks.read

The invoice listing filed with the KMD for a tax period: part A sales, part B purchases.

The KMD INF annex of a tax period: the invoice listing filed with the KMD.

Part A lists the sales invoices, part B the received invoices, of each partner whose invoices or credit notes of the period reach the threshold without VAT (1000 EUR). Credit notes are negative lines in the period of their own date, at the rate of the original invoice. reconciliation compares each part with the KMD rows of the period, and findings names what a person should check. A period with no KMD form mapped (from 2027) is 409 invalid_state.

company_idstringRequired
The id of the company, from list_companies.
period_fromstring (date)Required
The first day of the tax period.
period_tostring (date)Required
The last day of the tax period.
Arguments
ArgumentTypeRequiredDescription
company_idstringYesThe id of the company, from list_companies.
period_fromstring (date)YesThe first day of the tax period.
period_tostring (date)YesThe last day of the tax period.

get_vat_registration

Get the VAT registration
ReadPermissionbooks.read

The VAT status of the company on a day (registered, limited or unregistered), its VAT number and every registration record. The VAT rules follow the status on each tax point.

The VAT registration of the company by date: the status on as_of, the status at creation, and every record.

A registration, a limited registration or a deregistration is recorded with POST vat-registrations (record_vat_registration). The VAT rules follow the status on the tax point of each invoice.

company_idstringRequired
The id of the company, from list_companies.
as_ofstring (date)
The day of `status`. Default: the latest status by date.
Arguments
ArgumentTypeRequiredDescription
company_idstringYesThe id of the company, from list_companies.
as_ofstring (date)NoThe day of `status`. Default: the latest status by date.

get_vat_return

Get a VAT return
ReadPermissionbooks.read

One VAT return with its boxes.

company_idstringRequired
The id of the company, from list_companies.
vat_return_idstringRequired
The core ULID of the object, 26 characters.
Arguments
ArgumentTypeRequiredDescription
company_idstringYesThe id of the company, from list_companies.
vat_return_idstringYesThe core ULID of the object, 26 characters.

get_vat_threshold

Get the VAT registration threshold watch
ReadPermissionbooks.read

The turnover of the calendar year against the 40 000 EUR registration threshold, the day it was exceeded and the application deadline, the limited registration duty, and whether a deregistration is possible.

The VAT registration threshold watch of the calendar year of as_of.

The turnover with a place of supply in Estonia from 1 January counts toward 40 000 EUR (EE-VAT-007). The day it exceeds it is the day the duty to register arose, and the application is due 3 working days later (EE-VAT-008). The intra-Community acquisitions above 10 000 EUR, or a service bought from a foreign business, need a limited registration (EE-VAT-010). deregistration_possible says whether the turnover allows a deregistration (EE-VAT-011). findings names what a person must do.

company_idstringRequired
The id of the company, from list_companies.
as_ofstring (date)Required
The day of the watch. The turnover counts from 1 January of its year.
Arguments
ArgumentTypeRequiredDescription
company_idstringYesThe id of the company, from list_companies.
as_ofstring (date)YesThe day of the watch. The turnover counts from 1 January of its year.

get_vd_report

Get the VD report
ReadPermissionbooks.read

The intra-Community supplies of one month (until 12.2026): one line per EU customer VAT number.

The VD report of a month: the intra-Community supplies (until 12.2026).

One line for each customer VAT number, with the goods amount and the services amount of the month, in whole euros, from the VAT codes of the EC sales list. A credit note is a negative amount in the month of its own date. A correction of an invoice of an earlier month is listed in corrections, because it goes on a VDP correction report for that month. reconciliation compares the amounts with KMD rows 3.1.1 and 3.1, and findings names what a person should check. A period that is not one calendar month is 400; a month from 2027, when the VD data moves into the KMD data set, is 409 invalid_state.

company_idstringRequired
The id of the company, from list_companies.
period_fromstring (date)Required
The first day of the month.
period_tostring (date)Required
The last day of the same month.
Arguments
ArgumentTypeRequiredDescription
company_idstringYesThe id of the company, from list_companies.
period_fromstring (date)YesThe first day of the month.
period_tostring (date)YesThe last day of the same month.

list_vat_returns

List VAT returns
ReadPermissionbooks.read

The VAT returns, ordered by period and revision; ordering=-period_from is newest first.

A list answers {items, next_cursor}; pass next_cursor back as cursor for the next page.

company_idstringRequired
The id of the company, from list_companies.
cursorstring
The `next_cursor` of the previous page. Omit it for the first page.
date_fromstring (date)
The earliest start of the return period, inclusive.
date_tostring (date)
The latest start of the return period, inclusive.
formstring
Returns of this form only (`KMD`).
limitinteger
The page size, 1 to 200. Default 50.
ordering"period_from" | "-period_from"
`period_from` (the default) is oldest first, `-period_from` newest first. The id breaks ties. * `period_from` - period_from * `-period_from` - -period_from
state"draft" | "prepared" | "filed" | "amended"
Returns in this state only. * `draft` - draft * `prepared` - prepared * `filed` - filed * `amended` - amended
Arguments
ArgumentTypeRequiredDescription
company_idstringYesThe id of the company, from list_companies.
cursorstringNoThe `next_cursor` of the previous page. Omit it for the first page.
date_fromstring (date)NoThe earliest start of the return period, inclusive.
date_tostring (date)NoThe latest start of the return period, inclusive.
formstringNoReturns of this form only (`KMD`).
limitintegerNoThe page size, 1 to 200. Default 50.
ordering"period_from" | "-period_from"No`period_from` (the default) is oldest first, `-period_from` newest first. The id breaks ties. * `period_from` - period_from * `-period_from` - -period_from
state"draft" | "prepared" | "filed" | "amended"NoReturns in this state only. * `draft` - draft * `prepared` - prepared * `filed` - filed * `amended` - amended

preview_vat_return

Preview a VAT return
ReadPermissionbooks.read

What preparing the VAT return of a period would write, without writing it.

company_idstringRequired
The id of the company, from list_companies.
formstring
The return form. Default the company's form (`KMD`).
period_fromstring (date)Required
The first day of the return period.
period_tostring (date)Required
The last day of the return period.
Arguments
ArgumentTypeRequiredDescription
company_idstringYesThe id of the company, from list_companies.
formstringNoThe return form. Default the company's form (`KMD`).
period_fromstring (date)YesThe first day of the return period.
period_tostring (date)YesThe last day of the return period.