Invoice-Converter API

The Invoice-Converter API is organized around REST. It accepts multipart file uploads, returns JSON-encoded responses, and uses standard HTTP response codes and authentication.

Send a PDF invoice and the API extracts structured data using AI, validates it against EN 16931, and produces compliant XRechnung XML, ZUGFeRD/Factur-X hybrid PDF, or other European e-invoicing formats. Conversion is asynchronous — submit a job, poll for status, then fetch the result.

Just getting started? Jump to the Quickstart guide for a working example in under five minutes.

Base URL

https://invoice-converter.com/api/v1

Status: planned (beta, work in progress)

Last updated: 2026-02-20

Introduction

Send a PDF invoice to a single endpoint and Invoice-Converter handles extraction, validation, and output generation. The result endpoint returns the generated file only after validation gates pass; otherwise it returns 422 VALIDATION_FAILED.

Key capabilities

Single endpoint for PDF-to-XML conversion
AI-powered invoice data extraction
Automated EN 16931 and KoSIT validation
XRechnung, ZUGFeRD, UBL, and CII output formats
Async processing with polling — results in 5–15 seconds
Idempotent writes for safe retries

Authentication

Use your API key as a Bearer token. Keys are provisioned in your account settings under Profile → API keys.

Required request headers

Authorization: Bearer <api_key>

Auth rules

Keys are tenant-scoped and environment-scoped (live / test). Key prefix determines environment.
Provision or rotate keys under Profile → API keys in your account, or contact support.
Missing or invalid key returns 401.
Correlation and idempotency headers are generated by the proxy when omitted.

Idempotency contract

The proxy auto-generates an Idempotency-Key header when the client omits it.
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.

Quickstart

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

1POST/api/v1/invoices:convert

Start async conversion and receive a task_id for polling. Optional: set format; default is XRECHNUNG.

Request

curl -X POST 'https://invoice-converter.com/api/v1/invoices:convert' \
  -H 'Authorization: Bearer <api_key>' \
  -F 'file=@invoice.pdf' \
  -F 'format=XRECHNUNG'  # optional; allowed: XRECHNUNG|ZUGFERD|EN16931|UBL|CII

Response — 202 Accepted

{
  "task_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "pending",
  "message": "PDF accepted. Conversion started.",
  "filename": "invoice.pdf",
  "file_size": 245832,
  "correlation_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7"
}

2GET/api/v1/tasks/{task_id}

Poll every 2–5 seconds until status is completed or failed. Typical conversion time: 5–15 seconds.

Request

curl 'https://invoice-converter.com/api/v1/tasks/<task_id>' \
  -H 'Authorization: Bearer <api_key>'

Response — 200 OK

{
  "task_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "completed",
  "correlation_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7"
}

3GET/api/v1/tasks/{task_id}/result

Download the generated file. Response is XML or PDF depending on the format requested. If blocking validation issues remain, this endpoint returns 422 VALIDATION_FAILED and no file.

Request

curl -o invoice.xml 'https://invoice-converter.com/api/v1/tasks/<task_id>/result' \
  -H 'Authorization: Bearer <api_key>' -D -

Response — 200 OK

HTTP/1.1 200 OK
Content-Type: application/xml
Content-Disposition: attachment; filename="invoice.xml"
X-Correlation-ID: 7c9e6679-7425-40de-944b-e07fc1f90ae7

<?xml version="1.0" encoding="UTF-8"?>
<Invoice xmlns="urn:oasis:names:specification:ubl:schema:xsd:Invoice-2">
  <!-- XRechnung-compliant UBL 2.1 XML -->
  ...
</Invoice>

Endpoints

All endpoints are served through the website proxy at /api/v1. Upstream timeouts surface as 504; correlation IDs propagate end-to-end for traceability.

POST/api/v1/invoices:convert

Upload a PDF invoice and start asynchronous conversion. Returns a task_id for polling.

Request

Format: multipart/form-data

file (binary, required) — PDF invoice file
format (string, optional, default: XRECHNUNG) — target output format; see format matrix below

Response — 202 Accepted

json

{
  "task_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "pending",
  "message": "PDF accepted. Conversion started.",
  "filename": "invoice.pdf",
  "file_size": 245832,
  "correlation_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7"
}

GET/api/v1/tasks/{task_id}

Poll the current status of a conversion task. Returns pending, processing, completed, or failed. When failed, the response includes an error field with the failure reason.

