External API V1 Documentation

Convert invoice document to structured e-invoice

Convert structured data

Poll task status

Upload a PDF, DOCX, or TXT invoice document and start asynchronous conversion. Returns a task_id for polling. ZUGFeRD/Factur-X hybrid PDF downloads require a PDF source upload; DOCX/TXT sources should request XML results. Request: multipart/form-data; file (binary, required) — PDF, DOCX, or TXT invoice source document; legacy DOC/RTF, images, and other files are rejected; format (string, required) — target output format; see format matrix below; profile (string, optional, recommended for deterministic integrations) — explicit compliance profile, matched case-insensitively. Each format has a closed accepted set and one default: XRECHNUNG → [XRECHNUNG] (default XRECHNUNG); EN16931 → [EN16931] (default EN16931); UBL → [XRECHNUNG, PEPPOL, EN16931] (default EN16931); CII → [XRECHNUNG, EN16931, ZUGFERD_EN16931, ZUGFERD_XRECHNUNG] (default EN16931); ZUGFERD → [ZUGFERD_EN16931, ZUGFERD_XRECHNUNG] (default ZUGFERD_EN16931). ZUGFERD, FACTURX, FACTUR-X, and FACTUR_X alias ZUGFERD_EN16931; ZUGFERD-XRECHNUNG aliases ZUGFERD_XRECHNUNG. A value outside the accepted set returns 422 OUTPUT_PROFILE_CONFLICT; an unrecognized profile name returns 422 INVALID_PROFILE with details.allowed_profiles; jurisdiction (string, optional) — explicit ISO 3166-1 alpha-2 jurisdiction context used for validation/advisory checks; does not override profile; transaction_scope (string, optional) — explicit transaction scope context, such as B2G; applied to the queued task; delivery_channel (string, optional) — one of PEPPOL, DIRECT_XML, PORTAL, EMAIL_PDF, UNKNOWN; applied to the queued task; client_reference or external_invoice_id (string, optional) — tenant-side invoice/job reference returned on accepted uploads and task status responses; source_system (string, optional) — upstream ERP or billing system label returned on accepted uploads and task status responses; use_seller_master_data (boolean, optional) — when omitted, the tenant profile default applies; false ignores saved seller defaults for this request, true provides/uses seller defaults; seller_master_data (JSON object string, optional) — request-scoped seller defaults used only when use_seller_master_data=true; supported keys include business_name, address, tax, electronic address, contact, and payment fields (payment_means_code 30/42/58, payment_iban, payment_bic, payment_account_name, payment_terms_note); every supplied profile value replaces the corresponding extracted value, absent profile fields remain unchanged, and differences create non-blocking review warnings. Response: 202 Accepted.

