Norman

Reverse an issued invoice with a cancellation invoice (Stornorechnung; for a Polish company a faktura korygująca to zero). Creates the cancellation with the invoice's lines, the next invoice number and a reference to the invoice, then marks the invoice "cancelled": it is no longer edited, reminded about or matched to payments. Only an issued invoice (saved, sent, overdue, paid or uncollectible) can be cancelled, and only once. To correct part of an invoice use create_credit_note instead. Edit a draft directly. issued (YYYY-MM-DD) defaults to today. The amounts stay positive, like the invoice's; the PDF prints every amount with a minus. correction_reason says why. A Polish cancellation of an invoice in KSeF goes there as a correcting invoice (KOR) that states it; when it cannot go yet, the API refuses and says why.

cancel_invoice

Germany only. Discard a prepared, not yet approved correction. The approved month stays as it was.

cancel_payroll_correction

Detect category for a transaction using AI. Args: transaction_amount: Amount of the transaction transaction_description: Description of the transaction transaction_type: Type of transaction ("income" or "expense") Returns: Suggested category information for the transaction

categorize_transaction

Verify or unverify a transaction (finalize or unfinalize). Args: transaction_id: Public ID of the transaction to update verify: If True, verify (finalize) the transaction; if False, unverify (unfinalize) it Returns: Updated transaction information

change_transaction_verification

Mark a manual step (blockedReason manual_step) done — or skipped — after the user says they did it or want to skip it, and let the run continue. Not for questions: those take answer_workflow_question. If the user asks to reopen a completed step, use done=False. This changes checklist progress only; it does not undo the underlying accounting work. Returns: The run.

complete_workflow_step

Confirm a detected routine only after the user explicitly agrees. Confirmation records the user's choice. For a monthly_invoice routine it does not create or send an invoice; offer create_recurring_invoice separately. Use schedule_workflow for a standing workflow schedule.

confirm_routine

Try the current step again after it stopped (blockedReason step_failed), or after the user connected the missing source. Tell the user what stopped it first — the reason is in blockedDetail. Returns: The run.

continue_workflow

Convert a quote into a draft invoice. The quote stays, with the status "invoiced", and the invoice refers to it (sourceDocument). Issue the invoice with update_invoice status "saved" before sending it. Args: offer_id: ID of the quote to convert Returns: The new draft invoice

convert_offer_to_invoice

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

create_annual_close

