API

E-invoice API: convert PDF invoices to XRechnung and ZUGFeRD

Updated November 2026

What does the pdfvera e-invoice API do?

The pdfvera API turns a PDF invoice into an XRechnung (UBL and CII) and a ZUGFeRD PDF with one HTTP call. You only get files that meet the KoSIT validation rules. If mandatory details are missing, the response names them, and you send them with the next call. Access is included in every plan and counts against the same monthly quota as the converter on the website.

What the API returns

You send a PDF invoice, and the API reads the details and recalculates the totals. If everything is complete, you get up to four files back, each Base64-encoded:

Files in outputs (response of POST /api/v1/de/convert)
FileContent
xrechnung-ubl.xmlXRechnung 3.0 in UBL syntax
xrechnung-cii.xmlXRechnung 3.0 in CII syntax
zugferd-en16931.pdfZUGFeRD invoice (PDF/A-3, EN 16931 profile) with the layout of your PDF
pruefbericht.htmlvalidation report with the KoSIT result plus your details and corrections

These are the same files as from the converter on the website, from the same check. The XRechnung is only delivered if it meets the KoSIT validation rules. The ZUGFeRD PDF is added only if it also passes the check with the Mustang validator; otherwise you get the other three files.

Access and price

  • You create the API key in your account. It is shown once; pdfvera stores only a hash of it and its first ten characters.
  • The API comes with every plan at no extra cost. Each invoice created counts once against your monthly quota, as on the website.
  • Converting the same PDF again in the same month does not count again.
  • A check without files (form field mode=preview, i.e. -F mode=preview) does not count. Use it to test your integration without using up quota.
  • Up to five keys per account, for example one per system. You revoke a key in your account with one click.

Plan prices are on the pricing page. For accounting firms with many clients, the Office plan is available on request.

First call with curl

The key goes in the Authorization header, and the PDF goes along as the form field pdf:

curl https://pdfvera.com/api/v1/de/convert \
  -H "Authorization: Bearer pv_YOUR_KEY" \
  -F pdf=@invoice.pdf

If the invoice is complete, the response contains "deliverable": true, and outputs holds the files. This is how you save the XRechnung with jq; if it is missing, the file stays empty:

curl -s https://pdfvera.com/api/v1/de/convert \
  -H "Authorization: Bearer pv_YOUR_KEY" \
  -F pdf=@invoice.pdf \
  | jq -r '.outputs["xrechnung-ubl.xml"] // empty' | base64 --decode > invoice.xml

Sending missing details

If the PDF lacks a detail that an XRechnung requires, such as the buyer reference (Leitweg-ID, the buyer's routing ID) or the recipient's email address, the response contains "deliverable": false. questions lists the details this invoice needs, with field name, description and example; anything still missing carries "missing": true. You send the values in the form field form as a JSON object, together with the same PDF:

curl https://pdfvera.com/api/v1/de/convert \
  -H "Authorization: Bearer pv_YOUR_KEY" \
  -F pdf=@invoice.pdf \
  -F 'form={"buyer_reference":"04011000-1234512345-06","buyer.email":"rechnung@kunde.de"}'

You correct misread details the same way. The found list shows what was read from the PDF. Each correctable entry names its key in edit[].key, for example fix:number for the invoice number. If a correction is rejected, fix_errors gives the reason:

-F 'form={"fix:number":"RE-2026-0042"}'

Not every invoice can be saved by adding details. If the totals in the PDF do not add up, for example, questions stays empty and reasons gives the reason.

The response at a glance

Response fields (JSON)
FieldMeaning
deliverabletrue if the invoice can be converted; files only without mode=preview
outputsfile name → content (Base64); only when deliverable and without mode=preview
questionsdetails this invoice needs, with field name, text and example; missing: true = still missing
founddetails read from the PDF, with the correction key in edit[].key
invoiceinvoice number, date, seller, buyer, net, tax, gross, amount due, currency
reasonswhy no file is created yet, such as the validation rule kosit:BR-DE-15
used, quotainvoices used and included in the current month (when files are created)

Check your quota with GET /api/v1/usage. The full description of every field is in the OpenAPI file.

Error codes

HTTP status and error code
StatuserrorMeaning
400formform is not a JSON object or is longer than 4,096 characters
401keykey missing, wrong or revoked
402subscriptionno active plan
402quotamonthly quota used up; used and quota are in the response
413sizePDF larger than 20 MB
415typenot a PDF file
422pagesmore than 30 pages
422scannedmore than 10 scanned pages
422pagesizepage size too large
429ratetoo many calls; scope names minute, hour or day
503busyconversion at capacity; please try again later
503unavailableconversion temporarily unavailable
500, 502, 504failedconversion failed; please try again later

Limits

  • One PDF of up to 20 MB and 30 pages per call, with no more than 10 scanned pages.
  • Per account, up to 20 calls a minute, 120 an hour and 1,000 a day, website and API combined.
  • One invoice per call. For many invoices, call the API one after the other.

MCP server for Claude, Cursor and other AI assistants

With the pdfvera MCP server, an AI assistant converts invoices on your computer. The small program reads the PDF from your disk, calls the API with your key and puts the files next to the PDF. If a mandatory detail is missing, the assistant asks you for it and calls the API again. The same quota and limits apply as for the API.

claude mcp add pdfvera -e PDFVERA_API_KEY=pv_YOUR_KEY -- npx -y pdfvera-mcp@latest

Or as the pdfvera plugin (/plugin marketplace add pdfvera/pdfvera-mcp, then /plugin install pdfvera@pdfvera). It brings no MCP server; it shows Claude how to call the API itself. It reads the key from PDFVERA_API_KEY, set in ~/.claude/settings.json under env.

Cursor and other programs with MCP support add the server to their MCP configuration, in Cursor's case in ~/.cursor/mcp.json:

{
  "mcpServers": {
    "pdfvera": {
      "command": "npx",
      "args": ["-y", "pdfvera-mcp@latest"],
      "env": { "PDFVERA_API_KEY": "pv_YOUR_KEY" }
    }
  }
}

The server offers three tools: convert_invoice (PDF invoice to XRechnung and ZUGFeRD), convert_bank_statement (Brazilian bank statements) and get_usage (plan and quota). There is no version yet for ChatGPT, which only connects to MCP servers on the web. With @latest, the server fetches new versions itself the next time it starts. The source code is on GitHub (MIT licence), the package on npm.

Privacy

The PDF is processed in the EU and not stored. We store only a hash of the PDF, and only when files were created, so the same invoice does not count twice in a month. How the file is processed and which service providers are involved is explained under data processing. You will find the data processing agreement under DPA.

API questions

Does the API cost extra?

No. It comes with every plan and uses the same monthly quota as conversion on the website.

Can I test the API without a plan?

With a key and mode=preview, you can check invoices without using up quota. You only get files with a plan.

Which formats does the API produce?

XRechnung 3.0 in UBL and CII, a ZUGFeRD PDF in the EN 16931 profile and a validation report as HTML.

What happens if a detail is missing?

The response lists it in questions. You send the value in the form field with the same PDF again; only then are the files created.

Is my invoice stored?

No. The PDF is processed in the EU and then discarded. We store only a hash of the PDF, and only when files were created.