Norman

Create a Draft annual-close workspace; this does not lock or submit the year.

create_annual_close

Post a closing adjustment to a Draft annual close; locked years remain server-protected.

create_annual_close_entry

Create an active asset, optionally linked to a Norman Transaction or split item. New assets are active and have no disposal date; record a sale or loss later with update_asset (status plus disposal_date).

create_asset

Create a new attachment with a file. Args: transactions: List of transaction IDs to link attachment_type: Type of attachment (invoice, receipt) amount: Amount related to attachment amount_exchanged: Exchanged amount in different currency attachment_number: Unique number for attachment brand_name: Brand name associated with attachment currency: Currency of amount (default EUR) currency_exchanged: Exchanged currency (default EUR) description: Description of attachment supplier_country: Country of supplier (DE, INSIDE_EU, OUTSIDE_EU) value_date: Date of value vat_sum_amount: VAT sum amount vat_sum_amount_exchanged: Exchanged VAT sum amount vat_rate: VAT rate percentage sale_type: Type of sale additional_metadata: Additional metadata for attachment How to provide the file (pick one): 1. file_url — best if the file has a public HTTP(S) URL 2. file_ref — call request_file_upload first to get an upload link, ask the user to open it in their browser and drop the file, then pass the file_ref here 3. file_content_base64 — ONLY for tiny files under 50 KB NEVER base64-encode images, PDFs, or scans — they will blow up the context window. Use file_url or request_file_upload instead.

create_attachment

Create an automation rule. Preview first with preview_rule. Send exactly one of category_id / company_category_id (freelancer vs SME). After creating, offer apply_rule_to_existing to also categorize the backlog. Returns: The created rule.

create_rule

Create a custom Ledger account; balance-sheet accounts stay Ledger-only. Pass ebilanz_assignment to report the new account in the E-Bilanz; without one, a code outside the SKR standard stays unmapped and blocks the cutover preview and the annual E-Bilanz. Account and assignment are saved together.

create_chart_of_accounts_account

Create a new client. Args: name: Client name or business name client_type: Type of client (defaults to "business"), Options: "business", "private" address: Client physical address zip_code: Client postal/zip code email: Client email address country: Client country code (e.g. "DE") vat_number: Client VAT number city: Client city phone: Client phone number Returns: Newly created client record

create_client

Create a new custom company category for the active SME company. ⚠️ SME ONLY — only works for GmbH/UG companies with a DATEV chart of accounts. Not applicable to freelance accounts. Use search_skr_by_code or suggest_skr_category first to find the right account number from the full SKR catalog, then create the category here.

create_company_category

Credit part or all of an issued invoice with a credit note (Rechnungskorrektur). Without items every line of the invoice is credited. Pass items (with the quantities and rates to credit, in minor currency units) to correct part of it. The invoice itself stays in force. The credit note refers to the invoice on the PDF and in the e-invoice XML. status "draft" leaves it editable; "saved" issues it at once. issued (YYYY-MM-DD) defaults to today.

create_credit_note

Make a delivery note (Lieferschein) from an issued invoice or an approved quote. The delivery note lists the document's lines with quantities and units and prints no prices. It takes the next number of its own sequence, refers to the source document and is filed in the company's Files space. Pass items to note a partial delivery. delivery_date (YYYY-MM-DD) defaults to the source's delivery date, or today when it has none. Several delivery notes per document are fine.

create_delivery_note

Generate a short-lived upload link that the USER opens in their browser. Call this BEFORE create_attachment when the user wants to attach a file (image, PDF, receipt) and you cannot provide a public file_url. The link opens a drag-and-drop upload page. After the user uploads, the page shows a file_ref token. Use that file_ref in create_attachment. IMPORTANT: Do NOT try to upload the file yourself (curl, base64, etc.). Just give the link to the user and wait for them to upload.

request_file_upload

