External API V1 Documentation

Key capabilities#

Use these points as the practical checks for this section.

• Upload endpoints for PDF invoices and structured invoice data
• AI-powered invoice data extraction
• Automated EN 16931 and KoSIT validation
• XRechnung, ZUGFeRD, EN16931, UBL, and CII output formats
• Async processing with polling; small invoices often take around 30 seconds, larger invoices up to 1-2 minutes
• Idempotent writes for safe retries

Delivery Artifacts#

Download machine-readable integration artifacts for the Developer API.

Quickstart#

Three API calls complete a conversion. The convert endpoint is served at /api/v1 and requires authentication.

Get API access#

Use these points as the practical checks for this section.

• Create an account and request API access.
• Use prepaid API credits for approved testing or Enterprise order-form billing for production use.
• After approval, create a live API key from the API access section.
• Run the first request with server-side credentials, then monitor usage and rotate keys from your profile.

Base URL and API keys#

Use these points as the practical checks for this section.

• Production base URL: https://www.invoice-converter.com/api/v1.
• Live keys use the production host and the icp_... prefix.
• Run onboarding and validation requests with approved live keys before sending production volume.
• Treat keys as server-side secrets. Do not embed them in browser or mobile clients.

First successful request#

Use this sequence as the minimum happy path after creating an API key.

• Upload: POST /api/v1/invoices:convert with Authorization, Idempotency-Key, file=@invoice.pdf, and format=XRECHNUNG.
• Poll every 10-15 seconds: GET /api/v1/tasks/{task_id} until status is completed or failed.
• Download: GET /api/v1/tasks/{task_id}/result?download=xml and store X-Correlation-ID for support tracing.
• For ZUGFeRD PDF output, request format=ZUGFERD on convert and download=pdf on result.
• For structured input, call POST /api/v1/invoices:convert-structured with pdf_file=@invoice.pdf, data_file=@invoice-data.json, and the target format.
• Optionally send client_reference or external_invoice_id and source_system for ERP reconciliation.
• For split ERP exports of one invoice, repeat data_file; for multiple invoices, start one task per invoice with its own idempotency key.
• Store result_artifacts from the status response to see whether XML/PDF artifacts are validated, cached, or still unavailable because of dependencies.

Common payload examples#

Use these points as the practical checks for this section.

• XRECHNUNG: send format=XRECHNUNG.
• ZUGFERD: send format=ZUGFERD; use download=pdf on result for the hybrid PDF/A-3 output.
• Structured input: send pdf_file plus one or more data_file parts; accepted data formats are CSV, JSON, XML, XLSX, and TXT, with any supported target format. The data_file parts must contain all mandatory data; the PDF does not fill missing fields.
• Multiple invoices: submit separate convert requests and track each returned task_id; repeated data_file parts are only for split exports of the same invoice.
• UBL: send format=UBL; for deterministic integrations, set an explicit profile such as PEPPOL, XRECHNUNG, or EN16931.
• CII: send format=CII; for deterministic integrations, set an explicit profile such as EN16931.

Required request headers#

Use these points as the practical checks for this section.

• Authorization: Bearer <api_key>

Auth rules#

API access is gated. Approved accounts can create API keys from the profile, use them as Bearer tokens, and use prepaid credits for approved testing or Enterprise order-form billing for production.

• Keys are tenant-scoped live credentials for approved accounts. The current production prefix is icp_....
• Create, rotate, and revoke API keys from your profile after API access is enabled. Copy new keys immediately because plaintext keys are shown only once.
• Missing or invalid key returns 401.
• Calls to /api/v1 receive an X-Correlation-ID automatically when omitted.
• Write calls require Idempotency-Key; keep this value stable across retries.
• Use server-to-server integration from your backend. Browser-origin access is restricted in production.

Idempotency contract#

Use these points as the practical checks for this section.

• Send an Idempotency-Key on every write call.
• Idempotency keys must match [A-Za-z0-9._:-]+ and be at most 200 chars.
• If you provide your own key, the same key + identical payload returns the cached response.
• Same key + different payload returns 409 IDEMPOTENCY_CONFLICT.
• Idempotency keys expire after 24 hours.

Endpoint Reference#

All endpoints are available under /api/v1. Timeouts surface as 504 and other temporary connectivity failures as 502; correlation IDs help support trace requests end-to-end.

Output format matrix#

Changelog#

Recent externally visible API changes.

Error Contract#

Common errors and what to do#

Use these points as the practical checks for this section.

• Retry with backoff: 429, 500, 502, 503, 504.
• Fix request or source data: 400, 409, 413, 422.
• Fix access or credentials: 401, 403.
• Confirm approval and prepaid testing credits or Enterprise order-form billing: 402 INSUFFICIENT_API_CREDITS.
• Keep polling later: 202 TASK_NOT_READY.
• For 422 VALIDATION_FAILED, show the returned field, rule ID, and remediation to a human reviewer before retrying with corrected invoice data.
• For 503 AUTHORITATIVE_VALIDATION_UNAVAILABLE, fetch the same task result later; no unverified artifact was delivered.

Rate & payload limits#

Per-key rate limits and payload size constraints are enforced for all API calls. Rejected conversions do not consume prepaid API credits; rate limits are calculated separately per endpoint.

• Endpoint-aware limits are cost-weighted. Both upload endpoints use the baseline quota (default 30/min and 500/hour); task polling is currently at least 10/min and 120/hour, and result downloads are currently at least 10/min and about 134/hour by default.
• Read effective limits from X-RateLimit-Limit-Minute and X-RateLimit-Limit-Hour on responses.
• PDF upload max size: 20 MB
• Structured data upload max size: 2 MB total across all data_file parts.
• JSON payload max size: 1 MB
• Rate-limit responses include Retry-After, X-RateLimit-Limit-Minute, and X-RateLimit-Limit-Hour.

Retry guidance#

Use these points as the practical checks for this section.

• Use exponential backoff with jitter.
• Retry only transient classes (429, 500, 502, 503, 504) using the same payload and idempotency key where possible.
• Do not blindly retry validation or contract errors (400, 401, 402, 403, 409, 413, 422).

Task lifecycle & retention#

Use these points as the practical checks for this section.

• Completed and failed tasks remain available for 10 minutes after reaching terminal state.
• Processing times out after 5 minutes — stuck tasks are automatically marked failed.
• Idempotency keys expire after 24 hours.
• Rate-limit counters reset on a rolling window.

Support model#

Use these points as the practical checks for this section.

• Business-hours support on commercially reasonable efforts.
• No formal SLA, service credit, or response-time commitment unless agreed in an order form.

Send Technical Feedback#

Share implementation questions, risks, and required contract changes with our team.

Use Postman and OpenAPI#

Use these points as the practical checks for this section.

• Import the Postman collection and set baseUrl, apiKey, and a new idempotencyKey variable.
• Run the collection in order: convert, poll status, then fetch result.
• Use the OpenAPI JSON to generate typed clients, but keep file upload, polling, and binary result handling covered by integration tests.
• Record X-Correlation-ID in logs so support can trace requests end-to-end.