Upload a carrier PDF plus CSV, JSON, XML, XLSX, or TXT invoice data and start asynchronous structured-data conversion. The data_file parts are the only semantic source; the PDF does not fill missing invoice fields. For ZUGFeRD/Factur-X it is used as the carrier PDF, and for XML-oriented outputs it is retained as the submitted PDF artifact. Use one conversion request per invoice; repeat data_file only for split ERP exports that describe the same invoice. Request: multipart/form-data; pdf_file (binary, required) — carrier PDF used for ZUGFeRD/Factur-X embedding and retained for XML-oriented outputs; data_file (binary, required, repeatable) — CSV, JSON, XML, XLSX, or TXT invoice data used as the only semantic source; .xls, PDFs, and image files are rejected as data_file; repeat for split header/line exports of the same invoice; aliases data_files and data_files[] are accepted; structured data total size — max 2 MB across all data_file parts; format (string, required) — target output format; supports XRECHNUNG, ZUGFERD, EN16931, UBL, and CII; profile (string, optional, recommended for deterministic integrations) — explicit compliance profile, matched case-insensitively. Each format has a closed accepted set and one default: XRECHNUNG → [XRECHNUNG] (default XRECHNUNG); EN16931 → [EN16931] (default EN16931); UBL → [XRECHNUNG, PEPPOL, EN16931] (default EN16931); CII → [XRECHNUNG, EN16931, ZUGFERD_EN16931, ZUGFERD_XRECHNUNG] (default EN16931); ZUGFERD → [ZUGFERD_EN16931, ZUGFERD_XRECHNUNG] (default ZUGFERD_EN16931). A value outside the accepted set returns 422 OUTPUT_PROFILE_CONFLICT; an unrecognized profile name returns 422 INVALID_PROFILE with details.allowed_profiles; jurisdiction (string, optional) — explicit ISO 3166-1 alpha-2 jurisdiction context used for validation/advisory checks; does not override profile; transaction_scope (string, optional) — explicit transaction scope context, such as B2G; applied to the queued task; delivery_channel (string, optional) — one of PEPPOL, DIRECT_XML, PORTAL, EMAIL_PDF, UNKNOWN; applied to the queued task; client_reference or external_invoice_id (string, optional) — tenant-side invoice/job reference returned on accepted uploads and task status responses; source_system (string, optional) — upstream ERP or billing system label returned on accepted uploads and task status responses; use_seller_master_data (boolean, optional) — when omitted, the tenant profile default applies; false ignores saved seller defaults for this request, true provides/uses seller defaults; seller_master_data (JSON object string, optional) — request-scoped seller defaults used only when use_seller_master_data=true; supported keys include business_name, address, tax, electronic address, contact, and payment fields (payment_means_code 30/42/58, payment_iban, payment_bic, payment_account_name, payment_terms_note); every supplied profile value replaces the corresponding extracted value, absent profile fields remain unchanged, and differences create non-blocking review warnings. Response: 202 Accepted.

Poll the current status of a conversion task. Returns pending (accepted and queued, not started yet), processing, completed, or failed. Rate limit 10/min and 120/hour, which is the binding constraint for polling: wait about 20 seconds after the accepted 202 before the first call, then back off (20s, 30s, 45s, 60s, and 60s from there on) and stop on completed or failed. Completed tasks include result_artifacts diagnostics so clients can see which XML/PDF artifacts are available, cached, and validation-proven. Completed task payloads may include additive _processing_warnings and _validation_warnings entries with SOURCE_CONTEXT_* rule IDs when source evidence was unavailable, suspect, or truncated; treat them as review signals, not failures. When failed, the response includes an error field with the failure reason. Request: none (GET); task_id (path, required) — UUID returned by the convert endpoint; include_validation_report_html (query, optional) — true or false (default false); when true, the status response inlines the sanitized validation report HTML for the current strict artifact when available. Response: 200 OK.

Download the generated file (XML or PDF). Result syntax matches the original task format: XRECHNUNG/EN16931/UBL return UBL XML, CII/ZUGFERD return CII XML, and ZUGFERD + download=pdf returns a hybrid PDF/A-3. For other formats, download=pdf can return a rendered PDF; on a completed task download=xml is the expected-available artifact, not a guaranteed one. Repeated downloads may be served from cached generated artifacts when validation proof is still current. While processing, this endpoint returns a 202 carrying the standard error envelope ({"code":"TASK_NOT_READY","message":"Strict conversion is still processing. No validated artifact is available yet.","correlation_id":"<uuid>"}); blocking validation issues return 422 VALIDATION_FAILED, retryable dependency gaps return 503, terminal conversion failures return 500 TASK_FAILED with the reason in details.code, and artifact invariant failures return 500 INTERNAL_ARTIFACT_INVARIANT_FAILED, all with no file body. Successful downloads carry X-Correlation-ID, Content-Disposition, Cache-Control: no-store, X-Artifact-Sha256, X-Validation-Proof-Id, X-Artifact-Proof-Id, X-Artifact-State, X-Validation-State, X-Proof-Status, and X-Validator-Bundle-Id; X-Task-Id is not set on this endpoint. Rate limit 10/min and about 134/hour. Request: none (GET); task_id (path, required) — UUID returned by the convert endpoint; download (query, required) — xml or pdf. Response: 200 OK.

