Tool reference
This list is generated at build time directly from the server tool registry, no field is hand-maintained. A registered, enabled tool appears with real fields, a registered-but-dark tool shows "Coming soon", an unregistered tool never appears at all. The wire conventions (ISO-8601, cent amounts, clientOrderId, dryRun) are stated once in the Conventions panel, here only as a short per-tool pointer.
apiVersion v1 · schemaRevision 2 · 68 tools
Every tool call can also return one of these transport codes, listed once here: UNAUTHORIZED, FORBIDDEN_SCOPE, VALIDATION_ERROR, RATE_LIMITED, INTERNAL_ERROR
Read
Connection and setup probe: verifies the partner token and the processing chain end to end and reports under setup which prerequisites for a real send are met (sender profile, data processing agreement, balance, sandbox, approval, brand, letterhead, templates) and which step comes next. On a new account, setup.goldenPath lists the setup steps in order. Every step carries humanSummary (de, en), one sentence in everyday language for the person; tool names, nextTool, fixUrl and messageDe/messageEn are machine-facing. checkRender: true also checks whether rendering works right now (preview, thumbnail), for example before building a template that is then checked as an image. The answer arrives in about 3 seconds: a check over its time budget is listed under degraded and reports its cautious default.
Field Type checkRender boolean Optional Also probes the render path (composer + rasterizer). Defaults to false. profile_getScope: profile:readReturns an overview of the partner profile: default sender address, stored signature and letterhead, saved presets, a short wallet summary and the partner's current pricing (standard price or volume tier, including the next tier threshold).
No input fields besides reasoning.
wallet_balanceScope: wallet:readReturns the current wallet status: balance, the amount reserved for waiting letters, the available balance, daily cap for letters and costs, and the next reset time. If the available balance is short of the planned send, wallet_topup_link returns the top-up link.
No input fields besides reasoning.
sender_profile_listScope: sender_profile:readLists all of the partner's sender profiles with their legal form and whether the mandatory details are complete.
No input fields besides reasoning.
sender_profile_getScope: sender_profile:readReturns a single sender profile with all mandatory details, bank account and disclaimer. profileId is optional and defaults to the default profile.
Field Type profileId string (uuid) Optional Optional, defaults to the default profile. Error codes: NOT_FOUND
mandant_getScope: mandant:readReturns a client (Mandant) with addresses, category, case handler, monthly cap, monthly budget used, retention period and the letter count of the last 12 months.
Field Type mandantId string Optional mandantennummer string Optional Error codes: NOT_FOUND
mandant_listScope: mandant:readLists the partner's clients (Mandanten), optionally filtered by search term, category or tag.
Field Type searchQuery string Optional kategorieFilter string Optional tagFilter string Optional since string (date-time) Optional Only clients created since this time (ISO 8601). limit integer Optional Default 20, maximum 100. offset integer Optional Offset for pagination. Default 0. mandant_searchScope: mandant:readSearches clients (Mandanten) by client number, name, tags or case handler and names the matching column for each hit. Next step with the matched mandantennummer: document_create turns it into an invoice, dunning letter, payment reminder or credit note, mandant_get returns the full record, letter_create_draft writes a normal letter.
Field Type query string Required since string (date-time) Optional Only clients created since this time (ISO 8601). limit integer Optional Default 20, maximum 100. offset integer Optional Offset for pagination. Default 0. template_listScope: template:readLists the letter templates (template list) for occasions such as cancellation, invoice, payment reminder, quote, contract and letters to public authorities, with category, version and placeholders (merge fields). The technical tool name is template_list. By default it returns the released templates; statusFilter with the template:write scope also returns open drafts. Every entry says with curated: true whether it is a curated FrankKi standard template (the library to copy from), and with hasBlocks: true whether it carries a structured layout with tables and totals instead of plain text. Next step: template_get returns one template in full (for a block template including blocksTemplate and styleDefs to copy and modify), template_apply_with_merge_fields fills it with values.
Field Type query string Optional Term matched against name and category, e.g. Mahnung or Miete. kategorieFilter string Optional statusFilter released | draft | all Optional released (default) shows every released template. Standalone form templates carry sendable:false and require a cover letter when applied. draft shows only open drafts, all shows both. draft and all additionally require the template:write scope. source own | library | all Optional own returns the account's templates, library the FrankKi library, all (default) both, own first. Every row names its origin in source. limit integer Optional Default 50, maximum 100. offset integer Optional Offset for pagination. Default 0. template_getScope: template:readReturns a single template with subject and content template, the merge fields and the recommended approval default. A block template also returns blocksTemplate and styleDefs; once copied and modified, template_save stores it as an own draft. The crafting chain starts here: template_get on a curated standard template (template_list marks them with curated: true), edits to blocksTemplate, letter_preview renders the state, template_save stores it, template_preview shows the stored version, template_release releases it. With versionId and the template:write scope a specific draft version can be read too. Next step: template_apply_with_merge_fields fills the placeholders with values.
Field Type templateId string (uuid) Required versionId string (uuid) Optional Optional: one specific version, including a draft. Also requires the template:write scope. If omitted, the released version is returned. Error codes: NOT_FOUND
letter_getScope: letter:readReturns one of the partner's letters together with its order and a download URL for the PDF valid for 24 hours. status is the letter status; before the order exists, a letter in the approval queue carries the same status as in order_status: pending_approval, approved_in_grace or queued_autopilot, plus approval with its approvalId. letterStatus is the stored letter status.
Field Type letterId string (uuid) Optional orderId string (uuid) Optional letter_listScope: letter:readLists the partner's letters with optional filters by recipient name, subject, status and time. status is the letter status; before the order exists, a letter in the approval queue carries the same status as in order_status: pending_approval, approved_in_grace or queued_autopilot, plus approval with its approvalId. letterStatus is the stored letter status.
Field Type recipientNameContains string Optional subjectContains string Optional statusFilter draft | ready | ordered | printed | shipped | delivered | pending_approval | sent | unsent Optional Letter status draft, ready, ordered, printed, shipped or delivered. pending_approval means letters waiting for approval; draft and ready hold the remaining letters in that state. sent means every letter with an accepted order, unsent every other letter. since string (date-time) Optional limit integer Optional offset integer Optional sender_profile_validateScope: sender_profile:readChecks whether a sender profile (by profileId) or a proposed field set contains all mandatory details for its legal form. The call takes exactly one form: profileId OR rechtsform + proposedFields. proposedFields is an object; a JSON-encoded object string is also accepted. Returns valid, missingFields and soft hints. Reports a gap as a result and keeps running.
No input fields besides reasoning.
analytics_summaryScope: analytics:readReturns the partner account's aggregated metrics: letters per month, cost per mandant for rebilling, transit times to delivery, failure rates, and spend against configured limits. Amounts are net cost in cents.
Field Type metric overview | letters_per_month | cost_per_mandant | delivery_times | failure_rates | spend_vs_caps Optional Which report. overview (default) summarises the last three months. months integer Optional Trend length for letters_per_month and failure_rates, 1 to 24, default 12. since string Optional Range start, for example 2026-01-01. Default: last 90 days. until string Optional Range end, default now. topN integer Optional Number of mandants in cost_per_mandant, 1 to 50, default 10. address_listScope: address:readLists the addresses in the partner address book. Optionally filtered by name, city or client.
Field Type searchQuery string Optional limit integer Optional offset integer Optional Offset for pagination. Default 0. address_validateScope: address:readValidates an address using country-specific rules and returns valid (the same verdict as the order_send address check) plus, per field, what is missing, malformed or differs from the city. A check only, the address book is left untouched; address_upsert creates and changes addresses.
Field Type name string Required company string Optional street string Required houseNumber string Optional pobox string Optional zip string Optional city string Required country string Optional ISO 3166-1 alpha-2, defaults to DE. mandantennummer string Optional addressType recipient | sender | billing Optional isDefault boolean Optional template_apply_with_merge_fieldsScope: template:readFills a saved template and returns subject and content or a complete cover-form package. For a block template the finished blocks are returned instead of content. Letterhead and brand are selected separately at preview or send time. A standalone form template with sendable:false and releaseBlocker:null needs coverTemplateId from a directly addressable letter template; a saved link is only the optional default. order_send sends the result with templateId, templateVersionId, coverTemplateId, coverTemplateVersionId and the original templateMergeValues and re-renders exactly that version from them. order_send expects the package sections in the form in which they come back here. If a required value is missing, the tool returns MERGE_FIELDS_MISSING and lists the missing or invalid fields.
Field Type templateId string (uuid) Required The template ID from template_list / template_get. templateVersionId string (uuid) Optional Exact released or superseded template version. If omitted, the currently released version is used. coverTemplateId string (uuid) Optional Optional cover letter for a standalone form template. Required when applying a form that has no saved link. coverTemplateVersionId string (uuid) Optional Optional exact released version of the selected cover letter. mergeValues object Optional Mapping of placeholder names to values, e.g. { "provider": "Telekom" }. The merge field's type applies: date expects ISO YYYY-MM-DD, currency integer cents, number a number, rows a list of row objects keyed by the bound table's column keys. language de | en Optional Language for money and date formatting. Defaults to de. mandantennummer string Optional Optional client reference (context only). Error codes: NOT_FOUND
shipping_quoteScope: letter:readDetermines price, letter format, shipping method and estimated delivery time for a planned letter, before it is sent. The estimate needs only page count, country and delivery type. Once the letter exists, order_send sends it, and order_send with dryRun:true gives the more precise price for that specific letter. The price is per letter and already includes the partner's volume tier where one applies (field tierId); pricing_tiers returns the volume tiers themselves. Registered-mail availability follows the destination's current catalog. The codes einschreiben_einwurf and einschreiben_uebergabe are German products; Switzerland uses ch_einschreiben. For other destinations, a standard shipping_quote for that country lists the available methods in availableDeliveryTypes, and a quote for the chosen code returns its price. A rejected country/method pair gives a verdict for that pair alone. A catalog snapshot gives a verdict for that snapshot alone. Tracked mail and registered mail are distinct products.
Field Type pageCount integer Required Page count for a general estimate. With letterId, FrankKi uses the stored page count and ignores this value. color boolean Optional Colour for an estimate. Defaults to the colour of the default letterhead. With letterId, FrankKi reads the colour from the stored preview. deliveryType standard | einschreiben_einwurf | einschreiben_uebergabe | ch_b_post | ch_a_post | ch_einschreiben | at_eco | at_prio | intl_standard | intl_priority | intl_express | intl_tracked | intl_registered Required Delivery method code. Registered mail: einschreiben_einwurf and einschreiben_uebergabe for Germany, ch_einschreiben for Switzerland; for other countries a standard quote names the codes in availableDeliveryTypes. express boolean Optional country string, max 2 chars Optional ISO 3166-1 alpha-2, defaults to DE. letterId string (uuid) Optional Optional: the letterId of an existing draft. Page count and colour then come from the stored preview; order_send with dryRun:true returns the final price including attachments. pricing_tiersScope: letter:readReturns FrankKi's volume tiers (bulk discounts): from which monthly quantity which example price per letter applies. It answers questions about bulk discounts, volume pricing or enterprise pricing. The example prices are for a one-page black and white standard letter within Germany; the real per-letter price also depends on page count, color, delivery type and destination country (shipping_quote returns that).
No input fields besides reasoning.
order_statusScope: order:readReturns where a letter stands: status, German tracking history, tracking number (registered mail), estimated delivery and whether it can still be cancelled. The call takes exactly one id: orderId, approvalId (from order_send while orderId is null) or letterId. Before dispatch the status is queued_autopilot with dispatchAt, humanSummary (de, en) and cancelWith. On awaiting_partner_fix the letter waits for order_fix_resubmit; on failed, failure gives the reason and nextStep the way back. While cancellable is true, order_cancel stops the send.
Field Type orderId string (uuid) Optional approvalId string (uuid) Optional From order_send while orderId is null. letterId string (uuid) Optional Error codes: NOT_FOUND
order_einlieferungsbelegScope: order:readReturns the proof of posting (Einlieferungsbeleg) for a sent order, once the letter is handed in and the mail provider issues one: a download URL for the receipt valid for 7 days (a PDF where the mail provider issues one, otherwise a JSON record built from its status data; belegFormat names the format, and a new call returns a fresh link), the postmark, the mail provider and the verified record from the GoBD archive. The receipt shows the hand-in at the post. The tracking number and delivery status of registered mail come from order_status.
Field Type orderId string (uuid) Required Error codes: NOT_FOUND
approval_listScope: approval:readLists the account's approvals, newest first, with a time-limited PDF preview, the cost, the reason and the deadlines. By default the pending approvals plus approved letters still waiting in their cancel window (autopilot, chat); graceState names dispatchAt. status all lists everything. approval_decide decides on one of the returned approvalIds.
Field Type status pending | approved | rejected | expired | all Optional Default: pending plus cancel window. since string (date-time) Optional Only approvals submitted since this time (ISO 8601). approvalId string Optional One approval with every detail: all template diff segments and every batch recipient. Without approvalId the list shortens both. limit integer Optional Default 20, maximum 100. offset integer Optional Offset for pagination. Default 0. setup_fix_linkScope: profile:readHands one item over to the human in a browser: top up the balance, sign the data processing agreement or complete the sender profile. Returns the matching page plus a card that visibly keeps the letter draft and notices by itself when the human is back. Payment happens in the browser.
Field Type gap wallet | avv | senderProfile Required Which item is handed over: wallet (balance), avv (data processing agreement) or senderProfile (sender profile). wallet_topup_linkScope: wallet:readCreates a Stripe checkout link to top up the wallet balance. Card data stays with Stripe; the balance is credited once the payment completes.
Field Type amountEuros number Required Top-up amount in euros, between 10 and 500. requestNonce string, max 200 chars Optional Optional stable retry key. On a retry send the same value to get the same checkout link instead of a second one. Error codes: INSUFFICIENT_FUNDS
template_diff_checkScope: template:readCompares a finished letter with its template and shows where it deviates. A block template compares finalBlocks in place of finalContent, text by text in reading order. Free and read-only.
Field Type templateId string (uuid) Required The template ID from template_list / template_get. versionId string (uuid) Optional Optional: a specific version, otherwise the released one. finalSubject string Required The letter's final subject line. finalContent string Optional The final letter text. A block letter comes as finalBlocks. finalBlocks Array<object> Optional The final blocks when the letter is structured. The texts are compared in reading order. mergeFields object Optional Mapping of placeholder names to values, e.g. { "provider": "Telekom" }. Error codes: NOT_FOUND
letter_design_listScope: letter_design:writeLists the partner's saved letterheads (letter designs) with name, id and hashes; with designId it returns one design with its full design JSON. A design is referenced by name or id when sending and carries every kind of mail: cancellation, invoice, payment reminder, quote, contract and letters to public authorities.
Field Type includeArchived boolean Optional true includes archived (deleted) designs. Defaults to false. designId string (uuid) Optional One letter design with its full design JSON. Without designId the list gives name, id and hashes per design, without the design JSON. letter_design_previewScope: letter_design:writeRenders a saved or inline letter design (schemaVersion 1 or 2) with the same composer as a real send, using real sender data, a fictional recipient and sample text. Returns one inline PNG page, page 2 only for continuationHeader, links only with pages 0. sampleVariant empty shows the stationery alone, as in the dashboard. It previews a cancellation, invoice, payment reminder, quote, contract or letter to a public authority on this stationery. Free of charge; the letter stays a draft.
Field Type designId string (uuid) Optional design unknown Optional reference object Optional sampleSubject string, max 200 chars Optional sampleContent string, max 4000 chars Optional sampleVariant typical | empty Optional typical shows a full example page, empty the stationery alone with an open text area. sampleContent takes precedence. pages integer Optional Default 1, page 2 only with continuationHeader, 0 links only. resolution thumb | full Optional Error codes: DESIGN_NOT_FOUND, DESIGN_RENDER_FAILED, DESIGN_ZONE_VIOLATION
letter_design_list_presetsScope: letter_design:writeReturns the owner-approved native-v2 letterheads as safe starting points for cancellations, invoices, payment reminders, quotes, contracts and letters to public authorities. It grows with every curated design that passes review. The plain list gives id, name, description and tags per preset; presetId returns the full design and exactly one real-composer preview with an inline PNG.
Field Type presetId string Optional Optional: loads one preset with its rendered preview. Without presetId the list stays image-free and cheap. pages integer Optional resolution thumb | full Optional brand_kit_getScope: profile:readReads the saved brand values for the user-facing result letterhead and brand. Returns logo references, colours and font for further work with letter_design_preview and letter_design_save. Technical tool name: brand_kit_get.
No input fields besides reasoning.
signature_listScope: profile:readLists the signatures stored in the partner profile with a short-lived preview URL (valid for 24 hours).
No input fields besides reasoning.
letterhead_listScope: profile:readLists the letterheads stored in the partner profile with a short-lived preview URL (valid for 24 hours).
No input fields besides reasoning.
schedule_listScope: letter:scheduleLists the partner's scheduled sends with date, status and reserved amount.
Field Type statusFilter scheduled | sent | cancelled | failed Optional Only schedules with this status. address_search_companyScope: address:readSearches companies and public authorities in the directory and returns the matching mailing address including an authority PO box.
Field Type query string Required country string Optional letter_searchScope: letter:readFull-text searches the partner's letters across subject, recipient name and letter content. status is the letter status; before the order exists, a letter in the approval queue carries the same status as in order_status: pending_approval, approved_in_grace or queued_autopilot, plus approval with its approvalId. letterStatus is the stored letter status.
Field Type query string Required since string (date-time) Optional Only letters modified since this time (ISO 8601). limit integer Optional Default 20, maximum 100. offset integer Optional Offset for pagination. Default 0. archive_exportScope: archive:readSchedules an archive export (GoBD CSV, DATEV, PDF bundle or client allocation) for a date range and returns a job ID to query its status.
Field Type since string (date-time) Required until string (date-time) Required format gobd_csv | datev_export | pdf_bundle | mandant_allocation_pdf | mandant_allocation_csv Required target string Optional mandantennummerFilter string Optional senderProfileFilter string (uuid) Optional notifyEmail string (email) Optional Error codes: NOT_FOUND
archive_export_statusScope: archive:readReturns the status of an archive export job and, once complete, a download URL valid for 90 days.
Field Type jobId string (uuid) Required Error codes: NOT_FOUND
letter_previewScope: order:sendRenders a letter, draft or form as images, composed like a real send, and returns inline PNGs, PDF link, page count, cost and designRender with the actual documentMode, rendered letter chrome and bodyStartMm. The preview is free and the letter stays put. The letter comes via letterId, a released template (templateId, templateVersionId, templateMergeValues) or inline content OR blocks; the recipient via recipientAddressId or the recipient fields. With letterId, the embedded card is the human preview; the PDF link and letter text are also in the result, for text-only views. An unsaved design applies to this one preview only. Standalone forms (self-declaration, questionnaire, certificate) render as a form with design: { "schemaVersion": 1, "documentMode": "form" }: that drops recipient block, date and subject and starts content at 27 mm. Schema reference: frankki://blocks-guide. For a rebuild of an original, the PNGs show page by page whether page count and major geometry match; changed blocks or a changed design render again on the next letter_preview call. template_save stores the matching layout as a draft, template_release releases it.
Field Type letterId string (uuid) Optional Stored draft to preview. The letter can come inline instead. subject string, max 200 chars Optional Subject. Required without a letterId. content string, max 30000 chars Optional Letter body as plain text. Exactly one of content and blocks. blocks Array<unknown> (min 1, max 200) Optional Structured letter content as typed blocks, in place of content. Limits: 200 blocks, 100 rows per table, 20 columns, 2000 characters per cell, 10 images, 262144 bytes. styleDefs object Optional Named document styles (max 24); blocks reference them via style. language de | en Optional designId string (uuid) Optional Saved letter design for this preview. design object Optional Unsaved letter design for this preview only. Takes precedence over designId and creates no account entry. Standalone forms render with documentMode: "form". reference object Optional Per-letter values (Vorgangsnummer, Ihr Zeichen, customer number, QR parameters ...). They fill the info block and barcode in the preview. senderProfileId string (uuid) Optional pages integer Optional How many pages come back as images. Default 3, maximum 8. The PDF link contains every page. resolution thumb | full Optional thumb (96 dpi, default, fast and small) or full (150 dpi, for checking details). templateId string (uuid) Optional templateVersionId string (uuid) Optional Released template version, with templateId and templateMergeValues: shows exactly the letter order_send would send with them. templateMergeValues object Optional recipientAddressId string (uuid) Optional Recipient from the address book. Alternatively the recipient fields; if both are missing, a sample recipient fills the window. recipientName string Optional recipientCompany string Optional recipientStreet string Optional recipientHouseNumber string Optional recipientZip string Optional recipientCity string Optional recipientCountry string Optional ISO 3166-1 alpha-2, defaults to DE. template_previewScope: template:readRenders a STORED template with sample values and returns inline PNGs, PDF link and designRender. designId or an unsaved design selects the stationery; standalone forms render with documentMode: "form". The preview is free of charge and purely for looking at. letter_preview renders a blocks layout still in the making; template_save stores a finished version (technical tool name template_save).
Field Type templateId string (uuid) Required The template ID from template_list / template_get. versionId string (uuid) Optional Exact template version to inspect. If omitted, the released version is used, then the newest draft. designId string (uuid) Optional Saved letter design for this template preview. designVersionId string (uuid) Optional Exact immutable letterhead version for this preview. design object Optional Unsaved letter design for this preview only. Forms render with documentMode: "form". pages integer Optional How many pages come back as images. Default 1, maximum 3. 0: PDF link only. Error codes: NOT_FOUND
document_listScope: letter:readLists the account's created documents (invoice, payment reminder, dunning letter, credit note), newest first, filtered by type, client, recipient or referenced document. Next step: document_get returns the full payload, document_create creates a follow-up document via references.
Field Type documentType rechnung | zahlungserinnerung | mahnung | gutschrift Optional mandantennummer string Optional recipientQuery string Optional free text over the recipient name, company or city. referencesDocumentId string (uuid) Optional only documents referring to this FrankKi document (for example every dunning letter for one invoice). referencesNumber string Optional since string (date-time) Optional limit integer Optional default 20, maximum 100. offset integer Optional offset for pagination. Default 0. document_getScope: letter:readReturns one document with its full payload (line items, totals, VAT rates, reference) plus the letterId and orderId of the letter it lives in. The field referencePrefill carries the ready-made references block for a follow-up document: document_create takes it unchanged as document.references for a dunning letter, payment reminder or credit note. Under exports FrankKi returns signed download links for sent invoices and credit notes: zugferdPdfUrl is a PDF/A-3 with embedded EN 16931 XML (ZUGFeRD), xrechnungXmlUrl the pure XRechnung XML. Both are download-only; transmitting an e-invoice to a portal stays with the partner. When an export is missing the slot names the reason: DOCUMENT_EXPORT_NOT_READY means for now, a later call returns the export (the send or the activation is still pending), DOCUMENT_EXPORT_NOT_SUPPORTED means permanently (the export covers invoices and credit notes; for a dunning letter or payment reminder the invoice they refer to carries the export). Next step: order_status tracks the send, document_create creates a dunning letter or credit note via references.
Field Type documentId string (uuid) Required
Action
sender_profile_upsertScope: sender_profile:writeno dryRunCreates or edits a sender profile: legal form, mandatory details, optionally bank details, disclaimer and default letterhead. An incomplete profile is saved and reports its missing fields back, so it can be completed step by step. Sending works once they are complete.
Field Type id string Optional Id of an existing profile to edit; the changed fields are enough. null in pflichtangaben removes a field. A legal-form change drops the old form's fields. Omitting creates a new one. rechtsform string Optional The sender's legal form. It determines the required mandatory details. pflichtangaben object Optional Mandatory details as an object. sender_profile_validate names the fields required per legal form. bankverbindung object Optional Optional bank details with iban, bic and bankname, independent of completeness. They print in the footer and under invoices. disclaimer string Optional Optional disclaimer or footer, independent of completeness. displayName string Optional Optional display name in lists. isDefault boolean Optional true makes this the default sender. The first profile created becomes default. defaultDesignId stringnull Optional Letterhead for letters naming none. Omitting keeps the value, null clears it. address_upsertScope: address:writeno dryRunCreates or updates an address in the partner address book. Validates the address using country-specific rules.
Field Type addressId string (uuid) Optional name string Required company string Optional street string Required houseNumber string Optional pobox string Optional zip string Optional city string Required country string Optional ISO 3166-1 alpha-2, defaults to DE. mandantennummer string Optional addressType recipient | sender | billing Optional isDefault boolean Optional Error codes: ADDRESS_INVALID
Creates a letter draft: produces a preview PDF in the stored letter design (letter body only), stores the draft and returns page count, preview link (valid for 24 hours) and a non-binding cost estimate. The draft stays free of charge until it is sent. The body is either content (plain text) OR blocks (structured: tables, headings, totals lines), exactly one of the two. Compact blocks example: {"blocks":[{"type":"heading","text":"Rechnung"},{"type":"table","columns":[{"key":"text","label":"Artikel","width":"grow"},{"key":"sum","label":"Summe","align":"right","format":"eur"}],"rows":[{"text":"Beratung","sum":32000}]},{"type":"totals","lines":[{"label":"Gesamt","amountCents":32000,"emphasis":true}]}]} Schema reference incl. styleDefs and limits: MCP resource frankki://blocks-guide. The first pages come back as images and show subject, address in the address window, sender, date and line breaks as they will print. The embedded card is the human preview; the PDF link and letter text are also in the result, for text-only views. Reported findings are in warnings. A new call creates a corrected draft; a printed letter is final. For a Mahnung, Kündigung, Mieterhöhung or other deadline letter, Einschreiben adds a proof of posting; shipping_quote returns its price. Next step with the returned letterId: letter_preview shows the draft as an image to refine it, order_send sends the draft, letter_schedule sends it at a later time.
Field Type subject string, max 200 chars Required content string, max 30000 chars Optional Letter body as plain text. Exactly one of content and blocks. blocks Array<unknown> (min 1, max 200) Optional Structured letter content as typed blocks, in place of content. Limits: 200 blocks, 100 rows per table, 20 columns, 2000 characters per cell, 10 images, 262144 bytes. styleDefs object Optional Named document styles (max 24); blocks reference them via style. language de | en Optional Defaults to de. senderAddressId string (uuid) Optional senderProfileId string (uuid) Optional Sender profile the letter will later be sent with. For the preview only its default letter design is used. recipientAddressId string (uuid) Optional A saved address from the address book (address_list) as the recipient. Equivalent: recipientAddressInline or the fields recipientName to recipientCountry as on order_send. recipientName string Optional recipientCompany string Optional recipientStreet string Optional recipientHouseNumber string Optional recipientZip string Optional recipientCity string Optional recipientCountry string Optional recipientAddressInline object Optional presetName string Optional includeSignature boolean Optional true places the stored signature under the letter text. Off by default, same as on send. signatureId string (uuid) Optional A specific stored signature in place of the first one on file. clientLetterId string Optional Idempotency key. A repeat call with the same value AND the same payload returns the same draft instead of creating a second one. A different letter needs a new key: the same key with different content ends with IDEMPOTENCY_CONFLICT and creates no draft. designId string (uuid) Optional Saved letter design for this letter. It is already rendered into the preview PDF and stored on the draft so a later send by letterId inherits it (unless the send names its own design). If omitted, the sender profile default design applies, in the preview as well as on send. reference object Optional Per-letter values (Vorgangsnummer, Ihr Zeichen, customer number, QR parameters ...). They fill the info block and the barcode. attachment_upload_pdfScope: order:sendno dryRunUploads a PDF as an attachment to a partner letter. Before saving, it checks the file size (max. 50 MB) and the merged page count (max. 30 pages including the letter and other attachments). Printing is A4 portrait only: FrankKi shrinks any other page (US Letter, A5, landscape) onto A4, and the answer names it in pageFormatNote.
Field Type letterId string (uuid) Required pdfUrl string Optional Public URL of the PDF (alternative to pdfBase64). pdfBase64 string Optional PDF as Base64 (alternative to pdfUrl). title string Optional position integer Optional attachment_upload_imageScope: order:sendno dryRunUploads an image (PNG/JPEG) as an attachment to a partner letter. The image is scaled to an A4 PDF page server-side (optionally rotated) and stored like a PDF. Before saving, it checks the merged page count (max. 30 pages). EXIF orientation is applied to the pixels automatically, so a phone photo is upright by itself. rotation turns the image further by the given degrees; 0 keeps it as uploaded.
Field Type letterId string (uuid) Required imageUrl string Optional Public URL of the image (alternative to imageBase64). imageBase64 string Optional Image as Base64 (alternative to imageUrl). rotation 0 | 90 | 180 | 270 Optional Additional clockwise rotation in degrees. The image's EXIF orientation is already baked into the pixels automatically, so the image is upright on its own. This value turns it a second time on top of that. For a phone photo, 0 is therefore the correct value. title string Optional position integer Optional letter_upload_pdfScope: order:sendno dryRunUploads a finished letter PDF that is sent exactly as it is. The check looks at whether the recipient address sits in the address zone of the delivery method. For a standard letter that is 60 to 85.5 mm from the top, for Einschreiben 68 to 85.5 mm, both 22 to 107.5 mm from the left. The rest of the window area stays empty, every edge keeps 5 mm clear, and every page is A4 portrait. The result holds pdfStorageKey, the findings with the millimetres to move, and page 1 with the zones drawn in. sendable says whether order_send accepts this pdfStorageKey. When only the postcode or city differs, either the recipient fields or the PDF can be corrected; every other finding needs a corrected PDF and a new upload. Free.
Field Type pdfBase64 string Optional The letter PDF as Base64 (alternative to pdfUrl). pdfUrl string Optional Public URL of the letter PDF (alternative to pdfBase64). deliveryType standard | einschreiben_einwurf | einschreiben_uebergabe | ch_b_post | ch_a_post | ch_einschreiben | at_eco | at_prio | intl_standard | intl_priority | intl_express | intl_tracked | intl_registered Optional Delivery method the address zone is checked for; the same one order_send gets later. Defaults to standard. recipientZip string Optional Optional: recipient postcode, compared with the printed address. recipientCity string Optional Optional: recipient city, compared with the printed address. Sends a letter by post: checks the sender's mandatory details, the recipient address, the AVV and the limits, creates the PDF and calculates the price. The letter arrives via letterId (a draft) or inline: then the body is content (plain text) or blocks (structured: tables, headings, totals lines), exactly one of the two. Compact blocks example: {"blocks":[{"type":"heading","text":"Rechnung"},{"type":"table","columns":[{"key":"text","label":"Artikel","width":"grow"},{"key":"sum","label":"Summe","align":"right","format":"eur"}],"rows":[{"text":"Beratung","sum":32000}]},{"type":"totals","lines":[{"label":"Gesamt","amountCents":32000,"emphasis":true}]}]} Schema reference: frankki://blocks-guide. dryRun: true is a free rehearsal: it returns the price, page 1 as an image and the checks list (each gate with passed, failed or skipped), and the letter stays unsent; a second call with the same values and dryRun: false sends exactly that letter. A real send waits for approval. Autopilot is a dashboard setting the person controls: with it, a standard letter from an own released template (templateId plus templateVersionId) to an address-book recipient leaves after 10 minutes. saveRecipient: true adds the recipient on the way, humanSummary names the time, order_status and order_cancel take the approvalId. mcp_health reports under setup which approval path applies. For a Mahnung, Kündigung, Mieterhöhung or other deadline letter, Einschreiben adds a proof of posting; shipping_quote returns its price. A finished own PDF goes out unchanged: letter_upload_pdf checks and stores it, then order_send sends it with pdfStorageKey and the recipient.
Field Type letterId string (uuid) Optional Existing draft. The letter can come inline instead. pdfStorageKey string Optional The key from letter_upload_pdf, when an own finished PDF is the letter, in place of subject and body. It goes with the recipient fields exactly as printed on the PDF, and the deliveryType. The send checks that the address sits in the address zone of the delivery method, 60 to 85.5 mm from the top for a standard letter and 68 to 85.5 mm for Einschreiben. If it sits elsewhere, PDF_LAYOUT_INVALID gives the millimetres to move. subject string, max 200 chars Optional content string, max 30000 chars Optional Letter body as plain text. Exactly one of content and blocks. blocks Array<unknown> (min 1, max 200) Optional Structured letter content as typed blocks, in place of content. Limits: 200 blocks, 100 rows per table, 20 columns, 2000 characters per cell, 10 images, 262144 bytes. styleDefs object Optional Named document styles (max 24); blocks reference them via style. recipientAddressId string (uuid) Optional A saved address from the address book (address_list) as the recipient, in place of the fields recipientName to recipientCountry. recipientName string Optional recipientCompany string Optional recipientStreet string Optional recipientHouseNumber string Optional recipientZip string Optional recipientCity string Optional recipientCountry string Optional ISO 3166-1 alpha-2, defaults to DE. priceVersion string Optional Optional: the priceVersion from an earlier shipping_quote. If the price at send time differs, the call is aborted with PRICE_CHANGED before anything is charged. quotedUnitPriceCents integer Optional Optional: the unit price in cents from an earlier shipping_quote (unitPriceCents). If set, it decides the PRICE_CHANGED comparison and returns the old price in the error. deliveryType standard | einschreiben_einwurf | einschreiben_uebergabe | ch_b_post | ch_a_post | ch_einschreiben | at_eco | at_prio | intl_standard | intl_priority | intl_express | intl_tracked | intl_registered Optional Defaults to standard. express boolean Optional color boolean Optional If omitted, colour is detected automatically. includeSignature boolean Optional signatureId string (uuid) Optional letterheadId string (uuid) Optional A specific letterhead for this send. If omitted, the default letterhead is used. letterheadEnabled boolean Optional false leaves the letterhead off for this one send. senderAddressId string (uuid) Optional senderProfileId string (uuid) Optional mandantennummer string Optional clientOrderId string, max 200 chars Optional Idempotency key: any string (1-200 characters, e.g. 'mahnung-kunde42-2026-07-20'; no UUID format required). A repeat call with the same value returns the same order instead of sending a second time. The 'approval:' namespace is reserved. scheduledAt string (date-time) Optional approvalMode auto | draft | review Optional How the send is approved. 'draft' and 'review' put it into the approval queue instead of sending immediately. 'auto' is currently treated exactly like 'review': the letter waits for a person to approve it. With a test token every mode runs as a rehearsal. Both still reserve the amount in the wallet at submit time, so an approved letter cannot fail on funds later. Without cover the call returns INSUFFICIENT_FUNDS and nothing is created. letter_create_draft creates a draft with no wallet cover. maxCostEuros number Optional Maximum amount in euros. If the price is above it, the call is aborted. presetName string Optional auditTag string Optional templateId string (uuid) Optional templateVersionId string (uuid) Optional Exact released template version. Only with templateId; the server rerenders it with templateMergeValues and ignores caller-supplied subject/content. templateMergeValues object Optional Merge values for the exact template version. coverTemplateId string (uuid) Optional Cover letter for a standalone form template. coverTemplateVersionId string (uuid) Optional Exact released version of the cover letter. designId string (uuid) Optional Saved letter design for this send. If omitted, in order: the design stored on the draft (when sending by letterId), else the sender profile default design, else none. design object Optional Exact letter-design snapshot from template_apply_with_merge_fields.composition.design. Takes precedence over designId and prevents later design edits from changing the released template composition. reference object Optional Per-letter values (Vorgangsnummer, Ihr Zeichen, customer number, QR parameters ...). They fill the info block and the barcode. dryRun boolean Optional Free rehearsal; returns page 1 as an image and the checks list (each gate with passed, failed or skipped). saveRecipient boolean Optional true saves the recipient to the address book with this send (for autopilot). includeGeometry boolean Optional Also returns the page layout data. Idempotency key: clientOrderId (see Conventions).
Error codes: SENDER_PFLICHTANGABEN_INCOMPLETE, ADDRESS_INVALID, AVV_REQUIRED, DAILY_CAP_EXCEEDED, MANDANT_CAP_EXCEEDED, COST_OVER_LIMIT, CONTENT_REJECTED, COUNTRY_NOT_SUPPORTED, LEGAL_PROOF_UNAVAILABLE_FOR_COUNTRY, PRICE_UNAVAILABLE, PDF_LETTER_UNSUPPORTED, SANDBOX_DISABLED, IDEMPOTENCY_CONFLICT, DESIGN_NOT_FOUND, DESIGN_RENDER_FAILED, DESIGN_ZONE_VIOLATION
Submits a letter for human approval: checks mandatory details, recipient, data processing agreement and limits, creates the final PDF, calculates the price, reserves the cost and adds an approval to the queue. It waits for a person's decision, also with autopilot. The embedded card is the preview and approval. The PDF link and letter text are also in the result, for text-only views. With approval:self_approve, the card shows Approve and Reject. In every other case it opens the signed-in portal. With dryRun, the balance and queue remain untouched, and the answer contains the checks list (each gate with passed, failed or skipped).
Field Type letterId string (uuid) Optional Existing draft. The letter can come inline instead. subject string, max 200 chars Optional content string, max 30000 chars Optional recipientAddressId string (uuid) Optional A saved address from the address book (address_list) as the recipient, in place of the fields recipientName to recipientCountry. recipientName string Optional recipientCompany string Optional recipientStreet string Optional recipientHouseNumber string Optional recipientZip string Optional recipientCity string Optional recipientCountry string Optional ISO 3166-1 alpha-2, defaults to DE. deliveryType standard | einschreiben_einwurf | einschreiben_uebergabe | ch_b_post | ch_a_post | ch_einschreiben | at_eco | at_prio | intl_standard | intl_priority | intl_express | intl_tracked | intl_registered Optional Defaults to standard. express boolean Optional color boolean Optional If omitted, colour is detected automatically. includeSignature boolean Optional signatureId string (uuid) Optional senderAddressId string (uuid) Optional senderProfileId string (uuid) Optional mandantennummer string Optional clientOrderId string Optional Idempotency key. A repeat call with the same value returns the same approval instead of submitting a second time. The 'approval:' prefix is reserved. scheduledAt string (date-time) Optional approvalMode auto | draft | review Optional maxCostEuros number Optional Maximum amount in euros. If the price is above it, the call is aborted. presetName string Optional auditTag string Optional templateId string (uuid) Optional reason string, max 500 chars Optional Short reason for the approval, shown to the reviewer on the card. requesterContext string, max 500 chars Optional Additional context about the submitter or the occasion. dryRun boolean Optional Idempotency key: clientOrderId (see Conventions).
Error codes: SENDER_PFLICHTANGABEN_INCOMPLETE, ADDRESS_INVALID, AVV_REQUIRED, DAILY_CAP_EXCEEDED, MANDANT_CAP_EXCEEDED, COST_OVER_LIMIT, CONTENT_REJECTED, IDEMPOTENCY_CONFLICT
Approves or rejects a pending approval. 'approve' requires that this OAuth connection carries the separately granted approval:self_approve scope. When that scope is absent, the human opens the returned approvalUrl and decides in the signed-in portal. approval:decide is also required. An agent approval dispatches after 10 minutes and can be stopped with order_cancel until then.
Field Type approvalId string (uuid) Required decision approve | reject Required comment string, max 1000 chars Optional clientOrderId string Optional Idempotency key: clientOrderId (see Conventions).
Error codes: APPROVAL_ALREADY_DECIDED, NOT_FOUND
order_cancelScope: order:sendno dryRunCancels a letter and credits the amount to the account's wallet (closed loop, credited to the wallet rather than the card). With orderId it cancels an existing order within the cancellation window; if the letter is already printing the call is cleanly rejected. With approvalId it stops a chat-approved send within its 10-minute grace window before it is even sent (the human says 'stop').
Field Type orderId string (uuid) Optional The order to cancel. approvalId string (uuid) Optional In place of orderId: stops a chat-approved send within its 10-minute grace window before it is sent (the human says 'stop'). reason string, max 500 chars Optional Optional cancellation reason. Error codes: NOT_FOUND
template_saveScope: template:writeno dryRunSaves a template as a DRAFT (save template, save template version, create template draft). documentKind is letter or form. Letterhead and brand are an external layer resolved at preview or send time and stay outside the template. designId remains only as a deprecated hint for inferring document kind; explicit documentKind wins. A form can be saved on its own. coverTemplateId may pin a cover-template version for a package. When templateId is absent, a new template is created; with templateId, a new draft version. The draft becomes usable on release; the response includes the review link. The technical tool name is template_save. The template body is either contentTemplate (plain text) OR blocksTemplate (structured: tables, headings, totals lines), exactly one of the two. Merge fields are typed (text, date, number, currency, rows); a table block binds a rows list via rowsFrom. The fastest start is a standard template from template_get, copied and modified. letter_preview renders the state before saving, page by page next to the original; a rebuild is done when page count and major geometry match the original. Standalone forms render in letter_preview with a design in documentMode "form".
Field Type templateId string (uuid) Optional Existing template: a NEW draft version is created. If omitted, a new template is created. name string Required Name of the template. kategorie stringnull Optional Subject category, e.g. kuendigung (termination). subjectTemplate string Required Subject template, may contain {{placeholders}}. contentTemplate string Optional Content template as plain text, may contain {{placeholders}}. Either contentTemplate OR blocksTemplate. blocksTemplate Array<unknown> (min 1, max 200) Optional Structured content template (tables, headings, totals lines). Text fields may contain {{placeholders}}; a table block can bind a rows merge field via rowsFrom: "<key>" and receives its rows on apply. Either contentTemplate OR blocksTemplate. styleDefs object Optional Named styles of the block template. Only together with blocksTemplate. mergeFields Array<object> (max 100) Optional The placeholders of the template. approvalModeRecommended auto | review | draft | Optional Recommended approval mode for letters from this template. documentKind letter | form Optional Immutable document kind of the template version. letter is directly addressable; form requires a cover letter. designId string (uuid) Optional Deprecated authoring hint used to infer documentKind. The design is not stored on the template. Explicit documentKind wins. clearDesign boolean Optional Deprecated compatibility authoring hint. New template versions have no design binding. coverTemplateId string (uuid) Optional Cover template for a form without a recipient block. Saving pins its exact current released version. clearCoverTemplate boolean Optional Removes the inherited cover-template pin. Without coverTemplateId and clearCoverTemplate, a new version inherits the previous pin. Error codes: NOT_FOUND, TEMPLATE_SLUG_CONFLICT
template_releaseScope: template:writeno dryRunReleases a draft version so it can be sent; last step of the crafting chain (template_get, modify, letter_preview, template_save, template_preview, template_release). template_preview shows the human an approval card with a Release button. template_release makes the version sendable at once, bypassing that card, which the person otherwise confirms; the response records the release as released by the agent. Via MCP this works on an account with exactly one active user. With several users a human releases it in the dashboard (four-eyes principle), and the response contains the link. After that, template_apply_with_merge_fields fills the template with values, and letter_create_draft or order_send sends the result.
Field Type templateId string (uuid) Required versionId string (uuid) Required The draft version to release. Error codes: NOT_FOUND, TEMPLATE_VERSION_NOT_DRAFT, TEMPLATE_FOUR_EYES_REQUIRED
template_archiveScope: template:writeno dryRunArchives a template. It disappears from the lists and from sending but is kept. The content stays fully preserved and calling it again is harmless.
Field Type templateId string (uuid) Required Error codes: NOT_FOUND
template_draft_discardScope: template:writeno dryRunDiscards a draft version while it is still waiting for its release. Released and superseded versions stay untouchable and fully preserved. Calling it again is harmless.
Field Type templateId string (uuid) Optional Optional. Additionally pins the version to this template. versionId string (uuid) Required The draft version to discard. Error codes: NOT_FOUND, TEMPLATE_VERSION_IMMUTABLE
template_clone_from_libraryScope: template:writeno dryRuntemplate_clone_from_library copies one to five FrankKi standard templates into the account's own templates in one call, such as invoice, dunning letter, quote, cancellation or letters to authorities, and shows the first as an image. With release true it releases them on a single-user account. Then order_send sends with templateId and templateVersionId.
Field Type items Array<object> (min 1, max 5) Required Ids from mcp_health or template_list (curated). release boolean Optional Releases on a single-user account. previewFirst boolean Optional preset_saveScope: preset:writeno dryRunSaves a named preset (configuration bundle) in the partner profile. The name is unique per partner. Limits inside the preset are stored as-is and serve as a note. Enforcement runs exclusively on the account and sub-wallet limits set in the web app.
Field Type name string Required Unique name of the preset (per partner). preset object Required The configuration bundle (sender/signature/letterhead, shipping, labelling, approval, scheduling, limits, auditTagPrefix). signature_uploadScope: signature:writeno dryRunUploads a signature as PNG and stores it in the partner profile. On sending, the signature is inserted below the letter body. Only PNG is supported.
Field Type pngBase64 string Required The signature as PNG (Base64). widthMm number Optional Desired width in mm (optional). displayName string Optional Display name of the signature (optional). letterhead_uploadScope: letterhead:writeno dryRunUploads a letterhead as PNG or PDF and stores it in the partner profile. The source is either fileUrl or fileBase64, exactly one of the two; fileUrl keeps the file out of the call payload. PNG is printed on the page; a PDF letterhead is only filed for now, printing stays PNG-only (rendered=false). When rebuilding an existing letter: the logo and title block at the top of the page belong here (then letter_design_save); the letter body stays reserved for blocks.
Field Type fileBase64 string Optional The letterhead as PNG or PDF (Base64), alternative to fileUrl. fileUrl string Optional Public http(s) URL of the letterhead (PNG or PDF), alternative to fileBase64. fileUrl transfers the file at full colour depth and keeps it out of the call payload; a colour-reduced base64 image prints visibly worse. Maximum 20 MB. widthMm number Optional Width in mm (optional). heightMm number Optional Height in mm (optional). placement header | footer | full Optional Placement on the page. displayName string Optional Display name of the letterhead (optional). letter_design_saveScope: letter_design:writeno dryRunSaves a reusable schemaVersion 1 or 2 letterhead (letter design) in the partner profile and returns its designId and stored-source hash. The same stationery then carries every kind of mail: cancellation, invoice, payment reminder, quote, contract and letters to public authorities. The technical tool name is letter_design_save. The design is fully validated and checked against postal clear zones before it is stored.
Field Type name string, max 120 chars Required Unique name of the letter design. design unknown Required designId string (uuid) Optional brandingOwnershipConfirmed boolean Optional Required as true when creating or changing a branding asset reference. Unchanged iterative saves need no renewed confirmation. Error codes: DESIGN_ZONE_VIOLATION
letter_design_deleteScope: letter_design:writeno dryRunArchives (deletes) a saved letterhead (letter design). New sends then run on the remaining letterheads, whether cancellation, invoice, payment reminder, quote, contract or letter to a public authority; already-sent letters keep their original for auditability.
Field Type designId string (uuid) Required The letter design to delete. Error codes: NOT_FOUND
brand_kit_saveScope: letter_design:writeno dryRunSaves logo references, colours and font for the user-facing result letterhead and brand. brandingOwnershipConfirmed must be true and confirms the usage rights for the supplied brand assets. The response includes the saved state and review link. Technical tool name: brand_kit_save.
Field Type brandKit object Required brandingOwnershipConfirmed boolean Required Confirms usage rights for the logo and custom font. Must be true. brand_import_from_websiteScope: letter_design:writeno dryRunReads a public company website and proposes a letterhead design from it: brand colours, a mapped house typeface, logo candidates and company details from the imprint. Found logos are stored as design assets in the account and are usable right away. The result is a proposal to review with the customer; the brand is adopted by a following brand_kit_save call carrying brandingOwnershipConfirmed. Technical tool name: brand_import_from_website.
Field Type websiteUrl string, max 2048 chars Required Public company website address. maxLogoCandidates integer Optional How many logo candidates get downloaded and stored. Default 3. brand_setup_from_websiteScope: letter_design:writeno dryRunCompany website to sender, brand and letterhead in two calls. apply false reads the website and returns a proposal: logo, colours, typeface, sender profile with mandatory details from the imprint, sender address and a matching letterhead, plus the missing details, the one question for the person and page 1 of that letterhead as an image (letterheadPreview). apply true saves everything at once with its proposalId and brandingOwnershipConfirmed true: brand, sender profile, sender address, letterhead with logo as default, and shows a preview image. Details the person already has on file stay, senderOverrides take precedence. Next step: template_clone_from_library. Technical tool name: brand_setup_from_website.
Field Type websiteUrl string, max 2048 chars Required Public company website. apply boolean Optional false returns the proposal, true saves it. proposal object Optional The proposal from the apply false answer, optionally corrected by the person. Saves a second website read. proposalId string Optional Required with apply true: the proposalId from the apply false answer, valid for 30 minutes. brandingOwnershipConfirmed boolean Optional Required with apply true: the person confirms they may use the logo and brand. designPresetId string Optional Letterhead preset from letter_design_list_presets. Defaults to the recommendation. senderOverrides object Optional Corrections and missing details from the person; they take precedence. letter_scheduleScope: letter:scheduledryRun availableSchedules an existing draft for a later time (fixed date, relative delay or recurring via cron). All checks and the price are determined immediately and the cost is reserved. A real OAuth connection creates an approval first. The embedded card is the preview and approval. The PDF link and letter text are also in the result, for text-only views. An OAuth connection with approval:self_approve may decide through the card. Approval creates the schedule, and the actual send runs at the planned time through the same send pipeline and approval path as order_send.
Field Type letterId string (uuid) Required Existing draft to be sent on schedule. mode at | in | cron Required at = fixed time, in = relative delay, cron = recurring. sendAt string Optional Time for mode='at' (ISO 8601, Berlin time if no offset). delay string Optional Delay for mode='in': '2d', '1w', '3h', 'next-business-day', 'next-monday', 'end-of-month'. cronExpression string Optional 5-field cron for mode='cron': 'min hour day month weekday'. endDate string Optional End date for a cron series (ISO 8601, Berlin time if no offset). businessDaysOnly boolean Optional true sends on business days only and moves a weekend or holiday time to the next business day at the same time of day. Default true. sendBeforeHour number Optional Cutoff hour for sending, in Berlin local time, default 16. A time at or after this hour moves to the next business day (with businessDaysOnly false: the next day), at 9:00. timing in the result names the requested time, the effective time and the reason. deliveryType standard | einschreiben_einwurf | einschreiben_uebergabe | ch_b_post | ch_a_post | ch_einschreiben | at_eco | at_prio | intl_standard | intl_priority | intl_express | intl_tracked | intl_registered Optional express boolean Optional color boolean Optional includeSignature boolean Optional signatureId string (uuid) Optional senderAddressId string (uuid) Optional senderProfileId string (uuid) Optional mandantennummer string Optional presetName string Optional auditTag string Optional templateId string (uuid) Optional templateVersionId string (uuid) Optional Exact released template version, together with templateId. The draft supplies recipient and attachments. The server renders subject and text from the template and templateMergeValues at every send. Autopilot considers only schedules of this kind. templateMergeValues object Optional Merge values for the exact template version. coverTemplateId string (uuid) Optional Cover letter for a standalone form template. coverTemplateVersionId string (uuid) Optional Exact released version of the cover letter. maxCostEuros number Optional Maximum amount in euros. If the price is above it, the call is aborted. dryRun boolean Optional Validates and prices the schedule but creates nothing and reserves nothing. Returns dryRunWouldHaveCost. Error codes: SENDER_PFLICHTANGABEN_INCOMPLETE, ADDRESS_INVALID, AVV_REQUIRED, COST_OVER_LIMIT
schedule_cancelScope: letter:scheduledryRun availableCancels a scheduled send and releases the amount reserved for it in the wallet. letter_schedule and schedule_list return the scheduleId.
Field Type scheduleId string (uuid) Required The schedule to cancel. dryRun boolean Optional true returns the amount that would be released, without cancelling the schedule. Error codes: NOT_FOUND
order_send_batchScope: order:senddryRun availableSubmits several letters as one batch. Each item is checked and priced separately. The batch enters the approval queue as one approval covering every recipient. With autopilot, a batch whose letters all meet the autopilot rules goes out after 10 minutes; order_cancel stops it until then. At the returned approvalUrl the human reviews the recipient list, count and total cost in the signed-in portal and decides there. An OAuth connection with the separately granted approval:self_approve scope can approve on its own. Rejection refunds the entire reservation. With dryRun, it remains a free rehearsal.
Field Type items Array<object> (min 1, max 100) Required The letters of the batch. Each entry carries its own clientOrderId and exactly one source: a letterId OR an inline letter. presetName string Optional Optional preset for the whole batch; per-entry override is not supported. stopOnError boolean Optional Aborts the batch on the first error. Default false. dryRun boolean Optional Simulates the whole batch: validates each entry but charges nothing and sends nothing. Error codes: SENDER_PFLICHTANGABEN_INCOMPLETE, ADDRESS_INVALID, AVV_REQUIRED, DAILY_CAP_EXCEEDED, MANDANT_CAP_EXCEEDED, COST_OVER_LIMIT, CONTENT_REJECTED, COUNTRY_NOT_SUPPORTED, LEGAL_PROOF_UNAVAILABLE_FOR_COUNTRY, PRICE_UNAVAILABLE, SANDBOX_DISABLED, IDEMPOTENCY_CONFLICT, DESIGN_NOT_FOUND, DESIGN_RENDER_FAILED, DESIGN_ZONE_VIOLATION
Corrects the recipient address of a letter in awaiting_partner_fix and resubmits it. This requires that the OAuth connection carries approval:self_approve. Otherwise the call returns a link where the human decides in the signed-in portal. The price stays unchanged.
Field Type orderId string (uuid) Required recipient unknown Required The corrected recipient address as inline fields or as { addressId } from the partner address book. clientOrderId string Optional Idempotency key: clientOrderId (see Conventions).
document_createScope: order:sendno dryRunTurns a structured billing payload into a finished document and stores it as a letter draft: FrankKi re-computes line items, net, VAT rates and gross, checks the mandatory details under § 14 UStG, optionally draws the document number from the account's sequence, and typesets everything in the DIN 5008 layout with the sender's letter design. The draft stays free of charge until it is sent. All amounts in integer cents. Compact example: {"document":{"documentType":"rechnung","documentNumber":"RE-2026-014","documentDate":"2026-07-30","leistungszeitraum":{"von":"2026-06-01","bis":"2026-06-30"},"zahlungszielTage":14,"lineItems":[{"description":"Beratung Juni","quantity":4,"unit":"Std","unitPriceCents":12000,"ustRate":19,"lineNetCents":48000}],"totals":{"nettoCents":48000,"ustLines":[{"rate":19,"netCents":48000,"ustCents":9120}],"bruttoCents":57120}},"recipientAddressId":"…"} Next step with the returned letterId: order_send sends the letter, approval_submit puts it in front of a human for approval instead, letter_schedule sends it later.
Field Type document object Required The document payload. All amounts in integer cents. The call supplies the sums, FrankKi re-computes them and rejects mismatches. sequenceScope object Optional subject string, max 200 chars Optional letter subject. If omitted FrankKi builds it from the document type and number. language de | en Optional Defaults to de. recipientAddressId string (uuid) Optional Recipient from the address book (address_list / mandant_search return the id). Either this or recipientAddressInline. recipientAddressInline object Optional mandantennummer string Optional client this document is filed under. Filing only. senderAddressId string (uuid) Optional senderProfileId string (uuid) Optional Sender profile the mandatory tax details are read from. Defaults to the default profile. designId string (uuid) Optional reference object Optional includeSignature boolean Optional signatureId string (uuid) Optional clientLetterId string Optional idempotency key for the letter draft.
Trust and live status
Machine-readable service facts and the current operational status of the partner interface are publicly available at all times, no login needed.