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.
Alerts
list_alerts
List alertsbooks.readWhat 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.
| Argument | Type | Required | Description |
|---|---|---|---|
| company_id | string | Yes | The id of the company, from list_companies. |
| cursor | string | No | 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" | No | Only this kind. |
| limit | integer | No | Number of results to return per page. |
| state | "dismissed" | "open" | "resolved" | No | Only this state. |
Allocations
allocate
Allocate an open itemallocations.writeA 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.
| Argument | Type | Required | Description |
|---|---|---|---|
| company_id | string | Yes | The id of the company, from list_companies. |
| kind | "payment" | "refund" | "credit_offset" | "prepayment_apply" | No | Default `payment`. * `payment` - payment * `refund` - refund * `credit_offset` - credit_offset * `prepayment_apply` - prepayment_apply |
| item_line_id | string | Yes | |
| counter_line_id | string | Yes | |
| item_minor | integer | Yes | |
| counter_minor | integer | null | No | |
| rate_source | "statement" | "rate_table" | "manual" | "same" | null | No | |
| adjustment_kind | "none" | "discount" | "writeoff" | "rounding" | No | Default `none`. * `none` - none * `discount` - discount * `writeoff` - writeoff * `rounding` - rounding |
| adjustment_base_minor | integer | null | No | |
| effective_date | string (date) | Yes | |
| origin | "human" | "matcher" | "import" | "migration" | No | Default `human`. * `human` - human * `matcher` - matcher * `import` - import * `migration` - migration |
| confidence | string (decimal) | null | string | No | |
| note | string | null | No | |
| idempotency_key | string | No | Optional. 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 invoicesbooks.readHow 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.
| Argument | Type | Required | Description |
|---|---|---|---|
| company_id | string | Yes | The id of the company, from list_companies. |
| invoice_id | string | No | The settlement of this invoice only. |
unallocate
Reverse an allocationallocations.writeRuns 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.
| Argument | Type | Required | Description |
|---|---|---|---|
| allocation_id | string | Yes | A core id (ULID). |
| company_id | string | Yes | The id of the company, from list_companies. |
| reason | string | null | No | |
| idempotency_key | string | No | Optional. 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 rulesbank.classifyBooks 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.
| Argument | Type | Required | Description |
|---|---|---|---|
| company_id | string | Yes | The id of the company, from list_companies. |
| bank_account_id | string | Yes | |
| to | string (date) | Yes | The last booking date, inclusive. |
| mode | "unclassified" | "reclassify" | Yes | * `unclassified` - unclassified * `reclassify` - reclassify |
| reason | string | null | No | |
| from | string (date) | Yes | The first booking date, inclusive. |
| idempotency_key | string | No | Optional. 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 transactionbooks.readOne 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.
| Argument | Type | Required | Description |
|---|---|---|---|
| bank_transaction_id | string | Yes | The core ULID of the object, 26 characters. |
| company_id | string | Yes | The id of the company, from list_companies. |
list_bank_accounts
List bank accountsbooks.readThe 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.
| Argument | Type | Required | Description |
|---|---|---|---|
| company_id | string | Yes | The id of the company, from list_companies. |
| active | boolean | null | No | Active (true) or inactive (false) bank accounts only. |
| cursor | string | No | The `next_cursor` of the previous page. Omit it for the first page. |
| limit | integer | No | The page size, 1 to 200. Default 50. |
list_bank_transactions
List bank transactionsbooks.readThe 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`.
| Argument | Type | Required | Description |
|---|---|---|---|
| company_id | string | Yes | The id of the company, from list_companies. |
| bank_account_id | string | No | Transactions of this bank account only. |
| cursor | string | No | The `next_cursor` of the previous page. Omit it for the first page. |
| date_from | string (date) | No | The earliest booking date, inclusive. |
| date_to | string (date) | No | The latest booking date, inclusive. |
| direction | "in" | "out" | No | Money in or money out only. * `in` - in * `out` - out |
| has_document | boolean | null | No | Only transactions an uploaded file explains (true) or that none explains (false). |
| limit | integer | No | The 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_id | string | No | Transactions of this party only. |
| q | string | No | 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_id | string | No | Transactions of this statement only. |
| status | "unmatched" | "part_matched" | "matched" | "exempted" | "classified" | "transfer_matched" | "transfer_unmatched" | "posted" | "open" | No | 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_explain | boolean | null | No | The 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 feedbooks.readThe 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`).
| Argument | Type | Required | Description |
|---|---|---|---|
| company_id | string | Yes | The id of the company, from list_companies. |
| as_of | string (date) | No | The day of `in_force` and of the order. Default: today. |
| bank_account_id | string | Yes | A payment provider feed (provider `stripe`). |
match_transfer
Match a transferbank.classifyRuns 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.
| Argument | Type | Required | Description |
|---|---|---|---|
| company_id | string | Yes | The id of the company, from list_companies. |
| out_transaction_id | string | Yes | |
| in_transaction_id | string | Yes | |
| note | string | null | No | |
| idempotency_key | string | No | Optional. 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 transactionbank.classifyRuns 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.
| Argument | Type | Required | Description |
|---|---|---|---|
| bank_transaction_id | string | Yes | A core id (ULID). |
| company_id | string | Yes | The id of the company, from list_companies. |
| party_id | string | null | No | |
| source | string | Yes | |
| idempotency_key | string | No | Optional. 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 companyorganization.readOne company: name, legal data and state.
Return the company.
- company_idstringRequired
- The id of the company, from list_companies.
| Argument | Type | Required | Description |
|---|---|---|---|
| company_id | string | Yes | The id of the company, from list_companies. |
list_companies
List companiesorganization.readThe 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.
| Argument | Type | Required | Description |
|---|---|---|---|
| cursor | string | No | The pagination cursor value. |
| limit | integer | No | Number of results to return per page. |
Dividends
get_dividend_report
Get the dividends of a payment monthbooks.readThe 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.
| Argument | Type | Required | Description |
|---|---|---|---|
| company_id | string | Yes | The id of the company, from list_companies. |
| period_from | string (date) | Yes | The first day of the month. |
| period_to | string (date) | Yes | The last day of the same month. |
Documents
get_document_record
Get a document recordbooks.readOne 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.
| Argument | Type | Required | Description |
|---|---|---|---|
| company_id | string | Yes | The id of the company, from list_companies. |
| document_id | string | Yes | The core ULID of the object, 26 characters. |
get_inbox
Get the invoice inboxdocuments.readThe 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.
| Argument | Type | Required | Description |
|---|---|---|---|
| company_id | string | Yes | The id of the company, from list_companies. |
list_document_records
List document recordsbooks.readThe 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.
| Argument | Type | Required | Description |
|---|---|---|---|
| company_id | string | Yes | The id of the company, from list_companies. |
| bank_feed | boolean | null | No | 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. |
| cursor | string | No | The `next_cursor` of the previous page. Omit it for the first page. |
| kind | "invoice" | "receipt" | "credit_note" | "statement" | "contract" | "other" | No | Documents of this kind only. * `invoice` - invoice * `receipt` - receipt * `credit_note` - credit_note * `statement` - statement * `contract` - contract * `other` - other |
| limit | integer | No | The 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_from | string (date) | No | The earliest received date, inclusive. Leaves out documents without one. |
| received_to | string (date) | No | The latest received date, inclusive. Leaves out documents without one. |
| referenced | boolean | null | No | Only documents the books refer to (true: booked) or that nothing refers to yet (false: to book). |
| sha256 | string | No | The SHA-256 of the file, lowercase hex. |
list_inbound_emails
List inbound emailsdocuments.readThe 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.
| Argument | Type | Required | Description |
|---|---|---|---|
| company_id | string | Yes | The id of the company, from list_companies. |
| cursor | string | No | The pagination cursor value. |
| limit | integer | No | Number of results to return per page. |
record_document
Record a documentdocuments.writeRuns 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.
| Argument | Type | Required | Description |
|---|---|---|---|
| company_id | string | Yes | The id of the company, from list_companies. |
| sha256 | string | Yes | |
| kind | string | Yes | |
| filename | string | Yes | |
| media_type | string | Yes | |
| size_bytes | integer | Yes | |
| storage_ref | string | Yes | |
| legacy_sha1 | string | null | No | |
| received_on | string (date) | null | string | No | |
| document_date | string (date) | null | string | No | The date the document was issued; it starts the retention periods. |
| retention_until | string (date) | null | string | No | A later retention date the caller needs; the core computes its own and keeps the later. |
| legal_hold | boolean | No | |
| idempotency_key | string | No | Optional. 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 employeebooks.readThe 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
| Argument | Type | Required | Description |
|---|---|---|---|
| company_id | string | Yes | The id of the company, from list_companies. |
| employee_id | string | Yes |
get_employee_submission
Get the status of an employee submissionbooks.readOne 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
| Argument | Type | Required | Description |
|---|---|---|---|
| company_id | string | Yes | The id of the company, from list_companies. |
| submission_id | string | Yes |
list_employee_submissions
List employee submissionsbooks.readThe 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.
| Argument | Type | Required | Description |
|---|---|---|---|
| company_id | string | Yes | The id of the company, from list_companies. |
| cursor | string | No | The pagination cursor value. |
| limit | integer | No | Number of results to return per page. |
list_employees
List employeesbooks.readThe 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.
| Argument | Type | Required | Description |
|---|---|---|---|
| company_id | string | Yes | The id of the company, from list_companies. |
| cursor | string | No | The pagination cursor value. |
| limit | integer | No | Number of results to return per page. |
submit_employee
Submit an employee or a changeemployees.submitSubmits 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.
| Argument | Type | Required | Description |
|---|---|---|---|
| company_id | string | Yes | The 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_id | string | No | A new employment: the employee. |
| employment_id | string | No | A change, a suspension, an end: the employment. |
| employee | object | No | The person of a new employee, or the changed fields of an employee. |
| employment | object | No | The employment of a start, or the changed fields of an employment. |
| suspension | object | No | A suspension of an employment. |
| end | object | No | The end of an employment. |
| event_date | string (date) | No | A change: the day it applies from. Default today. |
| idempotency_key | string | No | Optional. 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 statusbooks.readWhat 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.
| Argument | Type | Required | Description |
|---|---|---|---|
| company_id | string | Yes | The id of the company, from list_companies. |
| through | string | No | The 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 assetbooks.readOne 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.
| Argument | Type | Required | Description |
|---|---|---|---|
| company_id | string | Yes | The id of the company, from list_companies. |
| fixed_asset_id | string | Yes | The core ULID of the object, 26 characters. |
| as_of | string (date) | No | The day of the amounts; the months before its month are due. Default: today. |
get_fixed_asset_movements
Get the fixed asset movement tablebooks.readThe 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.
| Argument | Type | Required | Description |
|---|---|---|---|
| company_id | string | Yes | The id of the company, from list_companies. |
| date_from | string (date) | Yes | The first day of the range. |
| date_to | string (date) | Yes | The last day of the range. |
get_fixed_asset_schedule
Get the depreciation schedule of a fixed assetbooks.readEach 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.
| Argument | Type | Required | Description |
|---|---|---|---|
| company_id | string | Yes | The id of the company, from list_companies. |
| fixed_asset_id | string | Yes | The core ULID of the object, 26 characters. |
| as_of | string (date) | No | The day the due months end at: the months before its month are due. Default: today. |
| month_from | string | No | The first month, `YYYY-MM`. Default: the first month of depreciation. |
| month_to | string | No | The last month, `YYYY-MM`. Default: the end of the useful life. At most 1200 months. |
list_fixed_asset_groups
List fixed asset groupsbooks.readThe 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.
| Argument | Type | Required | Description |
|---|---|---|---|
| company_id | string | Yes | The id of the company, from list_companies. |
| on | string (date) | No | The day the groups are in force on. Default: the latest version of each group. |
list_fixed_assets
List fixed assetsbooks.readThe 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
| Argument | Type | Required | Description |
|---|---|---|---|
| company_id | string | Yes | The id of the company, from list_companies. |
| as_of | string (date) | No | The day of the amounts. Default: today in the time zone of the books. |
| class | "tangible" | "intangible" | "investment_property" | No | Assets of this class only. * `tangible` - tangible * `intangible` - intangible * `investment_property` - investment_property |
| cursor | string | No | The `next_cursor` of the previous page. Omit it for the first page. |
| group | string | No | The code of a fixed asset group. |
| limit | integer | No | The page size, 1 to 200. Default 50. |
| status | "planned" | "in_use" | "withdrawn" | "disposed" | No | Assets in this status only. * `planned` - planned * `in_use` - in_use * `withdrawn` - withdrawn * `disposed` - disposed |
preview_depreciation
Preview a depreciation schedulebooks.readThe 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
| Argument | Type | Required | Description |
|---|---|---|---|
| company_id | string | Yes | The id of the company, from list_companies. |
| cost_minor | integer | Yes | The 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_bps | integer | No | |
| ready_for_use_date | string (date) | Yes | |
| residual_value_minor | integer | No | |
| useful_life_months | integer | No |
Invoices
cancel_invoice
Cancel a draft invoiceinvoices.post_purchase or invoices.writeinvoices.post_purchaseorinvoices.writeRuns 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.
| Argument | Type | Required | Description |
|---|---|---|---|
| company_id | string | Yes | The id of the company, from list_companies. |
| invoice_id | string | Yes | A core id (ULID). |
| reason | string | Yes | |
| idempotency_key | string | No | Optional. 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 invoicebooks.readOne 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.
| Argument | Type | Required | Description |
|---|---|---|---|
| company_id | string | Yes | The id of the company, from list_companies. |
| invoice_id | string | Yes | The core ULID of the object, 26 characters. |
get_invoice_issue_deadlines
Get the sales invoices to issuebooks.readThe 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.
| Argument | Type | Required | Description |
|---|---|---|---|
| company_id | string | Yes | The id of the company, from list_companies. |
| as_of | string (date) | Yes | The day: the supplies made by it are due to be invoiced. |
import_sales_invoice
Import a sales invoice issued elsewhereinvoices.issueRecords, 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.
| Argument | Type | Required | Description |
|---|---|---|---|
| company_id | string | Yes | The id of the company, from list_companies. |
| series | string | Yes | 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 `-`. |
| number | string | Yes | The number the invoice carries. Unique in its series; never a number of the Oscar series. |
| kind | string | No | Default `invoice`; `credit_note` names `corrects_invoice_id`. |
| party_id | string | Yes | |
| corrects_invoice_id | string | null | No | |
| seller_snapshot | any | null | No | |
| buyer_snapshot | any | null | No | |
| revision | object | Yes | The facts of the invoice. `invoice_date` is the external issue date; `documents` holds the original document (role `original`). |
| idempotency_key | string | No | Optional. 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 invoiceinvoices.issueRuns 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.
| Argument | Type | Required | Description |
|---|---|---|---|
| company_id | string | Yes | The id of the company, from list_companies. |
| invoice_id | string | Yes | A core id (ULID). |
| number | string | null | No | Only under a `free` numbering policy. |
| seller_snapshot | any | null | No | |
| buyer_snapshot | any | null | No | |
| seller_address | string | null | No | 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_key | string | No | Optional. 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 invoicesbooks.readThe 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
| Argument | Type | Required | Description |
|---|---|---|---|
| company_id | string | Yes | The id of the company, from list_companies. |
| cursor | string | No | The `next_cursor` of the previous page. Omit it for the first page. |
| date_from | string (date) | No | The earliest invoice date, inclusive. |
| date_to | string (date) | No | The latest invoice date, inclusive. |
| direction | "purchase" | "sales" | No | Purchase or sales invoices only. * `purchase` - purchase * `sales` - sales |
| external_source_prefix | string | No | Imported invoices whose external series starts with this text: `stripe` selects every Stripe series. |
| kind | "invoice" | "receipt" | "credit_note" | "prepayment" | No | Invoices of this kind only. * `invoice` - invoice * `receipt` - receipt * `credit_note` - credit_note * `prepayment` - prepayment |
| limit | integer | No | The page size, 1 to 200. Default 50. |
| needs_review | boolean | null | No | Only invoices that need review (true) or that do not (false). |
| number | string | No | The 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_id | string | No | Invoices of this party only. |
| settlement | "unposted" | "unpaid" | "part_paid" | "paid" | "open" | "overdue" | No | 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" | No | Invoices in this state only. * `recorded` - recorded * `issued` - issued * `posted` - posted * `cancelled` - cancelled * `void` - void |
post_invoice
Post an invoiceinvoices.issue or invoices.post_purchaseinvoices.issueorinvoices.post_purchaseRuns 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.
| Argument | Type | Required | Description |
|---|---|---|---|
| company_id | string | Yes | The id of the company, from list_companies. |
| invoice_id | string | Yes | A core id (ULID). |
| cleared_by_bank_transaction_id | string | null | No | |
| idempotency_key | string | No | Optional. 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 invoiceinvoices.writeRecords 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.
| Argument | Type | Required | Description |
|---|---|---|---|
| company_id | string | Yes | The id of the company, from list_companies. |
| direction | string | Yes | `sales` or `purchase`. |
| kind | string | No | Default `invoice`. |
| party_id | string | Yes | |
| number | string | null | No | |
| corrects_invoice_id | string | null | No | |
| origin | string | No | Default `human`. |
| revision | object | Yes | The content of an invoice: one revision. A chosen `exchange_rate_id` is a human judgement. |
| idempotency_key | string | No | Optional. 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 invoiceinvoices.writeRuns 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.
| Argument | Type | Required | Description |
|---|---|---|---|
| company_id | string | Yes | The id of the company, from list_companies. |
| invoice_id | string | Yes | A core id (ULID). |
| reason | string | Yes | |
| party_id | string | null | No | |
| revision | object | Yes | The content of an invoice: one revision. A chosen `exchange_rate_id` is a human judgement. |
| idempotency_key | string | No | Optional. 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 booksbooks.readThe 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.
| Argument | Type | Required | Description |
|---|---|---|---|
| company_id | string | Yes | The id of the company, from list_companies. |
get_entry
Get a journal entrybooks.readOne 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.
| Argument | Type | Required | Description |
|---|---|---|---|
| company_id | string | Yes | The id of the company, from list_companies. |
| entry_id | string | Yes | The core ULID of the object, 26 characters. |
list_entries
List journal entriesbooks.readThe 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
| Argument | Type | Required | Description |
|---|---|---|---|
| company_id | string | Yes | The id of the company, from list_companies. |
| account_code | string | No | Entries with at least one line on this account. |
| bank_transaction_id | string | No | Entries posted from this bank transaction. |
| cursor | string | No | The `next_cursor` of the previous page. Omit it for the first page. |
| date_from | string (date) | No | The earliest economic date, inclusive. |
| date_to | string (date) | No | The latest economic date, inclusive. |
| invoice_id | string | No | Entries posted from any revision of this invoice. |
| journal | "purchases" | "sales" | "bank" | "general" | "opening" | "closing" | No | Entries of this journal only. * `purchases` - purchases * `sales` - sales * `bank` - bank * `general` - general * `opening` - opening * `closing` - closing |
| limit | integer | No | The 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_id | string | No | Entries with at least one line naming this party. |
| period | string | No | A period code (`2026-03`) or id. |
| source_id | string | No | Entries posted from this source row only. |
| source_kind | "invoice_revision" | "bank_transaction" | "allocation" | "transaction_exemption" | "transaction_money_in" | "accounting_event" | "vat_return" | No | 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" | No | Entries with this role only. * `primary` - primary * `reversal` - reversal * `replacement` - replacement |
| state | "posted" | "reversed" | No | Posted or reversed entries only. * `posted` - posted * `reversed` - reversed |
verify_books
Verify the booksbooks.readRuns 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.
| Argument | Type | Required | Description |
|---|---|---|---|
| company_id | string | Yes | The id of the company, from list_companies. |
Parties
create_party
Create a partyparties.writeRuns 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.
| Argument | Type | Required | Description |
|---|---|---|---|
| company_id | string | Yes | The id of the company, from list_companies. |
| name | string | Yes | |
| kind | "supplier" | "customer" | "employee" | "authority" | "group_company" | "other" | Yes | * `supplier` - supplier * `customer` - customer * `employee` - employee * `authority` - authority * `group_company` - group_company * `other` - other |
| country | string | null | No | |
| vat_area | string | null | No | |
| vat_number | string | null | No | |
| reg_code | string | null | No | |
| expects_document | boolean | No | Default true. |
| is_confirmed | boolean | No | |
| notes | string | null | No | |
| external_key | string | null | No | 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_persons | boolean | No | The party pools private persons (card buyers): the KMD INF annex leaves it out. No registry code. Default false. |
| address | string | null | No | The postal address printed on an invoice, one or more lines; the country is `country`. At most 500 characters. |
| string | null | No | 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`. | |
| phone | string | null | No | 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_key | string | No | Optional. 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 partybooks.readOne 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.
| Argument | Type | Required | Description |
|---|---|---|---|
| company_id | string | Yes | The id of the company, from list_companies. |
| party_id | string | Yes | The core ULID of the object, 26 characters. |
list_parties
List partiesbooks.readCustomers, 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.
| Argument | Type | Required | Description |
|---|---|---|---|
| company_id | string | Yes | The id of the company, from list_companies. |
| cursor | string | No | The `next_cursor` of the previous page. Omit it for the first page. |
| exclude_kind | "supplier" | "customer" | "employee" | "authority" | "group_company" | "other" | No | 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_key | string | No | The exact key of the party in another system. |
| include_merged | boolean | null | No | Include parties merged into another. Default false. |
| include_settled_external | boolean | null | No | 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" | No | Parties of this kind only. * `supplier` - supplier * `customer` - customer * `employee` - employee * `authority` - authority * `group_company` - group_company * `other` - other |
| limit | integer | No | The page size, 1 to 200. Default 50. |
| reg_code | string | No | The exact registry code. |
| role | "supplier" | "customer" | No | Only the parties that play this role, as `roles` derives it from the kind and the invoices. * `supplier` - supplier * `customer` - customer |
| search | string | No | Text anywhere in the name, or in the cleaned matching key. |
| vat_number | string | No | The exact VAT number. |
Payments
get_payment_connection
Get a payment connectionpayments.readStart 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.
| Argument | Type | Required | Description |
|---|---|---|---|
| company_id | string | Yes | The id of the company, from list_companies. |
| connection_id | string | Yes | The sqid of the connection. |
get_payment_sync_run
Get a sync runpayments.readOne 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.
| Argument | Type | Required | Description |
|---|---|---|---|
| company_id | string | Yes | The id of the company, from list_companies. |
| connection_id | string | Yes | The sqid of the connection. |
| run_id | string | Yes | The sqid of the run. |
get_stripe_document
Get a Stripe invoice or credit note of a connectionpayments.readOne 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.
| Argument | Type | Required | Description |
|---|---|---|---|
| company_id | string | Yes | The id of the company, from list_companies. |
| connection_id | string | Yes | The sqid of the connection. |
| document_id | string | Yes | The sqid of the import row. |
get_stripe_documents_summary
Get the summary of the Stripe invoices of a connectionpayments.readThe 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.
| Argument | Type | Required | Description |
|---|---|---|---|
| company_id | string | Yes | The id of the company, from list_companies. |
| connection_id | string | Yes | The sqid of the connection. |
get_stripe_invoice_import
Get the Stripe import of an invoicebooks.readFor 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).
| Argument | Type | Required | Description |
|---|---|---|---|
| company_id | string | Yes | The id of the company, from list_companies. |
| invoice_id | string | Yes | The invoice in the books (a ULID). |
list_payment_connections
List payment connectionspayments.readThe 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.
| Argument | Type | Required | Description |
|---|---|---|---|
| company_id | string | Yes | The id of the company, from list_companies. |
| cursor | string | No | |
| limit | integer | No | Number of results to return per page. |
list_payment_sync_runs
List the sync runs of a connectionpayments.readThe 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
| Argument | Type | Required | Description |
|---|---|---|---|
| company_id | string | Yes | The id of the company, from list_companies. |
| connection_id | string | Yes | The sqid of the connection. |
| cursor | string | No |
list_stripe_customers
List the Stripe customers of a connectionpayments.readA 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
| Argument | Type | Required | Description |
|---|---|---|---|
| company_id | string | Yes | The id of the company, from list_companies. |
| connection_id | string | Yes | The sqid of the connection. |
| cursor | string | No |
list_stripe_documents
List the Stripe invoices and credit notes of a connectionpayments.readAnswers 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
| Argument | Type | Required | Description |
|---|---|---|---|
| company_id | string | Yes | The id of the company, from list_companies. |
| connection_id | string | Yes | The sqid of the connection. |
| block_code | string | No | |
| cursor | string | No | |
| date_from | string (date) | No | The earliest invoice date, inclusive. |
| date_to | string (date) | No | The latest invoice date, inclusive. |
| invoice_id | string | No | The 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_id | string | No |
list_stripe_fee_invoices
List the Stripe fee invoices of a connectionpayments.readThe 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.
| Argument | Type | Required | Description |
|---|---|---|---|
| company_id | string | Yes | The id of the company, from list_companies. |
| connection_id | string | Yes | The sqid of the connection. |
list_stripe_payouts
List the Stripe payouts of a connectionpayments.readEach 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
| Argument | Type | Required | Description |
|---|---|---|---|
| company_id | string | Yes | The id of the company, from list_companies. |
| connection_id | string | Yes | The sqid of the connection. |
| cursor | string | No | |
| 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 connectionpayments.readHow 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.
| Argument | Type | Required | Description |
|---|---|---|---|
| company_id | string | Yes | The id of the company, from list_companies. |
| connection_id | string | Yes | The sqid of the connection. |
list_stripe_transactions
List the Stripe transactions of a connectionpayments.readAnswers 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
| Argument | Type | Required | Description |
|---|---|---|---|
| company_id | string | Yes | The id of the company, from list_companies. |
| connection_id | string | Yes | The sqid of the connection. |
| bank_transaction_id | string | No | The line of the Stripe feed (a ULID). |
| category | string | No | |
| classification | "rule" | "deferred" | "suspense" | "posted" | "conflict" | "allocated" | No | * `rule` - Rule receipt * `deferred` - Deferred * `suspense` - Suspense * `posted` - Posted * `conflict` - Conflict * `allocated` - Allocated |
| cursor | string | No |
request_payment_sync
Sync a payment connection nowpayments.manageQueues 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.
| Argument | Type | Required | Description |
|---|---|---|---|
| company_id | string | Yes | The id of the company, from list_companies. |
| connection_id | string | Yes | The sqid of the connection. |
| idempotency_key | string | No | Optional. 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 invoiceinvoices.writeRuns 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.
| Argument | Type | Required | Description |
|---|---|---|---|
| company_id | string | Yes | The id of the company, from list_companies. |
| connection_id | string | Yes | The sqid of the connection. |
| document_id | string | Yes | The sqid of the import row. |
| idempotency_key | string | No | Optional. 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 runbooks.readThe 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
| Argument | Type | Required | Description |
|---|---|---|---|
| company_id | string | Yes | The id of the company, from list_companies. |
| pay_run_id | string | Yes |
list_pay_runs
List pay runsbooks.readThe 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.
| Argument | Type | Required | Description |
|---|---|---|---|
| company_id | string | Yes | The id of the company, from list_companies. |
| cursor | string | No | The pagination cursor value. |
| limit | integer | No | Number of results to return per page. |
Periods
list_periods
List periodsbooks.readThe 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
| Argument | Type | Required | Description |
|---|---|---|---|
| company_id | string | Yes | The id of the company, from list_companies. |
| cursor | string | No | The `next_cursor` of the previous page. Omit it for the first page. |
| date | string (date) | No | The period that contains this date. |
| fiscal_year | string | No | The fiscal year label (`2026`). |
| limit | integer | No | The page size, 1 to 200. Default 50. |
| state | "open" | "soft_closed" | "locked" | No | Periods in this state only. * `open` - open * `soft_closed` - soft_closed * `locked` - locked |
Proposals
get_proposal
Get a proposalbooks.readOne proposal.
- company_idstringRequired
- The id of the company, from list_companies.
- proposal_idstringRequired
| Argument | Type | Required | Description |
|---|---|---|---|
| company_id | string | Yes | The id of the company, from list_companies. |
| proposal_id | string | Yes |
list_proposals
List proposalsbooks.readThe 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.
| Argument | Type | Required | Description |
|---|---|---|---|
| company_id | string | Yes | The id of the company, from list_companies. |
| cursor | string | No | The pagination cursor value. |
| limit | integer | No | Number of results to return per page. |
| status | "confirmed" | "pending" | "rejected" | No | Only the proposals in this status. |
propose_judgement
Propose a judgementallocations.write or bank.classify or parties.writeallocations.writeorbank.classifyorparties.writeProposes 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.
| Argument | Type | Required | Description |
|---|---|---|---|
| company_id | string | Yes | 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" | Yes | The command a person should run. |
| payload | object | Yes | 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. |
| note | string | No | Why you propose it, for the person who decides. |
| idempotency_key | string | No | Optional. 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 proposalreconciliation.decideAllocates 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.
| Argument | Type | Required | Description |
|---|---|---|---|
| company_id | string | Yes | The id of the company, from list_companies. |
| proposal_id | string | Yes | The sqid of the match proposal. |
| pairs | array of object | No | 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_key | string | No | Optional. 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 proposalsbooks.readThe 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`.
| Argument | Type | Required | Description |
|---|---|---|---|
| company_id | string | Yes | The id of the company, from list_companies. |
| bank_transaction_id | string | No | Only the proposals of this bank transaction (its core id). |
| cursor | string | No | The pagination cursor value. |
| limit | integer | No | Number of results to return per page. |
| status | "applying" | "auto_applied" | "confirmed" | "no_match" | "pending" | "rejected" | "superseded" | "undone" | No | Only the proposals in this status. Without it, every status but `no_match`. |
reject_match_proposal
Reject a match proposalreconciliation.decideMarks 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.
| Argument | Type | Required | Description |
|---|---|---|---|
| company_id | string | Yes | The id of the company, from list_companies. |
| proposal_id | string | Yes | The sqid of the match proposal. |
| idempotency_key | string | No | Optional. 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 matchreconciliation.decideReverses 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.
| Argument | Type | Required | Description |
|---|---|---|---|
| company_id | string | Yes | The id of the company, from list_companies. |
| proposal_id | string | Yes | The sqid of the match proposal. |
| idempotency_key | string | No | Optional. 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 ratebooks.readThe 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
| Argument | Type | Required | Description |
|---|---|---|---|
| company_id | string | Yes | The id of the company, from list_companies. |
| currency | string | Yes | The ISO code of the foreign currency. |
| rate_date | string (date) | Yes | The day of the rate. |
| source | "ecb" | "market" | "bank" | "implied" | "manual" | No | The source of the rate. Default `ecb`. * `ecb` - ecb * `market` - market * `bank` - bank * `implied` - implied * `manual` - manual |
list_accounts
List accountsbooks.readThe 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
| Argument | Type | Required | Description |
|---|---|---|---|
| company_id | string | Yes | The id of the company, from list_companies. |
| active | boolean | null | No | Active (true) or inactive (false) accounts only. |
| control_kind | "payable" | "receivable" | "suspense_payable" | "suspense_receivable" | "bank" | "transit" | "vat" | No | Accounts with this control kind only. * `payable` - payable * `receivable` - receivable * `suspense_payable` - suspense_payable * `suspense_receivable` - suspense_receivable * `bank` - bank * `transit` - transit * `vat` - vat |
| cursor | string | No | The `next_cursor` of the previous page. Omit it for the first page. |
| limit | integer | No | The page size, 1 to 200. Default 50. |
| search | string | No | A code prefix, or text anywhere in the name. |
| type | "asset" | "liability" | "equity" | "income" | "expense" | No | Accounts of this type only. * `asset` - asset * `liability` - liability * `equity` - equity * `income` - income * `expense` - expense |
list_dimensions
List dimensionsbooks.readThe 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.
| Argument | Type | Required | Description |
|---|---|---|---|
| company_id | string | Yes | The id of the company, from list_companies. |
| active | boolean | null | No | Active (true) or inactive (false) dimensions only. |
| cursor | string | No | The `next_cursor` of the previous page. Omit it for the first page. |
| kind | "project" | "grant" | "client" | "department" | "other" | No | Dimensions of this kind only. * `project` - project * `grant` - grant * `client` - client * `department` - department * `other` - other |
| limit | integer | No | The page size, 1 to 200. Default 50. |
Reports
get_balance_sheet
Get the balance sheetbooks.readThe 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.
| Argument | Type | Required | Description |
|---|---|---|---|
| company_id | string | Yes | The id of the company, from list_companies. |
| compare_date | string (date) | No | A second date to compare with, for example the end of the previous year. |
| date | string (date) | Yes | The day of the balance sheet. |
| omit_empty | boolean | null | No | 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. |
| schema | string | No | A reporting schema key. Default the latest balance sheet schema of the books. |
| simplified | boolean | null | No | Group the statement into a few rows. Default false: the full statutory scheme. |
get_chase_list
Get the chase listbooks.readEvery bank movement still in suspense: what to chase a document or a decision for.
- company_idstringRequired
- The id of the company, from list_companies.
| Argument | Type | Required | Description |
|---|---|---|---|
| company_id | string | Yes | The id of the company, from list_companies. |
get_general_ledger
Get the general ledgerbooks.readThe 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.
| Argument | Type | Required | Description |
|---|---|---|---|
| company_id | string | Yes | The id of the company, from list_companies. |
| account_code | string | No | One account only. |
| date_from | string (date) | No | The first day of the range, inclusive. Before it is the opening balance. |
| date_to | string (date) | No | The last day of the range, inclusive. |
get_open_items
Get the open itemsbooks.readEvery 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.
| Argument | Type | Required | Description |
|---|---|---|---|
| company_id | string | Yes | The id of the company, from list_companies. |
| account_code | string | No | Open items on this account only. |
| as_of | string (date) | No | The residuals as of this date: the lines of entries dated by it, the allocations effective by it. Default today. |
| party_id | string | No | Open items of this party only. |
get_profit_and_loss
Get the profit and loss statementbooks.readThe 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.
| Argument | Type | Required | Description |
|---|---|---|---|
| company_id | string | Yes | The id of the company, from list_companies. |
| compare_from | string (date) | No | The first day of a period to compare with. Goes with `compare_to`. |
| compare_to | string (date) | No | The last day of a period to compare with. Goes with `compare_from`. |
| date_from | string (date) | Yes | The first day of the period. |
| date_to | string (date) | Yes | The last day of the period. |
| omit_empty | boolean | null | No | 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. |
| schema | string | No | A reporting schema key. Default the latest income statement schema of the books. |
| simplified | boolean | null | No | Group the statement into a few rows. Default false: the full statutory scheme. |
get_trial_balance
Get the trial balancebooks.readThe 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`.
| Argument | Type | Required | Description |
|---|---|---|---|
| company_id | string | Yes | The id of the company, from list_companies. |
| date_from | string (date) | No | The first day of the range, inclusive. Before it is the opening balance. |
| date_to | string (date) | No | The last day of the range, inclusive. |
| period | string | No | A period code (`2026-03`) or id. Excludes `date_from` and `date_to`. |
get_tsd_activity
Get the TSD activity of a monthbooks.readWhether 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.
| Argument | Type | Required | Description |
|---|---|---|---|
| company_id | string | Yes | The id of the company, from list_companies. |
| period_from | string (date) | Yes | The first day of the month. |
| period_to | string (date) | Yes | The last day of the same month. |
Tax account
get_tax_account
Get the tax account at EMTAbooks.readThe 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.
| Argument | Type | Required | Description |
|---|---|---|---|
| company_id | string | Yes | The id of the company, from list_companies. |
VAT
get_invoice_listing
Get the KMD INF invoice listingbooks.readThe 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.
| Argument | Type | Required | Description |
|---|---|---|---|
| company_id | string | Yes | The id of the company, from list_companies. |
| period_from | string (date) | Yes | The first day of the tax period. |
| period_to | string (date) | Yes | The last day of the tax period. |
get_vat_registration
Get the VAT registrationbooks.readThe 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.
| Argument | Type | Required | Description |
|---|---|---|---|
| company_id | string | Yes | The id of the company, from list_companies. |
| as_of | string (date) | No | The day of `status`. Default: the latest status by date. |
get_vat_return
Get a VAT returnbooks.readOne 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.
| Argument | Type | Required | Description |
|---|---|---|---|
| company_id | string | Yes | The id of the company, from list_companies. |
| vat_return_id | string | Yes | The core ULID of the object, 26 characters. |
get_vat_threshold
Get the VAT registration threshold watchbooks.readThe 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.
| Argument | Type | Required | Description |
|---|---|---|---|
| company_id | string | Yes | The id of the company, from list_companies. |
| as_of | string (date) | Yes | The day of the watch. The turnover counts from 1 January of its year. |
get_vd_report
Get the VD reportbooks.readThe 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.
| Argument | Type | Required | Description |
|---|---|---|---|
| company_id | string | Yes | The id of the company, from list_companies. |
| period_from | string (date) | Yes | The first day of the month. |
| period_to | string (date) | Yes | The last day of the same month. |
list_vat_returns
List VAT returnsbooks.readThe 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
| Argument | Type | Required | Description |
|---|---|---|---|
| company_id | string | Yes | The id of the company, from list_companies. |
| cursor | string | No | The `next_cursor` of the previous page. Omit it for the first page. |
| date_from | string (date) | No | The earliest start of the return period, inclusive. |
| date_to | string (date) | No | The latest start of the return period, inclusive. |
| form | string | No | Returns of this form only (`KMD`). |
| limit | integer | No | The 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" | No | Returns in this state only. * `draft` - draft * `prepared` - prepared * `filed` - filed * `amended` - amended |
preview_vat_return
Preview a VAT returnbooks.readWhat 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.
| Argument | Type | Required | Description |
|---|---|---|---|
| company_id | string | Yes | The id of the company, from list_companies. |
| form | string | No | The return form. Default the company's form (`KMD`). |
| period_from | string (date) | Yes | The first day of the return period. |
| period_to | string (date) | Yes | The last day of the return period. |