Download the validation report tied to the current validated result artifact. The report is available only after strict conversion has produced a cached artifact with current validation proof, and returns 404 when no report is bound to the delivered artifact. A 202 carries the standard TASK_NOT_READY error envelope, not a file body. Successful responses carry X-Correlation-ID, Content-Disposition, Cache-Control: no-store, X-Artifact-Sha256, X-Validation-Proof-Id, X-Artifact-Proof-Id, X-Artifact-State, X-Validation-State, X-Proof-Status, X-Validator-Bundle-Id, plus X-Task-Id, X-Validation-Report-Proof-Id, X-Validation-Report-Content-Type, X-Validation-Report-Format, X-Validation-Report-Source, and X-Report-Source-Artifact-Format. Those artifact-level diagnostics describe the validated result artifact the report covers, not the returned report bytes: X-Artifact-Sha256 is the SHA-256 of that source artifact and must not be used to checksum the downloaded report, while X-Validation-Report-Proof-Id identifies the proof that supplied the report payload. Rate limit 10/min and 120/hour. Request: none (GET); task_id (path, required) — UUID returned by the convert endpoint; download (query, optional) — html or xml. Response: 200 OK.

Documentation release 1.13.0: Enterprise is available through direct checkout for EUR 50 per month or EUR 420 per year. Every active Enterprise subscription includes 100 conversion units per month shared by Email Import and External API V1; additional units use prepaid credits at EUR 0.50 each. Email Import and External API V1 no longer require manual account approval. Email Import still requires profile enablement and a verified sender.

Documentation release 1.12.0. No runtime behavior changed on this date; these entries document behavior that was already live. MULTIPLE_INVOICES_IN_DOCUMENT is now published in the error catalog. It is returned as 500 TASK_FAILED with details.code=MULTIPLE_INVOICES_IN_DOCUMENT, details.retryable=false, and details.can_review=false. It is terminal: split the source into one document per invoice. The failed attempt does not consume a billing unit. Retry guidance corrected: a 500 is not automatically retryable. Branch on code, and on details.code plus details.retryable for 500 TASK_FAILED, instead of on the HTTP status alone. Treat 500 TASK_FAILED as terminal unless details.retryable is true (transient provider failures such as rate limiting, timeouts, and transport errors), in which case start a new conversion with a new Idempotency-Key rather than re-polling the same task. Never retry 500 INTERNAL_ARTIFACT_INVARIANT_FAILED. Billing is documented as included-allowance-then-credits, so 402 INSUFFICIENT_API_CREDITS has two details shapes: prepaid (remaining, minimum_purchase) and included allowance (included_remaining, credit_remaining, shortfall, minimum_purchase). Newly documented runtime error codes that were already being returned: 403 API_NOT_ENABLED_FOR_TENANT, 409 IDEMPOTENCY_IN_PROGRESS, 409 IDEMPOTENCY_REPLAY_EXPIRED, 422 INVALID_PROFILE, 422 UPLOAD_FAILED, 400 INVALID_IDEMPOTENCY_KEY, 503 PLAN_TIER_CHECK_FAILED, 503 RATE_LIMIT_SERVICE_UNAVAILABLE, and 503 EXTRACTION_INCOMPLETE_GROUP_FAILURE. The 409 class is split by retry semantics: IDEMPOTENCY_IN_PROGRESS is retryable with the same key after a short delay, while IDEMPOTENCY_CONFLICT and IDEMPOTENCY_REPLAY_EXPIRED require a new key. Validation-report header passthrough fixed, and X-Validation-Report-Format, X-Validation-Report-Source, and X-Report-Source-Artifact-Format are now published. On the validation-report endpoint, X-Artifact-Sha256 is the SHA-256 of the result artifact the report validates, not of the returned report bytes; X-Validation-Report-Proof-Id identifies the proof that supplied the report payload. Added retention and lifecycle statements: 24-hour task/artifact retention after a terminal state, 24-hour idempotency records, a 15-minute in-progress reclaim, a 5-minute stall window, a 15-minute hard cap, and a recommended ~16-minute client timeout. Rate limits and polling guidance replaced with per-endpoint numbers, including the previously missing validation-report bucket. Quota headers are returned on 429 responses only, and the former "poll every 10-15 seconds" advice is replaced with a first-poll delay plus backoff. Published a closed format x profile compatibility table with the default profile for each format, and corrected download=xml on a completed task from "always available" to expected-available. Corrected 405 METHOD_NOT_ALLOWED to return Allow: POST, OPTIONS on conversion paths and Allow: GET, OPTIONS on task paths, and corrected 422 PROFILE_MISMATCH: there is no profile query parameter, and the fix is to start a new conversion with an aligned profile.