Request

Format: none (GET)

task_id (path, required) — UUID returned by the convert endpoint

Response — 200 OK

json

{
  "task_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "completed",
  "correlation_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7"
}

GET/api/v1/tasks/{task_id}/result

Download the generated file (XML or PDF). Content type depends on the format requested. If blocking validation issues remain, this endpoint returns 422 VALIDATION_FAILED and no file body.

Request

Format: none (GET)

task_id (path, required) — UUID returned by the convert endpoint

Response — 200 OK

json

Content-Type: application/xml
Content-Disposition: attachment; filename="invoice.xml"
X-Correlation-ID: 7c9e6679-7425-40de-944b-e07fc1f90ae7

<?xml version="1.0" encoding="UTF-8"?>
<Invoice xmlns="urn:oasis:names:...:Invoice-2">...</Invoice>

Output format matrix

Format	Syntax	Version / Profile	Content-Type	Extension
`XRECHNUNG`	UBL 2.1 XML	XRechnung 3.0	`application/xml`	`.xml`
`ZUGFERD`	CII XML in PDF/A-3	ZUGFeRD 2.3 / Factur-X 1.0	`application/pdf`	`.pdf`
`EN16931`	UBL 2.1 XML	EN 16931	`application/xml`	`.xml`
`UBL`	UBL 2.1 XML	OASIS UBL 2.1	`application/xml`	`.xml`
`CII`	UN/CEFACT CII XML	D16B	`application/xml`	`.xml`

Errors

Missing mandatory fields do not fail conversion intake, but file delivery is blocked at result time. The result endpoint returns 422 VALIDATION_FAILED with structured details until requirements are satisfied. Unreadable uploads return HTTP 422

Error catalog

Code	HTTP	Retryable	Notes
AUTHENTICATION_REQUIRED	401	No	Missing/empty bearer token
INVALID_API_KEY	401	No	API key not found/revoked/expired
IDEMPOTENCY_KEY_REQUIRED	400	No	Write endpoint without Idempotency-Key (auto-generated by proxy when omitted)
IDEMPOTENCY_CONFLICT	409	No	Same key used with different request hash
IDEMPOTENCY_IN_PROGRESS	409	Yes	Safe to retry later with same key/payload
AUTH_SERVICE_UNAVAILABLE	503	Yes	Auth backend unavailable
RATE_LIMIT_SERVICE_UNAVAILABLE	503	Yes	Rate-limit backend unavailable
RATE_LIMITED	429	Yes	Respect Retry-After and quota headers
BAD_REQUEST	400	No	Invalid JSON or invalid UUID path parameter
PAYLOAD_TOO_LARGE	413	No	Over upload size limit
INVALID_UPLOAD	400	No	Upload read/parsing failure
UPLOAD_FAILED	4xx/5xx	Conditional	Retry only for transient 5xx cases
TASK_NOT_READY	202	Yes	Poll again for async completion
TASK_STATUS_FAILED	4xx/5xx	Conditional	Retry if transient upstream/backend condition
TASK_RESULT_FAILED	4xx/5xx	Conditional	Retry if transient upstream/backend condition
PROXY_ERROR	502/504	Yes	Proxy/upstream failure (504 for timeout)

Validation response

json — 422 response

{ "code": "VALIDATION_FAILED", "details": [{ "field": "BuyerReference", "rule_id": "BR-DE-15" }] }

Missing mandatory field examples

Convert returns 202 Accepted when file intake succeeds.
Mandatory-field validation happens during async processing.
The result endpoint returns a file only when validation passes.
Blocking validation issues return 422 VALIDATION_FAILED with structured details.
Unreadable/empty PDF → immediate 400 INVALID_UPLOAD.

json — async task result with missing fields

{
  "code": "VALIDATION_FAILED",
  "message": "Validation failed",
  "correlation_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "details": [
    {
      "field": "BuyerReference",
      "rule_id": "BR-DE-15",
      "severity": "error",
      "source": "task-result-download",
      "suggestion": "Provide Leitweg-ID / BuyerReference."
    }
  ]
}

Rate Limits & Reliability

Per-key rate limits and payload size constraints are enforced at the proxy layer. Denied requests do not consume quota.

Rate & payload limits

30 requests per minute per API key
500 requests per hour per API key
PDF upload max size: 20 MB

Retry guidance

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

Polling state machine

