# MCP tool reference > Generated by `pnpm gen:docs` from the tool catalog of the Oscar MCP server. Every tool calls one operation of the Oscar API, with the same permission checks as every other client. The server lists to each caller only the tools that its role, its scopes and the client capabilities of the company allow. A write tool needs the `write` scope, and `/mcp/readonly` has no write tool. How to connect: `/docs/mcp.md`. ## Alerts ### `list_alerts`: List alerts - Access: read - Permission: `books.read` What a person of the company must act on, with the last day to act: a VAT registration, a KMD or TSD deadline, a sales invoice to issue, an exchange rate that was refused or corrected, an entry to re-rate. The alerts of the company, newest first. A list answers {items, next_cursor}; pass next_cursor back as cursor for the next page. | 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 item - Access: write - Permission: `allocations.write` A discount, a write-off or a rounding over 100 minor units (adjustment_kind), two different amounts in one foreign currency, or an FX difference over a tenth of the base value is a judgement of a person: propose it with propose_judgement. Runs the core command `allocate`. Permission: `allocations.write`. Send an idempotency_key and reuse it when you retry: the same key and the same arguments return the first outcome with replayed=true instead of running the command twice. If the answer is the error human_actor_required, a person must decide: call propose_judgement with the same command and its full payload. | 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 invoices - Access: read - Permission: `books.read` How far each invoice is settled, or one invoice with `invoice_id`. | 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 allocation - Access: write - Permission: `allocations.write` Runs the core command `unallocate`. Permission: `allocations.write`. The path carries `allocation_id`. Send an idempotency_key and reuse it when you retry: the same key and the same arguments return the first outcome with replayed=true instead of running the command twice. If the answer is the error human_actor_required, a person must decide: call propose_judgement with the same command and its full payload. | 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 rules - Access: write - Permission: `bank.classify` Books the card charges and refunds of a Stripe feed in a date range that no rule explained yet, with the rules in force (mode unclassified). Mode reclassify redoes receipts after a rule changed; it is a judgement of a person, so propose it with propose_judgement and a reason. Runs the core command `apply_money_in_rules`. Permission: `bank.classify`. Send an idempotency_key and reuse it when you retry: the same key and the same arguments return the first outcome with replayed=true instead of running the command twice. If the answer is the error human_actor_required, a person must decide: call propose_judgement with the same command and its full payload. | 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 transaction - Access: read - Permission: `books.read` One bank transaction with its source row, entries, allocations, the judgement on it, and its files. | 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 accounts - Access: read - Permission: `books.read` The bank feeds with their ledger account, transaction count and ledger balance. Ordered by label. A list answers {items, next_cursor}; pass next_cursor back as cursor for the next page. | 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 transactions - Access: read - Permission: `books.read` The bank transactions with their settlement status, derived on read. Ordered by booking date. `has_document` and `file_ids` name the uploaded files that explain a transaction (an upload with `bank_transaction_id`). `to_explain=true` lists the payments to explain: money out still open that no file explains. A list answers {items, next_cursor}; pass next_cursor back as cursor for the next page. | 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 feed - Access: read - Permission: `books.read` The rules that turn the card charges of a Stripe feed into receipts. A person adds, changes, reorders or removes a rule: propose set_money_in_rule, reorder_money_in_rules or remove_money_in_rule with propose_judgement. The standing money-in rules of a payment provider feed, with the version in force on `as_of`. The active rules come first, in the order the books evaluate them on a charge, then the removed ones. Each rule carries every version. A rule is written with `POST money-in-rules` (`set_money_in_rule`, a person with `bank.classify`). | 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 transfer - Access: write - Permission: `bank.classify` Runs the core command `match_transfer`. Permission: `bank.classify`. Send an idempotency_key and reuse it when you retry: the same key and the same arguments return the first outcome with replayed=true instead of running the command twice. If the answer is the error human_actor_required, a person must decide: call propose_judgement with the same command and its full payload. | 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 transaction - Access: write - Permission: `bank.classify` Runs the core command `set_transaction_party`. Permission: `bank.classify`. The path carries `bank_transaction_id`. Send an idempotency_key and reuse it when you retry: the same key and the same arguments return the first outcome with replayed=true instead of running the command twice. If the answer is the error human_actor_required, a person must decide: call propose_judgement with the same command and its full payload. | 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 company - Access: read - Permission: `organization.read` One company: name, legal data and state. Return the company. | Argument | Type | Required | Description | | --- | --- | --- | --- | | `company_id` | `string` | yes | The id of the company, from list_companies. | ### `list_companies`: List companies - Access: read - Permission: `organization.read` The companies of the organization this connection is bound to. Start here: every other tool takes the company_id of one of them. Only a company in state ready has books. One page of the companies, newest first. A list answers {items, next_cursor}; pass next_cursor back as cursor for the next page. | 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 month - Access: read - Permission: `books.read` The dividends paid in one month: the data of TSD annex 7 and form INF 1. The dividends paid in a month: the data of TSD annex 7 and form INF 1. A dividend is booked at its declaration, but taxed in the month of its payment. The view reads the payments of the month (the allocations that settle a recipient's dividend payable) and gives annex 7 part I (code 7008, the taxable dividends; code 7217, the income tax at 22/78; code 7200), part II (the balance of exempt dividends received, code 7310) and one INF 1 line for each recipient paid. `findings` names what a person should check. A period that is not one calendar month is 400. The TSD and INF 1 files are made elsewhere. | 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 record - Access: read - Permission: `books.read` One document record with the invoices, statements, events and VAT returns that refer to it. | 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 inbox - Access: read - Permission: `documents.read` The private address the company forwards supplier invoices to, the counts of the last 30 days and the Gmail search strings. The first read makes the address. The private forwarding address of the company, made on the first read, and what came in. Also the Gmail search strings to paste into a Gmail filter, and the newest Gmail forwarding confirmation that oscarai forwarded to the Gmail address that asked for it (never its code or link). | Argument | Type | Required | Description | | --- | --- | --- | --- | | `company_id` | `string` | yes | The id of the company, from list_companies. | ### `list_document_records`: List document records - Access: read - Permission: `books.read` The document records of the books. Ordered by creation; `ordering=-created_at` is newest first. `referenced=false` lists the documents nothing in the books refers to yet: the uploads still to book. `bank_feed=false` leaves out the statements the bank feed stored (its JSON files), `bank_feed=true` lists only them. `file_id` and `download_url` name the stored file. A list answers {items, next_cursor}; pass next_cursor back as cursor for the next page. | 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 emails - Access: read - Permission: `documents.read` The mails the invoice inbox received, newest first: the sender, the result, the files with their draft, and the attachments not kept. One page of the received mails, newest first: the sender, the outcome, the files, the attachments not kept. A list answers {items, next_cursor}; pass next_cursor back as cursor for the next page. | 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 document - Access: write - Permission: `documents.write` Runs the core command `record_document`. Permission: `documents.write`. Send an idempotency_key and reuse it when you retry: the same key and the same arguments return the first outcome with replayed=true instead of running the command twice. If the answer is the error human_actor_required, a person must decide: call propose_judgement with the same command and its full payload. | 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 employee - Access: read - Permission: `books.read` The personal code is masked. One employee, with every employment (the TÖR id and state, the suspensions) and the absences. | 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 submission - Access: read - Permission: `books.read` One submission: its status, the review, the TÖR id once TÖR registered it, and the messages of TÖR. One submission: its status, the reason of a refusal, TÖR's messages, the TÖR id once registered. | 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 submissions - Access: read - Permission: `books.read` The new employees and changes submitted for the firm to review: submitted, approved, registered in TÖR, applied (a change TÖR does not hold, such as the salary) or rejected. One page of the submissions, newest first, with their status and the reason of a refusal. A list answers {items, next_cursor}; pass next_cursor back as cursor for the next page. | 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 employees - Access: read - Permission: `books.read` The employee register, filled from TÖR, the employment register of the Tax and Customs Board. One page of the employees, newest first, each with the facts of its newest employment. `source` `tor_external` and `registered_outside` mark what TÖR showed that was not made through OscarAI. The personal code is masked. A list answers {items, next_cursor}; pass next_cursor back as cursor for the next page. | 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 change - Access: write - Permission: `employees.submit` Submits a new employee, another employment, a change, a suspension or an end of an employment. Nothing reaches TÖR yet: the accounting firm reviews the submission, and only on its approval registers the event in TÖR. Read the outcome with get_employee_submission. Submit a new employee, a new employment, a change, a suspension or an end, for the firm to review. Staff review it; on approval OscarAI registers the event in TÖR. The personal code of a new employee is sealed and never returned. The event is checked as TÖR checks it (400 `tor_invalid_event`). Send an idempotency_key and reuse it when you retry: the same key and the same arguments return the first outcome with replayed=true instead of running the command twice. | 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 status - Access: read - Permission: `books.read` What run_depreciation through a month would post, per asset, and the months it cannot post and why (a locked or missing period, or no usage recorded). What a depreciation run through `through` would post, per asset, and the months it could not post and why. `through` defaults to the month before the current month, the month the daily job posts. A blocked month (`period_locked`, `no_period`, `usage_missing`) needs a person. | 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 asset - Access: read - Permission: `books.read` One asset: its components with the estimate in force and the next charge, its events, usage, opening amounts and the invoice lines linked to it. One fixed asset: its components with their estimate and next charge, its events, usage and linked invoice lines. The amounts are on `as_of` (default today); the months before its month are due. | 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 table - Access: read - Permission: `books.read` The movement table of the notes for a date range, per kind of asset, and its agreement with the ledger. The movement table of the fixed assets of a range (EE-FA-033), by taxonomy, and its agreement with the ledger. Each column has the cost and the accumulated amounts at the start and at the end, the additions, the depreciation, the impairments and their reversals, the disposals, the reclassifications and the fair value changes. `gl_agreement` compares each asset account with the register. | 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 asset - Access: read - Permission: `books.read` Each month of each component: posted, due or projected, with the charge, the accumulated depreciation and the carrying amount. The depreciation schedule of a fixed asset: each month of each component, posted, due or projected. Without `month_from` and `month_to` it covers the useful life from the first month; at most 1200 months. A posted month names its entry. | 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 groups - Access: read - Permission: `books.read` The groups in force: class, accounts and the default method and useful life. The fixed asset groups in force: their class, accounts and default estimate. Ordered by code. | 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 assets - Access: read - Permission: `books.read` The fixed asset register: each asset with its group, class, status, cost, accumulated depreciation and impairment and carrying amount on a day (default today), and the totals. The fixed asset register: each asset with its group, status and amounts on `as_of` (default today). Ordered by code. `totals` sums every asset the filters keep. The register is internal; the Advanced part of the app reads it. A list answers {items, next_cursor}; pass next_cursor back as cursor for the next page. | 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 schedule - Access: read - Permission: `books.read` The first 24 months and the total of a draft estimate (cost, ready-for-use date, method, life or rate). It writes nothing. The first 24 months and the total of a draft estimate, under the depreciation policy in force. It writes nothing. | 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 invoice - Access: write - Permission: `invoices.post_purchase or invoices.write` Runs the core command `cancel_invoice`. Permission: `invoices.write` for a sales invoice, `invoices.post_purchase` for a purchase invoice. The path carries `invoice_id`. Send an idempotency_key and reuse it when you retry: the same key and the same arguments return the first outcome with replayed=true instead of running the command twice. If the answer is the error human_actor_required, a person must decide: call propose_judgement with the same command and its full payload. | 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 invoice - Access: read - Permission: `books.read` One invoice: its current revision with lines and documents, its revisions, its entries and its settlement. | 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 issue - Access: read - Permission: `books.read` The recorded sales invoices not issued yet whose supply has happened, with the last day to issue each: 7 days after the supply, or the 15th of the next month for an EU supply. The recorded sales invoices to issue on `as_of`, with the last day to issue each (EE-VAT-018). An invoice is issued within 7 calendar days after the supply, the end of a continuous supply, or the prepayment; an intra-Community supply or a service to a business in another EU state by the 15th of the next month. Only a supply made by `as_of`, on a day the company is VAT-registered, is listed. The daily reminder job raises an alert for each. | 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 elsewhere - Access: write - Permission: `invoices.issue` Records, issues and posts it with its external number, in the series of its source. Runs the core command `import_sales_invoice`. Permission: `invoices.issue`. Send an idempotency_key and reuse it when you retry: the same key and the same arguments return the first outcome with replayed=true instead of running the command twice. If the answer is the error human_actor_required, a person must decide: call propose_judgement with the same command and its full payload. | 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 invoice - Access: write - Permission: `invoices.issue` Runs the core command `issue_invoice`. Permission: `invoices.issue`. The path carries `invoice_id`. Send an idempotency_key and reuse it when you retry: the same key and the same arguments return the first outcome with replayed=true instead of running the command twice. If the answer is the error human_actor_required, a person must decide: call propose_judgement with the same command and its full payload. | 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 invoices - Access: read - Permission: `books.read` The invoices, purchase and sales, with the header facts of their current revision and their settlement. Oldest first by invoice date; `ordering=-invoice_date` is newest first. `settlement` filters by `settlement_state`: `open` is unpaid or part paid, `overdue` an open invoice due before today in the time zone of the books. A list answers {items, next_cursor}; pass next_cursor back as cursor for the next page. | 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 invoice - Access: write - Permission: `invoices.issue or invoices.post_purchase` Runs the core command `post_invoice`. Permission: `invoices.issue` for a sales invoice, `invoices.post_purchase` for a purchase invoice. The path carries `invoice_id`. Send an idempotency_key and reuse it when you retry: the same key and the same arguments return the first outcome with replayed=true instead of running the command twice. If the answer is the error human_actor_required, a person must decide: call propose_judgement with the same command and its full payload. | 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 invoice - Access: write - Permission: `invoices.write` Records a draft; post_invoice posts it. Runs the core command `record_invoice`. Permission: `invoices.write`. Send an idempotency_key and reuse it when you retry: the same key and the same arguments return the first outcome with replayed=true instead of running the command twice. If the answer is the error human_actor_required, a person must decide: call propose_judgement with the same command and its full payload. | 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 invoice - Access: write - Permission: `invoices.write` Runs the core command `revise_invoice`. Permission: `invoices.write`. The path carries `invoice_id`. Send an idempotency_key and reuse it when you retry: the same key and the same arguments return the first outcome with replayed=true instead of running the command twice. If the answer is the error human_actor_required, a person must decide: call propose_judgement with the same command and its full payload. | 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 books - Access: read - Permission: `books.read` The head of the books: the `commit_seq` of the latest command, the version a client cache is built from. | Argument | Type | Required | Description | | --- | --- | --- | --- | | `company_id` | `string` | yes | The id of the company, from list_companies. | ### `get_entry`: Get a journal entry - Access: read - Permission: `books.read` One journal entry with its lines and its posting fingerprint. | 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 entries - Access: read - Permission: `books.read` The posted and reversed journal entries, each with all its lines. Ordered by economic date. `ordering=-economic_date` is newest first. A list answers {items, next_cursor}; pass next_cursor back as cursor for the next page. | 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 books - Access: read - Permission: `books.read` Runs the consistency checks of the books. Slow. Return the findings of the verification job. An empty list means the books are consistent. | Argument | Type | Required | Description | | --- | --- | --- | --- | | `company_id` | `string` | yes | The id of the company, from list_companies. | ## Parties ### `create_party`: Create a party - Access: write - Permission: `parties.write` Runs the core command `create_party`. Permission: `parties.write`. Send an idempotency_key and reuse it when you retry: the same key and the same arguments return the first outcome with replayed=true instead of running the command twice. If the answer is the error human_actor_required, a person must decide: call propose_judgement with the same command and its full payload. | 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. | | `email` | `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 party - Access: read - Permission: `books.read` One party with its defaults and its roles. | 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 parties - Access: read - Permission: `books.read` Customers, suppliers and other counterparties. The parties, ordered by their cleaned name. Merged parties are left out unless asked for. `roles` says what each party is to the company, from its kind, its invoices and its open purchase drafts; `role` filters on the roles the books derive (an open draft aside), and `exclude_kind=employee` leaves out the employees, as the list of customers and suppliers does. A list answers {items, next_cursor}; pass next_cursor back as cursor for the next page. | 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 connection - Access: read - Permission: `payments.read` Start here for a question about Stripe: the feeds (one bank account per currency) and their balances, the last sync run, the open checks and the number of unexplained card receipts. One connection: its permissions, its feeds and their balances, the last run and the open checks. | 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 run - Access: read - Permission: `payments.read` One sync run: its window, its counts and its checks. | 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 connection - Access: read - Permission: `payments.read` One Stripe invoice or credit note: its import, its checks, its payments and refunds, and its document. | 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 connection - Access: read - Permission: `payments.read` The Invoices tab: the import rows per state, the blocked ones per code, the payments, the last warnings. | 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 invoice - Access: read - Permission: `books.read` For an invoice of the books whose external_source is stripe. The Stripe import of one invoice of the books: its Stripe number and status, its Dashboard link, its PDF and its payments with their Stripe ids. 404 for an invoice that did not come from Stripe. | 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 connections - Access: read - Permission: `payments.read` The Stripe connections of the company, with their status, the last sync and the count of open checks. No tool shows or changes the key of a connection. The connections of the company, newest first, disconnected ones included. A list answers {items, next_cursor}; pass next_cursor back as cursor for the next page. | 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 connection - Access: read - Permission: `payments.read` The sync runs of the connection, newest first, with their counts and checks. A list answers {items, next_cursor}; pass next_cursor back as cursor for the next page. | 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 connection - Access: read - Permission: `payments.read` A person links a Stripe customer to another party in Oscar; no tool does it. The Stripe customers of the connection, each with its party, how it was linked and its invoice count. A list answers {items, next_cursor}; pass next_cursor back as cursor for the next page. | 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 connection - Access: read - Permission: `payments.read` Answers why a Stripe invoice is not in the books: each one with how far its import went. A blocked one carries its block_code; retry_stripe_import runs it again once its cause is fixed. The Stripe invoices and credit notes of the connection and how far each import went, newest first. `state=blocked` lists what waits for a person, with its `block_code`. A list answers {items, next_cursor}; pass next_cursor back as cursor for the next page. | 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 connection - Access: read - Permission: `payments.read` The monthly fee invoices of the connection, newest month first (booked only when staff switched them on). | 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 connection - Access: read - Permission: `payments.read` Each payout with its match to the line of the bank statement that received it. The Stripe payouts of the connection, newest first, with their match and their summary. A list answers {items, next_cursor}; pass next_cursor back as cursor for the next page. | 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 connection - Access: read - Permission: `payments.read` How each Stripe tax becomes a VAT code. A person confirms or changes a mapping in Oscar; no tool does it. The tax mapping of the connection in order: the first active row that matches a Stripe tax wins. | 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 connection - Access: read - Permission: `payments.read` Answers why a card sale is unexplained: each imported Stripe transaction with its classification, the reason (for example no rule matched, or a VAT rate that no rule maps) and the facts the rules read. The imported Stripe transactions, newest first, with their classification, reason and facts. `classification=suspense&category=charge` lists the unexplained card receipts; `bank_transaction_id` finds the Stripe data of one feed line. A list answers {items, next_cursor}; pass next_cursor back as cursor for the next page. | 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 now - Access: write - Permission: `payments.manage` Queues a sync of the Stripe connection now, instead of waiting for the hourly sync. It answers with a task_id; list_payment_sync_runs shows the run when it has finished. A repeat imports nothing twice. Queue a sync run now. A run already waiting takes this request too (the same `task_id`). 409 `connection_disconnected`, `stripe_revoked` or `connection_paused`. Send an idempotency_key and reuse it when you retry: the same key and the same arguments return the first outcome with replayed=true instead of running the command twice. | 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 invoice - Access: write - Permission: `invoices.write` Runs the import of a blocked Stripe invoice or credit note again, with the same rules, after its cause was fixed (a tax mapping, a key permission). A repeat imports nothing twice. Run the import of a blocked Stripe invoice or credit note now, with the same rules. Not a judgement: it reads the same facts and the current tax mapping again. The answer is the row after the attempt; it may still be blocked, with its new reason. Send an idempotency_key and reuse it when you retry: the same key and the same arguments return the first outcome with replayed=true instead of running the command twice. | 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 run - Access: read - Permission: `books.read` The salary payments matched to a net pay become the payment lines of the TSD on the bank date. One pay run with every employee: the inputs, the gross and the net, the net not paid yet, the payments. | 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 runs - Access: read - Permission: `books.read` The monthly payroll: gross pay, taxes and net pay per month. One page of the pay runs, newest month first, with their totals and the net pay not paid yet. A client sees the posted runs; firm staff also the drafts and the approved ones. A list answers {items, next_cursor}; pass next_cursor back as cursor for the next page. | 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 periods - Access: read - Permission: `books.read` The accounting periods with their fiscal year, ordered by start date. A list answers {items, next_cursor}; pass next_cursor back as cursor for the next page. | 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 proposal - Access: read - Permission: `books.read` One proposal. | Argument | Type | Required | Description | | --- | --- | --- | --- | | `company_id` | `string` | yes | The id of the company, from list_companies. | | `proposal_id` | `string` | yes | | ### `list_proposals`: List proposals - Access: read - Permission: `books.read` The judgements proposed for a person to confirm, with their status. The proposals of the company, newest first. A `status` that is not a status is 400. A list answers {items, next_cursor}; pass next_cursor back as cursor for the next page. | 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 judgement - Access: write - Permission: `allocations.write or bank.classify or parties.write` Proposes a command that only a person may run: an exemption, a money-in classification or rule, a party default, a merge of two parties, a discount or a write-off on an allocation, a dimension rule, a period reopening, the facts of a dividend (the approved annual report, unpaid capital, a dividend received), a VAT registration or deregistration, a fixed asset group, a change of a depreciation estimate, an impairment or its reversal, a fair value of an investment property, a transfer or a withdrawal of a fixed asset, an undo of a fixed asset event, or any command answered with human_actor_required. Nothing changes in the books until a person with the permission confirms the proposal in Oscar; the command then runs as that person. The judgement commands and their payload fields (* required): - change_exemption: bank_transaction_id*, counter_role*, reason* - change_money_in: bank_transaction_id*, kind*, reason*, refund_invoice_id, refund_bank_transaction_id - classify_money_in: bank_transaction_id*, kind*, reason*, refund_invoice_id, refund_bank_transaction_id - exempt: bank_transaction_id*, counter_role*, reason* - merge_party: party_id*, into_party_id*, reason* - record_annual_report: financial_year_end*, approved_on*, net_assets_minor*, share_capital_minor*, legal_reserve_minor*, other_undistributable_reserves_minor, distributable_reserves_minor, retained_earnings_minor*, unamortised_development_costs_minor, document_id - record_dividend_received: received_on*, payer_name*, payer_reg_code, payer_country*, party_id, amount_minor*, holding_bps*, payer_taxable*, non_cooperative_jurisdiction, from_profit_taxed_at_14_86, document_id - record_unpaid_capital: as_of*, unpaid_minor*, reason*, document_id - record_vat_registration: kind*, effective_from*, vat_number, note, document_id - remove_dimension_rule: rule_id*, reason - remove_exemption: bank_transaction_id*, reason* - remove_money_in: bank_transaction_id*, reason* - remove_money_in_rule: rule_id*, effective_from*, reason* - reopen_period: period*, reason - reorder_money_in_rules: bank_account_id*, effective_from*, rule_ids*, reason* - set_dimension_rule: target_kind*, invoice_line_id, bank_transaction_id, dimension_value_id*, percent_bps, amount_minor, currency, note - set_money_in_rule: bank_account_id*, rule_id, name*, effective_from*, position*, conditions, outcome*, reason* - set_party_default: party_id*, expense_role, vat_code, currency, payment_days, language - set_fixed_asset_group: code*, name*, name_en, taxonomy*, cost_account*, contra_account*, fair_value_account, in_progress_account*, default_method*, default_useful_life_months, depreciable*, effective_from*, reason*, class* - change_fixed_asset_estimate: fixed_asset_id*, component_id, effective_from*, method, useful_life_months, rate_bps, total_units, unit, residual_value_minor, reason* - impair_fixed_asset: fixed_asset_id*, component_id, date*, recoverable_amount_minor*, basis*, discount_rate_bps, reason* - reverse_fixed_asset_impairment: fixed_asset_id*, component_id, date*, recoverable_amount_minor*, basis*, discount_rate_bps, reason* - revalue_investment_property: fixed_asset_id*, date*, fair_value_minor*, method*, appraiser, independent_appraiser*, reason* - transfer_fixed_asset: fixed_asset_id*, date*, to_group*, to_measurement, fair_value_minor, estimate, reason* - withdraw_fixed_asset: fixed_asset_id*, date*, reason* - undo_fixed_asset_event: event_id*, reason* Send an idempotency_key and reuse it when you retry: the same key and the same arguments return the first outcome with replayed=true instead of running the command twice. | 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 proposal - Access: write - Permission: `reconciliation.decide` Allocates the bank payment of the proposal to its invoices. A person's confirm also sets the party of the payment when it has none. Allocate a pending match as the caller. A confirmed one is returned unchanged. The body is optional. `pairs` gives the amount in the bank currency of a pair in another currency (`counter_minor`); that pair is allocated with `rate_source` manual, which needs a person (403 `match_manual_rate_needs_person` for an API key or an agent). Send an idempotency_key and reuse it when you retry: the same key and the same arguments return the first outcome with replayed=true instead of running the command twice. | 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 proposals - Access: read - Permission: `books.read` The matches of outgoing bank payments to open purchase invoices that the reconciliation matcher proposed or applied, with their status, tier, confidence and the reason a match waits for a person. A person decides one with confirm_match_proposal, reject_match_proposal or undo_match_proposal. The match proposals of the company, newest first. A list answers {items, next_cursor}; pass next_cursor back as cursor for the next page. | 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 proposal - Access: write - Permission: `reconciliation.decide` Marks a wrong match, so the matcher does not propose it again. Reject a pending match; nothing changes in the books. A rejected one is returned unchanged. Send an idempotency_key and reuse it when you retry: the same key and the same arguments return the first outcome with replayed=true instead of running the command twice. | 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 match - Access: write - Permission: `reconciliation.decide` Reverses the allocations of the match. Unallocate a match the matcher applied or a person confirmed. An undone one is returned unchanged. Send an idempotency_key and reuse it when you retry: the same key and the same arguments return the first outcome with replayed=true instead of running the command twice. | 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 rate - Access: read - Permission: `books.read` The invoices and bank transactions whose entries use the rate of one day, currency and source, for example after the ECB corrected it. The invoices and bank transactions whose live entries use one exchange rate. When the ECB corrects a rate after the books took it, these are the rows to re-rate (EE-FX-001, EE-VAT-026). `rate` is null when the books hold no such rate. | 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 accounts - Access: read - Permission: `books.read` The chart of accounts. The chart of accounts, ordered by code. A list answers {items, next_cursor}; pass next_cursor back as cursor for the next page. | 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 dimensions - Access: read - Permission: `books.read` The dimension axes, each with all its values. Ordered by code. A list answers {items, next_cursor}; pass next_cursor back as cursor for the next page. | 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 sheet - Access: read - Permission: `books.read` The balance sheet at a date, in the Estonian scheme. The lines with no amount are left out unless omit_empty is false. The balance sheet at a date (Estonian scheme 1), with an optional comparison date and a simplified grouping. | 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 list - Access: read - Permission: `books.read` Every bank movement still in suspense: what to chase a document or a decision for. | Argument | Type | Required | Description | | --- | --- | --- | --- | | `company_id` | `string` | yes | The id of the company, from list_companies. | ### `get_general_ledger`: Get the general ledger - Access: read - Permission: `books.read` The general ledger: each account with its lines and running balance, in the base currency. | 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 items - Access: read - Permission: `books.read` Every open-item line with its residual, as of a date (`as_of`, default today), aged at that date. | 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 statement - Access: read - Permission: `books.read` The income statement of a period, in the Estonian scheme. The lines with no amount are left out unless omit_empty is false. The income statement of a period (Estonian scheme 1, costs by type), with an optional comparison period and a simplified grouping. | 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 balance - Access: read - Permission: `books.read` The trial balance of a date range or a period, in the base currency. | 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 month - Access: read - Permission: `books.read` Whether the books show, in one calendar month, a fact the TSD of that month declares: payroll or a dividend payment. The income tax on a dividend follows the payment month, not the decision month. Whether the books show, in one calendar month, a fact that the TSD of that month declares. The facts are a journal line on the payroll roles and a dividend payment (EE-CIT-012). The income tax on a dividend is declared in the TSD of the payment month, not of the decision month (EE-CIT-016), so the dividend payment covers it. The daily reminder job reminds of the TSD of a month only when one is true, or when the company is set to file a TSD every month (`files_tsd_monthly`, PL-010). A period that is not one calendar month is 400. | 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 EMTA - Access: read - Permission: `books.read` The tax account of the company at the Estonian Tax and Customs Board (EMTA): the balance of the claims, the interest, the prepayment account, the open claims with their due dates, and a notice of a debt or of a claim due within 7 days. The amounts here are decimal strings in EUR, not minor units. access_status rights_missing means the company has not granted OscarAI access in e-MTA. The tax account from the stored copy, with its as-of time, the access status and the notices. Nothing is read from EMTA here: the copy is refreshed every night, after a filing or a tax payment, and by staff. Before the first refresh every amount is null and `access_status` is `never`. | 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 listing - Access: read - Permission: `books.read` The invoice listing filed with the KMD for a tax period: part A sales, part B purchases. The KMD INF annex of a tax period: the invoice listing filed with the KMD. Part A lists the sales invoices, part B the received invoices, of each partner whose invoices or credit notes of the period reach the threshold without VAT (1000 EUR). Credit notes are negative lines in the period of their own date, at the rate of the original invoice. `reconciliation` compares each part with the KMD rows of the period, and `findings` names what a person should check. A period with no KMD form mapped (from 2027) is 409 `invalid_state`. | 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 registration - Access: read - Permission: `books.read` The VAT status of the company on a day (registered, limited or unregistered), its VAT number and every registration record. The VAT rules follow the status on each tax point. The VAT registration of the company by date: the status on `as_of`, the status at creation, and every record. A registration, a limited registration or a deregistration is recorded with `POST vat-registrations` (`record_vat_registration`). The VAT rules follow the status on the tax point of each invoice. | 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 return - Access: read - Permission: `books.read` One VAT return with its boxes. | 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 watch - Access: read - Permission: `books.read` The turnover of the calendar year against the 40 000 EUR registration threshold, the day it was exceeded and the application deadline, the limited registration duty, and whether a deregistration is possible. The VAT registration threshold watch of the calendar year of `as_of`. The turnover with a place of supply in Estonia from 1 January counts toward 40 000 EUR (EE-VAT-007). The day it exceeds it is the day the duty to register arose, and the application is due 3 working days later (EE-VAT-008). The intra-Community acquisitions above 10 000 EUR, or a service bought from a foreign business, need a limited registration (EE-VAT-010). `deregistration_possible` says whether the turnover allows a deregistration (EE-VAT-011). `findings` names what a person must do. | 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 report - Access: read - Permission: `books.read` The intra-Community supplies of one month (until 12.2026): one line per EU customer VAT number. The VD report of a month: the intra-Community supplies (until 12.2026). One line for each customer VAT number, with the goods amount and the services amount of the month, in whole euros, from the VAT codes of the EC sales list. A credit note is a negative amount in the month of its own date. A correction of an invoice of an earlier month is listed in `corrections`, because it goes on a VDP correction report for that month. `reconciliation` compares the amounts with KMD rows 3.1.1 and 3.1, and `findings` names what a person should check. A period that is not one calendar month is 400; a month from 2027, when the VD data moves into the KMD data set, is 409 `invalid_state`. | 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 returns - Access: read - Permission: `books.read` The VAT returns, ordered by period and revision; `ordering=-period_from` is newest first. A list answers {items, next_cursor}; pass next_cursor back as cursor for the next page. | 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 return - Access: read - Permission: `books.read` What preparing the VAT return of a period would write, without writing it. | 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. |