Create a new invoice. Ask for additional information if needed, for example: - If the client is not found, ask for the client details and create a new client if necessary. - If a payment reminder should be sent, ask for the reminder settings. - If the invoice type is GOODS, ask for the delivery date. - If the invoice type is SERVICES, ask for the service start and end dates. - If the invoice should be sent to the client, ask for the email data. For a contract, use prepare_invoice_from_contract and review its proposal first. Preserve source_contract_id on creation to link the original document. Args: document_design: Template and appearance settings. Omit to inherit the company design. Paid templates require an active subscription. discount_percents: Overall invoice discount percentage. currency_exchanged: Reporting currency code. full_cost_origin_exchanged: Total in reporting currency in major units; omit for automatic conversion. tax_exempt_reason: VAT note; omit for automatic text, or use an empty string to print no note. instructions: Invoice instructions. message: Invoice message. company_email: Sender email; omit to use the company email. skip_bank_details: Exclude bank details from the document. save_client_details: Also save the submitted client details to the client record. client_data: Recipient details for this document. company_data: Sender details for this document. online_payment_enabled: Enable Stripe/PayPal payment links; omit to inherit, false to disable. document_type: Document type: invoice, quote, delivery_note, cancel or credit_note. Use invoice unless another type is requested. To cancel or credit an EXISTING invoice, or to make a delivery note from one, use cancel_invoice, create_credit_note or create_delivery_note instead. status: "draft" keeps an editable draft that is never emailed, marked paid or matched to payments. Omit or use "saved" to issue it. payment_status: Payment status: unpaid or paid. payment_date: Payment date in YYYY-MM-DD format. bank_account_pk: Bank account ID for payment details. is_to_create_transaction: Create a linked accounting transaction with the invoice. paid_amount: Amount already paid in minor currency units. source_contract_id: Source contract ID in the active company. client_id: Client public ID, or null for an allowed invoice without a recipient items: List of invoice items, each containing name, quantity, rate and vatRate. Example: [{"name": "Software Development", "quantity": 3, "rate": 30000, "vatRate": 19}] // VAT rates might be 0, 7, 19. By default it's 19. Rate is in cents; the API calculates totals. Optional per item: "description" (text printed under the name, max 500 chars), "unit" (one of items, hours, days, kilograms, liters, meters, square_meters) and "productId" (a catalog product's publicId from list_products). When a product is used, copy its name, description, unit and vatRate onto the item and take rate from priceNet (priceGross when is_vat_included is True). invoice_number: Optional invoice number (will be auto-generated if not provided) issued: Issue date in YYYY-MM-DD format due_to: Due date in YYYY-MM-DD format currency: Invoice currency (EUR, USD); omit for the company's own currency. payment_terms: Payment terms text notes: Additional notes language: Invoice language (en, de) invoice_type: Type of invoice (SERVICES, GOODS) is_vat_included: Whether prices include VAT bank_name: Name of the bank (gets from company details if exists) iban: IBAN for payments (gets from company details if exists) bic: BIC/SWIFT code (gets from company details if exists) create_qr: Whether to create payment QR code (only if BIC and IBAN provided) color_schema: Invoice style color (hex code). Omit to inherit company branding. font: Invoice font. Omit to inherit the company font. is_to_send: Whether to send invoice automatically to client mailing_data: Email data if is_to_send is True. Example: { "emailSubject": "Invoice No.{invoice_number} for {client_name}", "emailBody": "Dear {client_name},...", "customClientEmail": "client@example.com" // email to send the invoice to, if not provided, it will be sent to the client email address } settings_on_overdue: Configuration for overdue notifications. Example: { "isToAutosendNotification": true, // whether to send notification automatically "customEmailSubject": "Reminder: Invoice {invoice_number} is overdue", // custom email subject "customEmailBody": "Dear {client_name},...", // custom email body "notifyAfterDays": [1, 3], // days to notify after the due date "notifyInParticularDays": [] // days to notify in particular dates [2025-05-23", "2025-05-24"] } service_start_date: Service period start date (YYYY-MM-DD) by default it's today, should be provided if invoice_type is SERVICES service_end_date: Service period end date (YYYY-MM-DD) by default it's one month from today, should be provided if invoice_type is SERVICES delivery_date: Delivery date for goods (YYYY-MM-DD) by default it's today, should be provided if invoice_type is GOODS Returns: Information about the created invoice. Use downloadUrl for a direct temporary PDF download link (valid for 1 hour).

create_invoice

Create a balanced manual posting with explicit tax semantics. tax_role=VAT means amount is the actual tax correction, not a taxable base. Supported only with DOMESTIC_INPUT_VAT, DOMESTIC country scope, BOOKKEEPING_ERROR reason, a memo and one input VAT account. A credit to the input VAT account reduces the deduction; a debit increases it. Other reasons, output VAT and reverse-charge overrides are rejected.

create_manual_ledger_entry