Germany only. 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 printed on the document; omitted when unknown currency_exchanged: Company accounting currency for exchanged amounts; omitted when unknown description: Description of attachment supplier_country: Country of supplier (DE, PL, 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 — an HTTP(S) download URL accessible without extra headers 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 — content of a small file under 50 KB For images, PDFs, and scans, supply file_url or file_ref; embedding file bytes as base64 can exceed model context limits.

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

Record an incoming invoice/payable when the user asks to add a bill. Review extracted fields before creating it. This does not send money, schedule a bank payment, or file a tax return. A vendor IBAN is optional; SEPA payment from Norman is available only for German companies. Use list_bills first to avoid recording the same invoice twice.

create_bill

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 company. ⚠️ For companies using their own chart, including PL_KPIR and PL_FULL. Read list_company_categories first and use the selected company's chart. Only German SMEs should use search_skr_by_code or suggest_skr_category.

create_company_category

Credit part or all of an issued invoice with a credit note (Rechnungskorrektur; for a Polish company a faktura korygująca). Without items every line of the invoice is credited. Pass items (with the quantities and rates to credit, positive and in minor currency units) to correct part of it; the PDF prints every amount with a minus. 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. correction_reason says why. A Polish credit note of an invoice in KSeF goes there as a correcting invoice (KOR) that states it; when it cannot go yet, the API refuses and says why.

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. vat_exemption_basis: Polish companies only: the legal basis of a VAT exemption, art_113_1, art_113_9 or art_43_1_<point>[_<letter>]. preceding_invoice_number: For a cancel or credit_note made from scratch, the number of the invoice it refers to when that invoice was issued outside Norman. preceding_invoice_date: That invoice's date (YYYY-MM-DD). correction_reason: For a cancel or credit_note: why it is issued. A Polish correction sent to KSeF states it. 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. quote_kind: For document_type="quote" only. "proforma" creates a payment request with its own number series, not a VAT invoice or a tax booking. Convert with convert_offer_to_invoice. Omit or use "offer" for a normal quote. 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. A cancel or credit_note takes positive amounts, like the invoice it corrects, and prints them with a minus. 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. recurring: Repeat this invoice. It becomes the first of a series, and Norman makes the next invoices on the rule, as drafts unless mode says otherwise. Texts may use {month} {year} {quarter} {week} {period}; each invoice fills them from the period it bills. 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. Omit the subject and body to use the company's email template. Example: { "emailSubject": "Invoice No.{invoice_number} for {client_name}", "emailBody": "Dear {client_name},...", "customClientEmail": "client@example.com", // replaces the client's address for this email "additionalEmails": ["accounting@example.com"] // sent as CC } auto_reminders: Send automatic payment reminders for this invoice by the company's rule. Off unless true; only on paid plans. settings_on_overdue: Older reminder schedule, kept for existing integrations. It sends nothing; use auto_reminders. 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

Germany only. 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 (Germany 0, 7, 19; Poland 0, 5, 8, 23); 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

Set up a recurring invoice: a template and a rule. Norman makes nothing in advance. On each run date it makes one ordinary invoice from the template, with the next number of the company's normal sequence. Always confirm with the user: the client, the lines, how often (every N weeks, months or years), the first invoice date, the end (a date, a number of invoices, or none), and what happens on each date (mode). mode: "draft" (default) makes a draft the owner checks and issues; "issue" issues the invoice without sending it; "send" issues it and emails it to the client. Use "send" only when the user asks for automatic sending. Placeholders {month}, {year}, {quarter}, {week} and {period} in item names and descriptions, notes, message, payment terms and the email are filled with the period each invoice covers, for example "Hosting {month} {year}". A first invoice date of today or earlier makes the first invoice at once. 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: client_id: Client public ID items: Invoice items, each with name, quantity, rate (cents) and vatRate. Optional per item: "description", "unit", "productId", "discountPercent". interval: "week", "month" or "year" starts_on: First invoice date (YYYY-MM-DD). It also fixes the weekday or day of month. interval_count: Every how many weeks, months or years (1-99) ends_on: Optional last possible invoice date (YYYY-MM-DD) ends_after: Optional number of invoices. Omit both ends to run until ended. mode: "draft", "issue" or "send" payment_due_days: Days from each invoice date to its due date (0-365) billing_in_advance: True bills the coming period; false bills the period just ended. currency: Invoice currency; omit for the company currency. currency_exchanged: Reporting currency; omit for the company currency. payment_terms: Payment terms text notes: Additional notes language: Invoice language (en, de, pl, it, es) invoice_type: SERVICES or GOODS is_vat_included: Whether prices include VAT create_qr: Print a payment QR code (needs the company IBAN) color_schema: Hex colour; omit to inherit company branding. font: Omit to inherit the company font. settings_on_overdue: Older reminder schedule, kept for existing integrations. It sends nothing; use auto_reminders. online_payment_enabled: Payment links on each invoice; omit for the company setting. auto_reminders: Send automatic payment reminders for each invoice by the company's rule. Off unless true; only on paid plans. source_contract_id: Source contract ID in the active company document_design: Template and appearance settings; omit to inherit the company design. discount_percents: Overall discount percentage tax_exempt_reason: VAT note; omit to derive it per invoice, empty string for none. vat_exemption_basis: Polish companies only: the legal basis of a VAT exemption, art_113_1, art_113_9 or art_43_1_<point>[_<letter>]. instructions: Invoice instructions message: Invoice message company_email: Sender email; omit to use the company email. mailing_data: Email subject, body and recipients for mode "send". Returns: The series with its status, nextRunOn, upcoming dates and the invoices it made.

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

Dismiss a detected routine when the user says it is not useful. It stops being proposed; existing invoices and accounting entries are unchanged. Use unschedule_workflow to stop a workflow schedule instead.

dismiss_routine

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, appearance and bank details, 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

End a recurring invoice for good, including ongoing contract billing. Invoices it already made stay as they are. Call only when the user asks to stop this series; do not infer the end from document text. Args: recurring_invoice_id: ID of the recurring invoice

end_recurring_invoice

Explain whether an operation is in KPiR and why; synchronizes derived entries first.

get_polish_tax_book_operation