External API conversions now run the same document-scope gate as the interactive product, including on forced extraction modes that previously skipped it. A source document whose extraction reports multiple invoices, corroborated by two or more distinct invoice identifiers or by an invoice count with no identifiers, now fails terminally with MULTIPLE_INVOICES_IN_DOCUMENT. The failure is not retryable: split the source into one document per invoice and submit each separately. An uncorroborated multiple_invoices verdict no longer fails the conversion. On strict API issuance it returns 422 VALIDATION_FAILED with a blocking_source_conflict issue entry, which covers duplicate renditions such as an original plus its copy, a reprint, or a second-language rendition.

When seller master data is enabled, every supplied profile value replaces the corresponding extracted seller or payment value. Fields absent from the profile remain unchanged. Source differences are non-blocking review warnings.

Superseded by the 2026-07-26 entry above. Seller master data filled missing seller and payment fields only; explicit invoice values remained unchanged, and material profile/source conflicts blocked strict issuance until review. Since 2026-07-26 every supplied profile value replaces the corresponding extracted value instead.

Documentation backfill; no runtime behavior change. The error catalog now documents the previously undocumented runtime error codes, including API_CREDIT_SERVICE_UNAVAILABLE, TASK_NOT_FOUND, INVALID_CLIENT_METADATA, INVALID_SELLER_MASTER_DATA, PROFILE_MISMATCH, ZUGFERD_SOURCE_PDF_REQUIRED, VALIDATION_REPORT_NOT_FOUND, VALIDATION_REPORT_FAILED, INVALID_QUERY_PARAMETER, and METHOD_NOT_ALLOWED. Clients that parse error responses by the machine-readable code field need no changes; clients that switch on a fixed list of codes should add the newly documented values. Corrected changelog dates: DOCX/TXT source support shipped on 2026-06-30, not 2026-07-06.

Completed task payloads may include additive _processing_warnings and _validation_warnings entries with SOURCE_CONTEXT_* rule IDs when source evidence was unavailable, suspect, or truncated before extraction. Treat SOURCE_CONTEXT_* entries as review signals for customer-side exception handling; strict artifact downloads remain governed by validation proof and artifact checks.

Strict ZUGFeRD prerequisite failures (missing mandatory fields for hybrid generation) now fail as 422 VALIDATION_FAILED with the blocking rule IDs instead of a retryable 503; route these to a data-correction flow, not a retry loop. For XML-only formats (XRECHNUNG, EN16931, UBL, CII), the PDF rendering is now a best-effort convenience artifact: download=xml stays authoritative on completed tasks while download=pdf can be unavailable if the rendering failed after XML issuance. Conversions with unresolved blocking source conflicts now fail as 422 VALIDATION_FAILED with blocking_source_conflict issue entries instead of issuing an artifact.

POST /api/v1/invoices:convert now accepts PDF, DOCX, and TXT invoice source documents in the file field. Legacy DOC, RTF, image, and other unsupported source files are rejected before conversion starts. ZUGFeRD/Factur-X hybrid PDF downloads still require a PDF source upload; use XML downloads for DOCX/TXT source conversions. Added optional include_validation_report_html=true on GET /api/v1/tasks/{task_id} to inline the sanitized validation report HTML when available. Conversion uploads now accept optional use_seller_master_data and seller_master_data fields on both endpoints so approved tenants can opt into stored or request-scoped seller defaults.

Added GET /api/v1/tasks/{task_id}/validation-report?download=html|xml to retrieve the validation report tied to the current strict result artifact proof. Validation report responses expose task ID, artifact SHA-256, validation proof ID, report proof ID, report content type, and correlation ID headers.

Invoice data you submit is now the source of truth during hybrid ZUGFeRD generation; the server no longer overrides submitted quantities or totals with values recovered from the uploaded PDF. Deterministic cleanup and tax normalization still apply. Long-running conversions are no longer failed at a fixed 5-minute processing timeout. Tasks now fail only when they stop making progress for the stall window or exceed the absolute 15-minute hard cap, and extraction retries are bounded by a total wall-clock budget.