Poll GET /api/v1/tasks/{task_id} every 2–5 seconds. Stop when status reaches a terminal state.

pendingTask is queued for processing

processingAI extraction and validation are running

completedResult is ready; fetch via /result endpoint

failedConversion failed; error field in status response explains the reason; /result returns 404

Task lifecycle & retention

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

Business-hours support.
Target first response: 1 business day.

Invoice-Converter API

The Invoice-Converter API is organized around REST. It accepts multipart file uploads, returns JSON-encoded responses, and uses standard HTTP response codes and authentication.

Just getting started? Jump to the Quickstart guide for a working example in under five minutes.

Base URL

https://invoice-converter.com/api/v1

Status: planned (beta, work in progress)

Last updated: 2026-02-20

Introduction

Key capabilities

Single endpoint for PDF-to-XML conversion
AI-powered invoice data extraction
Automated EN 16931 and KoSIT validation
XRechnung, ZUGFeRD, UBL, and CII output formats
Async processing with polling — results in 5–15 seconds
Idempotent writes for safe retries

Authentication

Use your API key as a Bearer token. Keys are provisioned in your account settings under Profile → API keys.

Required request headers

Authorization: Bearer <api_key>

Auth rules

Keys are tenant-scoped and environment-scoped (live / test). Key prefix determines environment.
Provision or rotate keys under Profile → API keys in your account, or contact support.
Missing or invalid key returns 401.
Correlation and idempotency headers are generated by the proxy when omitted.

Idempotency contract

The proxy auto-generates an Idempotency-Key header when the client omits it.
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.

Quickstart

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

1POST/api/v1/invoices:convert

Start async conversion and receive a task_id for polling. Optional: set format; default is XRECHNUNG.

Request

curl -X POST 'https://invoice-converter.com/api/v1/invoices:convert' \
  -H 'Authorization: Bearer <api_key>' \
  -F 'file=@invoice.pdf' \
  -F 'format=XRECHNUNG'  # optional; allowed: XRECHNUNG|ZUGFERD|EN16931|UBL|CII

Response — 202 Accepted

{
  "task_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "pending",
  "message": "PDF accepted. Conversion started.",
  "filename": "invoice.pdf",
  "file_size": 245832,
  "correlation_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7"
}

2GET/api/v1/tasks/{task_id}

Poll every 2–5 seconds until status is completed or failed. Typical conversion time: 5–15 seconds.

Request

curl 'https://invoice-converter.com/api/v1/tasks/<task_id>' \
  -H 'Authorization: Bearer <api_key>'

Response — 200 OK

{
  "task_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "completed",
  "correlation_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7"
}

3GET/api/v1/tasks/{task_id}/result

Download the generated file. Response is XML or PDF depending on the format requested. If blocking validation issues remain, this endpoint returns 422 VALIDATION_FAILED and no file.

Request

curl -o invoice.xml 'https://invoice-converter.com/api/v1/tasks/<task_id>/result' \
  -H 'Authorization: Bearer <api_key>' -D -

Response — 200 OK

HTTP/1.1 200 OK
Content-Type: application/xml
Content-Disposition: attachment; filename="invoice.xml"
X-Correlation-ID: 7c9e6679-7425-40de-944b-e07fc1f90ae7

<?xml version="1.0" encoding="UTF-8"?>
<Invoice xmlns="urn:oasis:names:specification:ubl:schema:xsd:Invoice-2">
  <!-- XRechnung-compliant UBL 2.1 XML -->
  ...
</Invoice>

Endpoints

All endpoints are served through the website proxy at /api/v1. Upstream timeouts surface as 504; correlation IDs propagate end-to-end for traceability.

POST/api/v1/invoices:convert

Upload a PDF invoice and start asynchronous conversion. Returns a task_id for polling.

Request

Format: multipart/form-data

file (binary, required) — PDF invoice file
format (string, optional, default: XRECHNUNG) — target output format; see format matrix below

Response — 202 Accepted

json

{
  "task_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "pending",
  "message": "PDF accepted. Conversion started.",
  "filename": "invoice.pdf",
  "file_size": 245832,
  "correlation_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7"
}

GET/api/v1/tasks/{task_id}

Poll the current status of a conversion task. Returns pending, processing, completed, or failed. When failed, the response includes an error field with the failure reason.

Request

Format: none (GET)

task_id (path, required) — UUID returned by the convert endpoint

Response — 200 OK

json

