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:
| File | Content |
|---|---|
xrechnung-ubl.xml | XRechnung 3.0 in UBL syntax |
xrechnung-cii.xml | XRechnung 3.0 in CII syntax |
zugferd-en16931.pdf | ZUGFeRD invoice (PDF/A-3, EN 16931 profile) with the layout of your PDF |
pruefbericht.html | validation 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.pdfIf 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.xmlSending 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
| Field | Meaning |
|---|---|
deliverable | true if the invoice can be converted; files only without mode=preview |
outputs | file name → content (Base64); only when deliverable and without mode=preview |
questions | details this invoice needs, with field name, text and example; missing: true = still missing |
found | details read from the PDF, with the correction key in edit[].key |
invoice | invoice number, date, seller, buyer, net, tax, gross, amount due, currency |
reasons | why no file is created yet, such as the validation rule kosit:BR-DE-15 |
used, quota | invoices 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
| Status | error | Meaning |
|---|---|---|
| 400 | form | form is not a JSON object or is longer than 4,096 characters |
| 401 | key | key missing, wrong or revoked |
| 402 | subscription | no active plan |
| 402 | quota | monthly quota used up; used and quota are in the response |
| 413 | size | PDF larger than 20 MB |
| 415 | type | not a PDF file |
| 422 | pages | more than 30 pages |
| 422 | scanned | more than 10 scanned pages |
| 422 | pagesize | page size too large |
| 429 | rate | too many calls; scope names minute, hour or day |
| 503 | busy | conversion at capacity; please try again later |
| 503 | unavailable | conversion temporarily unavailable |
| 500, 502, 504 | failed | conversion 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 Desktop: download the pdfvera.mcpb extension, open it with a double click and enter your API key.
- Claude Code (needs Node.js 18 or later):
claude mcp add pdfvera -e PDFVERA_API_KEY=pv_YOUR_KEY -- npx -y pdfvera-mcp@latestOr 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.