Clarified that usage-tracking persistence failures are fail-open for response delivery: ready validated artifact responses are not denied, no extra prepaid API credit is consumed, and failed usage events are queued internally for reconciliation.

External API access is now documented as approved gated access rather than ungated key creation. Clarified that no formal SLA, service credit, or contractual penalty applies unless agreed in an order form. format is now required on both conversion endpoints; missing values return 400 FORMAT_REQUIRED and unsupported values return 422 INVALID_FORMAT. download is now required on task-result requests; missing values return 400 DOWNLOAD_FORMAT_REQUIRED and unsupported values return 400 INVALID_DOWNLOAD_FORMAT. Conversion uploads now accept client_reference/external_invoice_id and source_system for customer-side reconciliation. Accepted conversion and task-status responses now include status_url, primary_result_format, primary_result_url, and supplied reconciliation fields.

Structured conversion now accepts all public output formats: XRECHNUNG, ZUGFeRD, EN16931, UBL, and CII. Structured conversion now accepts repeatable data_file parts plus data_files and data_files[] aliases for split ERP exports. Structured multi-file bundles must describe exactly one invoice and fail fast on conflicting or missing bundle invoice IDs. Clarified that multiple invoice documents should be submitted as separate conversion tasks, each with its own idempotency key.

Added POST /api/v1/invoices:convert-structured for carrier-PDF plus CSV/JSON/XML/XLSX/TXT structured-data conversion across supported output formats. Documented that structured data is the only semantic source on this endpoint; the PDF is used for hybrid embedding. Updated OpenAPI and Postman artifacts for structured conversion.

Strict XML and hybrid ZUGFeRD PDF result artifacts now carry internal artifact parity metadata; public clients should use task-status result_artifacts for artifact readiness and validation-state diagnostics. Updated the documented production base URL to https://www.invoice-converter.com/api/v1.

Task-result downloads are now strict retrieval-only: no XML/PDF generation, AI call, repair, or validation runs on GET /api/v1/tasks/{task_id}/result. Strict tasks complete only after a validated artifact is stored; completed tasks without a current proof fail closed with 500 INTERNAL_ARTIFACT_INVARIANT_FAILED. External API conversions are permanently pinned to strict issuance: no draft output, no warning override, and artifact validation always required. Conversions run on a dedicated processing tier chosen by the service. Added additive result_artifacts diagnostics to the task status response, and documented the canonical delivery_channel values PEPPOL, DIRECT_XML, PORTAL, EMAIL_PDF, and UNKNOWN. Documented 422 ZUGFERD_SOURCE_PDF_INCOMPATIBLE, and clarified that missing XRechnung/Peppol target metadata such as BT-10, BT-49, and BG-16 is a validation correction flow rather than a transport retry.

Added prepaid External API credits for non-Enterprise tenants. Documented 402 INSUFFICIENT_API_CREDITS for approved tenants without Enterprise order-form billing or prepaid credits. Confirmed idempotent replays do not consume additional API credits. Clarified that External API V1 model routing is managed server-side while profile and delivery context stay caller-controlled.

Task status responses expose artifact readiness diagnostics for XML/PDF result availability. Documented that strict result downloads only return files after server-side artifact gates pass.

Successful task-result downloads are backed by a server-side validation proof for the returned bytes. The result endpoint returns 503 AUTHORITATIVE_VALIDATION_UNAVAILABLE when required authoritative validation, proof persistence, or hybrid-generation dependencies are unavailable. Cached task-result downloads are reused only when the cached artifact still has a persisted validation proof.

Made task-result downloads format-faithful for CII and ZUGFERD outputs. Added cached result artifact reuse for repeated XML/PDF downloads of the same task. Aligned polling quotas with endpoint-scoped weighted rate-limit buckets.

Added clearer, consistent API error responses across all endpoints. Expanded convert options and documented XML/PDF download behavior for task results. Improved retry safety with stricter idempotency requirements and validation. Updated OpenAPI/Postman artifacts to match current API behavior.