Create a new offer/quote, with the same line, design, payment and sender options as create_invoice. Omit document_design, colour and font to inherit company branding. The API enforces paid template access. Use update_invoice to edit an existing quote. Args: client_id: ID of the client for the offer items: List of offer items. Example: [{"name": "Software Development", "quantity": 3, "rate": 30000, "vatRate": 19}] VAT rates might be 0, 7, 19. Rate is in cents. offer_number: Optional offer number (will be auto-generated if not provided) issued: Issue date in YYYY-MM-DD format valid_until: Offer validity date in YYYY-MM-DD format (defaults to 30 days from today) currency: Offer currency (EUR, USD); omit for the company's own currency. payment_terms: Payment terms text notes: Additional notes language: Offer language (en, de) invoice_type: Type of offer (SERVICES, GOODS) is_vat_included: Whether prices include VAT bank_name: Name of the bank iban: IBAN for payments bic: BIC/SWIFT code create_qr: Whether to create payment QR code (only if BIC and IBAN provided) color_schema: Offer colour (hex code); omit to inherit saved branding. font: Offer font; omit to inherit the saved font. is_to_send: Whether to send the offer automatically to client mailing_data: Email data if is_to_send is True service_start_date: Service period start date (YYYY-MM-DD) service_end_date: Service period end date (YYYY-MM-DD) delivery_date: Delivery date for goods (YYYY-MM-DD) status: "draft" keeps an editable draft that is never emailed. Omit or use "saved" to issue it. Returns: Information about the created offer. Use downloadUrl for a direct temporary PDF download link when available.

create_offer