{
  "task_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "completed",
  "correlation_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7"
}

GET/api/v1/tasks/{task_id}/result

Download the generated file (XML or PDF). Content type depends on the format requested. If blocking validation issues remain, this endpoint returns 422 VALIDATION_FAILED and no file body.

Request

Format: none (GET)

task_id (path, required) — UUID returned by the convert endpoint

Response — 200 OK

json

Content-Type: application/xml
Content-Disposition: attachment; filename="invoice.xml"
X-Correlation-ID: 7c9e6679-7425-40de-944b-e07fc1f90ae7

<?xml version="1.0" encoding="UTF-8"?>
<Invoice xmlns="urn:oasis:names:...:Invoice-2">...</Invoice>

Output format matrix

Format	Syntax	Version / Profile	Content-Type	Extension
`XRECHNUNG`	UBL 2.1 XML	XRechnung 3.0	`application/xml`	`.xml`
`ZUGFERD`	CII XML in PDF/A-3	ZUGFeRD 2.3 / Factur-X 1.0	`application/pdf`	`.pdf`
`EN16931`	UBL 2.1 XML	EN 16931	`application/xml`	`.xml`
`UBL`	UBL 2.1 XML	OASIS UBL 2.1	`application/xml`	`.xml`
`CII`	UN/CEFACT CII XML	D16B	`application/xml`	`.xml`

Errors

Error catalog

Code	HTTP	Retryable	Notes
AUTHENTICATION_REQUIRED	401	No	Missing/empty bearer token
INVALID_API_KEY	401	No	API key not found/revoked/expired
IDEMPOTENCY_KEY_REQUIRED	400	No	Write endpoint without Idempotency-Key (auto-generated by proxy when omitted)
IDEMPOTENCY_CONFLICT	409	No	Same key used with different request hash
IDEMPOTENCY_IN_PROGRESS	409	Yes	Safe to retry later with same key/payload
AUTH_SERVICE_UNAVAILABLE	503	Yes	Auth backend unavailable
RATE_LIMIT_SERVICE_UNAVAILABLE	503	Yes	Rate-limit backend unavailable
RATE_LIMITED	429	Yes	Respect Retry-After and quota headers
BAD_REQUEST	400	No	Invalid JSON or invalid UUID path parameter
PAYLOAD_TOO_LARGE	413	No	Over upload size limit
INVALID_UPLOAD	400	No	Upload read/parsing failure
UPLOAD_FAILED	4xx/5xx	Conditional	Retry only for transient 5xx cases
TASK_NOT_READY	202	Yes	Poll again for async completion
TASK_STATUS_FAILED	4xx/5xx	Conditional	Retry if transient upstream/backend condition
TASK_RESULT_FAILED	4xx/5xx	Conditional	Retry if transient upstream/backend condition
PROXY_ERROR	502/504	Yes	Proxy/upstream failure (504 for timeout)

Validation response

json — 422 response

{ "code": "VALIDATION_FAILED", "details": [{ "field": "BuyerReference", "rule_id": "BR-DE-15" }] }

Missing mandatory field examples

Convert returns 202 Accepted when file intake succeeds.
Mandatory-field validation happens during async processing.
The result endpoint returns a file only when validation passes.
Blocking validation issues return 422 VALIDATION_FAILED with structured details.
Unreadable/empty PDF → immediate 400 INVALID_UPLOAD.

json — async task result with missing fields

{
  "code": "VALIDATION_FAILED",
  "message": "Validation failed",
  "correlation_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "details": [
    {
      "field": "BuyerReference",
      "rule_id": "BR-DE-15",
      "severity": "error",
      "source": "task-result-download",
      "suggestion": "Provide Leitweg-ID / BuyerReference."
    }
  ]
}

Rate Limits & Reliability

Per-key rate limits and payload size constraints are enforced at the proxy layer. Denied requests do not consume quota.

Rate & payload limits

30 requests per minute per API key
500 requests per hour per API key
PDF upload max size: 20 MB

Retry guidance

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

Polling state machine

Poll GET /api/v1/tasks/{task_id} every 2–5 seconds. Stop when status reaches a terminal state.

pendingTask is queued for processing

processingAI extraction and validation are running

completedResult is ready; fetch via /result endpoint

failedConversion failed; error field in status response explains the reason; /result returns 404

Task lifecycle & retention

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

Business-hours support.
Target first response: 1 business day.