API Changelog
This page tracks additions and changes to the faktoora public API and its documentation. All changes are backwards-compatible unless noted otherwise.
March 2026
Invoice Validation
Outgoing invoices can now be validated against XRechnung/ZUGFeRD standards via the API. Validation runs asynchronously after invoice file generation. Requires the invoiceValidation feature.
New/updated endpoints:
| Endpoint | Description |
|---|---|
POST /invoices | New optional validate: true parameter triggers validation after file generation |
GET /invoices/{faktooraId}/status | Response now includes a validation object with status, validity, and createdAt |
GET /invoices/{faktooraId}/validation-report | Download the PDF validation report for the most recent validation |
See Outgoing Invoices — Invoice Validation for details.
Invoice Number API
New endpoints for generating, verifying, and configuring invoice numbers programmatically. Previously invoice number management was only available through the UI.
New endpoints:
| Endpoint | Description |
|---|---|
GET /invoices/next-number | Generate the next available invoice number using a configurable template |
GET /invoices/verify-number | Check whether a specific invoice number is already in use |
GET /settings/invoice-number-template | Get the current template, pad length, and counter |
PUT /settings/invoice-number-template | Update the template pattern and/or pad length |
Templates support date tokens (YYYY, MM, DD) with a separator and auto-incrementing counter — e.g., YYYY/MM/id produces 2026/03/0042. The number is verified for uniqueness on generation.
MCP tools: get_next_invoice_number, verify_invoice_number, get_invoice_number_template, update_invoice_number_template — same functionality available to MCP clients.
See Invoice Numbers for the full guide.
API Key Lifecycle Management
API keys now support expiry dates, rotation, and revocation. Keys expose a computed status field (active, expiring_soon, expired, revoked) and automatic email warnings are sent at 7, 3, and 1 day before expiry.
New endpoints:
| Endpoint | Description |
|---|---|
GET /apikeys | List all API keys with new lifecycle fields |
PATCH /apikeys/{apiKeyId} | Update a key's label or expiry date |
POST /apikeys/{apiKeyId}/rotate | Rotate a key; creates a replacement and optionally keeps the old key alive during a grace period |
POST /apikeys/{apiKeyId}/revoke | Immediately revoke a key (soft-delete; key stays visible for audit) |
Updated GET /apikeys response fields:
| Field | Type | Description |
|---|---|---|
expiresAt | string | null | ISO 8601 expiry timestamp, or null for non-expiring keys |
lastUsedAt | string | null | Timestamp of the last authenticated request using this key |
lastUsedIp | string | null | IP address of the last authenticated request |
isRevoked | boolean | Whether the key has been revoked |
revokedAt | string | null | Timestamp when the key was revoked |
rotatedFromId | string | null | apiKeyId of the predecessor key, if created via rotation |
status | string | Computed: active, expiring_soon, expired, or revoked |
See API Key Management for the full guide.
MCP Server
The faktoora API now exposes an MCP (Model Context Protocol) server, allowing AI agents and MCP-compatible clients to interact with the API using natural language tooling.
The MCP server is available at POST /api/v1/mcp and authenticates via your existing API key. It supports the full Streamable HTTP transport defined in the MCP specification.
Supported tools (60 total across six domains):
| Domain | Example tools |
|---|---|
| Invoices | create_invoice_xrechnung, create_invoice_zugferd2, get_invoice_status, delete_invoice, list_invoices |
| Incoming invoices | import_incoming_invoice, list_incoming_invoices, get_incoming_invoice_summary |
| Outgoing import | import_outgoing_invoice, list_outgoing_invoices, get_outgoing_invoice_content |
| Customers | create_customer, list_customers, get_customer, update_customer, delete_customer |
| Products | create_product, list_products, create_product_bundle |
| Webhooks | create_webhook, list_webhooks, delete_webhook |
See MCP Server for setup instructions and the full tool reference.
Products & Product Bundles API
The full Products API is now documented and available. You can manage your product and service catalog programmatically without going through the UI.
New endpoints:
| Endpoint | Description |
|---|---|
GET /products | List products with pagination, keyword search, and sort |
GET /product/:id | Get a product by ID |
POST /product | Create a product |
PATCH /product/:id | Update a product |
DELETE /product/:id | Delete a product |
GET /product/valid-code | Check whether a product code is already in use |
Product Bundles — groups of products that can be added to an invoice as a single unit — are also documented. This feature requires the PRODUCT_BUNDLE subscription add-on. See Products & Product Bundles for full details.
Customers API
The full Customers API is now documented, covering the complete lifecycle of buyer records.
New endpoints:
| Endpoint | Description |
|---|---|
GET /customers | List customers with filtering and sort |
GET /customer/:id | Get a customer by ID |
POST /customer | Create a customer |
PATCH /customer/:id | Update a customer |
DELETE /customer/:id | Delete a customer |
GET /customers/generate-number | Auto-generate the next customer number in sequence |
GET /customer/verify-customer-number | Check whether a customer number is unique |
POST /customers/import | Bulk-import customers from a previously uploaded CSV file |
See Customers for full details.
Webhook Subscription Management
Webhooks can now be registered, updated, and deleted via the API. Previously this required using the faktoora UI.
| Endpoint | Description |
|---|---|
GET /webhooks | List your registered webhook subscriptions |
POST /webhooks | Register a new webhook |
PATCH /webhooks/{id} | Update a webhook |
DELETE /webhooks/{id} | Remove a webhook |
Note: When registering a subscription, use
"action": "invoiceCreated"(past tense). The event name delivered to your endpoint isinvoiceCreate(present tense). See Webhooks for the full event reference.
Invoice API Additions
List endpoint: GET /invoices now supports paginated listing with filtering and sorting. Pass an Accept: application/pdf or Accept: application/xml header to continue using it as a single-invoice download by invoice number — both modes are supported on the same endpoint.
Delete endpoint: DELETE /invoices/{faktooraId} is now documented. Deletion requires the invoiceDeleteMode feature to be enabled on your account.
Status polling: GET /invoices/{faktooraId}/status is now documented. Poll this after POST /invoices to track authority registration and delivery state without relying solely on webhooks.
POST response: The POST /invoices response now includes a detailsPage URL alongside the faktooraId, linking directly to the invoice in the faktoora UI.
Outgoing Invoice Content Access
A full set of content-retrieval endpoints is now documented under /import/outgoing/{faktooraId}. These give structured, machine-readable access to invoices created via POST /invoices — useful for verification, reconciliation, and downstream processing.
New endpoints include:
- Structured content by section:
seller,buyer,lineitems,taxes,paymentterms,paymentmeans,delivery - Merged content in one call:
GET /import/outgoing/{faktooraId}/content - Original source file download:
GET /import/outgoing/{faktooraId}/source - Validation reports: JSON summary and PDF
- Import processing status with three phases:
validationStatus,visualizationStatus,overallStatus - Embedded attachment listing and download
See Outgoing Invoices for the full 18-endpoint table.
Incoming Invoice Content Access
The incoming invoice API reference has been significantly expanded. The canonical endpoint prefix is now /import/incoming/{importId} — the legacy /import/{importId} prefix remains fully supported.
Added 13 content-retrieval endpoints:
- Structured content by section:
seller,buyer,lineitems,taxes,paymentterms,paymentmeans,delivery - Merged content in one call:
GET /import/incoming/{importId}/content - Original source file download:
GET /import/incoming/{importId}/source - Embedded attachment listing and download
- Paginated invoice list:
GET /import/incoming
See Incoming Invoices for the full 19-endpoint table.
December 2025
Webhook Payload Schemas
Full field-level schemas are now published for all 15 webhook event types. Previously only a subset of fields were listed.
invoiceCreate payload — expanded to include 20+ fields:
amount, outstandingBalance, currency, invoiceNumber, invoiceTypeCode, status, format, issueDate, dueDate, deliveryDate, orderNumber, shippingOrderNumber, contractNumber, assignmentNumber, orderReferenceId, buyerReferenceId, mandateReference, projectName, totalCosts, createdAt
invoiceIncomingCreate payload — expanded to include:
importId, taxAmount, sellerName, type, inputType, isValid, buyerReference, invoiceCurrencyCode
detailsPage field — added to all event payloads that reference a document. This is a fully-qualified URL linking directly to the relevant entity in the faktoora UI. Useful for linking webhook notifications to specific records without constructing URLs manually.
New Webhook Events
Two additional webhook events are now active and documented:
| Event | Trigger |
|---|---|
orderConfirmationCreate | Order confirmation document created |
orderConfirmationSent | Order confirmation sent via email |
July 2025
Additional Webhook Events
The following events were added and are now documented:
| Event | Trigger |
|---|---|
invoiceSent | Outgoing invoice successfully delivered via email |
invoiceIncomingSent | Incoming invoice forwarded to a recipient via email |
June 2025 — Developer Documentation Launch
docs.faktoora.com launched as the dedicated developer portal for the faktoora API.
Initial coverage:
- Getting Started — authentication (
X-API-KEYheader), environment setup, and first-request walkthrough - Outgoing Invoices — invoice creation via
POST /invoiceswith draft, review, and direct modes; ZUGFeRD, XRechnung format selection; download byfaktooraIdor invoice number - Incoming Invoices — API upload via
POST /import, EN 16931 validation, status polling, PDF preview - Webhooks — initial event reference covering
invoiceCreate,invoiceOverdue,invoiceIncomingCreate, offers, letters, reminders,customerCreate,productCreate - Glossary — canonical definitions for
faktooraId,XRechnung,ZUGFeRD,PEPPOL,EN 16931, invoice status lifecycle - Process diagrams — sequence and flowchart diagrams for outgoing and incoming invoice flows
- Interactive API docs — full OpenAPI spec at /api-docs via the Scalar UI