Create a catalog product or service. Args: name: Product or service name (unique among the company's active products) price: Unit price in cents (net unless is_price_gross is True) vat_rate: VAT rate in percent (0, 7, 19 in Germany); the country default if omitted product_type: "SERVICES" (default) or "GOODS" unit: One of items, hours, days, kilograms, liters, meters, square_meters description: Optional text printed under the name on invoices (max 500 chars) is_price_gross: True when `price` already includes VAT sku: Optional article number, unique per company company_category_id: Optional bookkeeping (income) category ID Returns: The created product

create_product

Create a recurring invoice that will automatically generate new invoices based on specified frequency. Useful for contracts or services that bill on a regular basis. Always ask for recurring configuration, for example: - How often to generate invoices (weekly, monthly) - Number of units for frequency (e.g. 1 for monthly = every month, 2 = every 2 months) - Start date - End date - End invoice count (optional) Ask for additional information if needed, for example: - If the client is not found, ask for the client details and create a new client if necessary. - If the invoice number is not provided, ask for it. - If the due date is not provided, ask for it. - If the payment terms are not provided, ask for it. - If the bank details are not provided, ask for it. For a contract, use prepare_invoice_from_contract and review its proposal first. Preserve source_contract_id on creation to link the original document. Args: document_design: Template and appearance settings. Omit to inherit the company design. Paid templates require an active subscription. discount_percents: Overall invoice discount percentage. currency_exchanged: Reporting currency code. full_cost_origin_exchanged: Total in reporting currency in major units; omit for automatic conversion. tax_exempt_reason: VAT note; omit for automatic text, or use an empty string to print no note. instructions: Invoice instructions. message: Invoice message. company_email: Sender email; omit to use the company email. skip_bank_details: Exclude bank details from the document. save_client_details: Also save the submitted client details to the client record. client_data: Recipient details for this document. company_data: Sender details for this document. online_payment_enabled: Enable Stripe/PayPal payment links; omit to inherit, false to disable. mailing_data: Email subject, body, recipient, extra recipients and copy-to-company option. source_contract_id: Source contract ID in the active company. client_id: Client public ID, or null for an allowed invoice without a recipient items: List of invoice items, each containing name, quantity, rate and vatRate. Optional per item: "description", "unit" and "productId", as in create_invoice. is_ongoing: Continue until cancelled; omit both end conditions when true. payment_due_days: Days after each issue date until payment is due (0-365). billing_in_advance: True bills the upcoming service period; false bills in arrears. frequency_type: How often to generate invoices ("weekly", "monthly") frequency_unit: Number of units for frequency (e.g. 1 for monthly = every month, 2 = every 2 months) starts_from_date: Date to start generating invoices from (YYYY-MM-DD) ends_on_date: Optional end date for recurring invoices (YYYY-MM-DD). Either ends_on_date or ends_on_invoice_count should be provided. ends_on_invoice_count: Optional number of invoices to generate before stopping. Either ends_on_date or ends_on_invoice_count should be provided. invoice_number: Base invoice number (will be auto-generated if not provided) currency: Invoice currency, e.g. USD. EUR, the default, bills in the company's own currency. payment_terms: Payment terms text notes: Additional notes language: Invoice language (en, de) invoice_type: Type of invoice (SERVICES, GOODS) is_vat_included: Whether prices include VAT bank_name: Name of the bank iban: IBAN for payments bic: BIC/SWIFT code create_qr: Whether to create payment QR code color_schema: Invoice style color (hex code). Omit to inherit company branding. font: Invoice font. Omit to inherit the company font. is_to_send: Whether to send invoices automatically to client settings_on_overdue: Configuration for overdue notifications Returns: Information about the created recurring invoice. Use downloadUrl for a direct temporary PDF download link (valid for 1 hour).

create_recurring_invoice

Create a new manual transaction. For SME companies (GmbH/UG), use company_category_id instead of category_id, and optionally set payment_date and payment_type for accrual accounting.

create_transaction

Create a new vendor (supplier). Args: name: Vendor name or business name iban: Vendor bank account IBAN bic: Vendor bank BIC/SWIFT email: Vendor email address phone: Vendor phone number address: Vendor physical address country: Vendor country code (e.g. "DE") vat_number: Vendor VAT number Returns: Newly created vendor record

create_vendor

Soft-delete an account. Existing postings remain in the immutable Ledger.

deactivate_chart_of_accounts_account

Delete an asset only after explicit confirmation; audit/reversal rules remain server-side.

delete_asset

Delete an attachment — e.g. an orphan receipt/invoice with no linked transaction (a stale self-statement left behind after the real invoice was attached). Retention-aware: Norman keeps documents under GoBD retention. A retained document returns a 409 whose `detail.requiresConfirmation` is true (with a `retentionUntil` date); re-call with `confirm=true` to override. Only call once the user has confirmed the attachment should be removed. Args: attachment_id: ID of the attachment to delete confirm: set true to override the legal-retention guard on a retained document Returns: Confirmation of deletion, or the 409 retention warning if confirm is not set

delete_attachment

Delete an automation rule after the user confirms. Prefer disabling (update_rule with is_active=false) when the user may want it back. Returns: Deletion confirmation.

delete_rule

Delete a bill. Args: bill_id: ID of the bill to delete Returns: Confirmation of deletion

delete_bill

Delete a client. Args: client_id: ID of the client to delete Returns: Confirmation of deletion

delete_client

Delete a transaction and its regenerable Ledger postings after confirmation.

delete_transaction

Delete a vendor. Args: vendor_id: ID of the vendor to delete Returns: Confirmation of deletion

delete_vendor

Reject an awaiting-review execution after the user said no. The target goes back through normal categorization, and this rule never re-claims the same target. Returns: The dismissed execution.

dismiss_rule_execution

Copy an invoice or a quote into a new draft of the same kind. The copy keeps client, lines, terms and appearance, is dated today with the payment term carried over, takes the next number of its sequence and does not refer to the original. Finish it with update_invoice: adjust the service or delivery dates and set status "saved" to issue it.

duplicate_invoice

Generate a test Finanzamt preview for a tax report. Generates and stores a temporary preview PDF without submitting the report. Returns its first page as an inline image in the API's format (normally JPEG) plus a downloadUrl for the full PDF. Repeated calls create new preview files.

generate_finanzamt_preview

Get opening/cutover status for a fiscal year without changing the books.

get_accounting_setup

Get one annual-close workspace and its Draft/locked/submitted status.

get_annual_close

Review SuSa, Bilanz, GuV, BVV and blocking validations. This never locks or submits.

get_annual_close_workbook

Get an asset including source transaction, useful life and annual depreciation.

get_asset

Download an attachment and return it as an inline image. Works for image attachments (PNG, JPEG, GIF, WebP). For PDFs and other non-image files, returns the download URL instead.

get_attachment_preview

Get detailed information about a specific bill. Args: bill_id: ID of the bill to retrieve Returns: Detailed bill information

get_bill

Read the cash register derived from CASH transactions and the Kasse account.

get_cash_book

Get detailed information about a specific client. Args: client_id: ID of the client to retrieve Returns: Detailed client information

get_client

Get an aggregated financial health snapshot for a client company. Combines company details, balance, transaction stats, missing receipts, outstanding invoices, and tax report status into a single overview. Designed for tax advisors managing multiple client companies. Returns: A structured overview with company info, financial summary, document completeness, and tax compliance status.

get_client_overview

Get the current balance of the company. Returns: Company balance information

get_company_balance

Get detailed information about the user's company.

get_company_details