API reference
Every route of the Klarbon API: authentication, what each call costs, idempotency, rate limits and errors, from the OpenAPI 3.1 document.
On this page
The same tools as klarbon.app, server to server. Authenticate with an API key from your account page in the Authorization header: Bearer kb_live_...
Paid calls spend your API balance first: API packs bought on your account page, and 25 free API calls on the first key, once per email address and excluding disposable addresses. When the API balance is empty they spend the same credits as the site, plan credits before bought ones. When the combined balance cannot cover the call it answers 402 no_credits, or 503 checkoutUnavailable when buying is switched off.
Open is free (fair use 1000 a day per account). Check follows your plan's daily checks. Convert and make cost 1 call per file; bank statements 1 call per started 500 transactions. One call and one credit pay for the same work. A call that fails, or writes a file that does not validate, costs nothing.
Reading plain PDF invoices and PDF bank statements is not available yet. A plain PDF invoice submitted to /convert returns 422 unsupported; a PDF statement submitted to /bank/convert returns 503 extract_failed. Hybrid PDFs with embedded invoice XML are supported.
Files are at most 20 MB and 50 PDF pages. They are processed for the request, without a document archive. Messages follow Accept-Language in the supported interface languages, or the account language when the header is absent.
Rate limits: 60 requests a minute per key (bursts of 10) and 120 per account, announced in the RateLimit and RateLimit-Policy headers; a per-minute rate-limit refusal carries Retry-After.
Base address: https://klarbon.app/api/v1. Version 1.0.0. The full description is the OpenAPI 3.1.0 document.
Sending files
Send the file as multipart/form-data with a file field and the parameters as other
fields, or as the raw body with its Content-Type and the parameters in the query string. Messages
follow Accept-Language, else your account's language.
Idempotency
Paid calls take an Idempotency-Key header. A repeat with the same key and the same request within
24 hours never charges again and answers credits.spent: 0. The same key with a different request is
422; a repeat while the first call still runs is 409.
Errors
Every error is { ok: false, error, message }: error is a stable code, message one plain sentence in the caller's language, which may change.
| Status | Code | When |
|---|---|---|
| 400 | invalid | A malformed request or parameter, or a key in the address. |
| 401 | auth | No key where one is needed, or an unknown or revoked key. |
| 402 | no_credits | The combined API balance and credits cannot cover the call. Nothing was charged; topUpUrl says where to buy. |
| 409 | invalid | The first call with this Idempotency-Key is still running. |
| 413 | too_large | Over 20 MB or 50 PDF pages. |
| 415 | unsupported | A file format the route does not take. The message lists those it does. |
| 422 | invalid | The file could not be read, the written file did not validate (with report), or the Idempotency-Key was used for another request. |
| 422 | unsupported | A target format the route cannot write. |
| 503 | extract_failed | Reading PDF statements is not available yet. |
| 429 | limit | A rate limit or the day's free calls. |
| 503 | engine_unavailable | Validation is briefly unavailable. Nothing was charged. |
| 500 | internal | Our fault. Nothing was charged. |
Formats
GET /formats
Every format and what each tool can do with it. Works with or without an API key.
Answers with formats.
curl https://klarbon.app/api/v1/formatsE-invoices
POST /open
Read an e-invoice into the Klarbon invoice model, optionally as HTML. Free, within the fair use limit. Needs an API key.
| Name | In | Description |
|---|---|---|
html | query | Also return the invoice as complete, print-ready HTML. One of 0, 1, true, false. |
locale | query | The language of the HTML's labels; defaults to the request's language. One of en, de, fr, nl, it, es, pl, pt, ro. |
Body: multipart/form-data, application/xml, application/octet-stream. The file, at most 20 MB: as multipart/form-data with a file field, or as the raw body with its Content-Type (parameters then go in the query).
Answers with format, invoice, warnings, losses, wrappers, html.
curl https://klarbon.app/api/v1/open \
-H "Authorization: Bearer $KLARBON_API_KEY" \
-F file=@invoice.xml POST /check
Validate an e-invoice, with each finding explained. Counts towards the account's daily checks, shared with the site. Needs an API key.
| Name | In | Description |
|---|---|---|
ruleset | query | A rule set id, or auto to pick it from the file. Leave it out when you send country. One of auto, en16931-ubl, en16931-cii, en16931-ubl-creditnote, xrechnung-3.0-ubl, xrechnung-3.0-cii, peppol-bis3-invoice, peppol-bis3-creditnote, facturx-1.07-minimum, facturx-1.07-basicwl, facturx-1.07-basic, facturx-1.07-en16931, facturx-1.07-extended, zugferd-2.3-minimum, zugferd-2.3-basicwl, zugferd-2.3-basic, zugferd-2.3-en16931, zugferd-2.3-extended, facturx-1.09-minimum, facturx-1.09-basicwl, facturx-1.09-basic, facturx-1.09-en16931, facturx-1.09-extended, zugferd-2.5-minimum, zugferd-2.5-basicwl, zugferd-2.5-basic, zugferd-2.5-en16931, zugferd-2.5-extended, nlcius, nlcius-cii, fr-ctc, fr-ctc-cii. |
country | query | Also apply this country's national rules on top of EN 16931 (FR: the French CTC rules for the file's syntax). Only when you send it; Klarbon never infers a country from the file. One of FR. |
Body: multipart/form-data, application/xml, application/octet-stream. The file, at most 20 MB: as multipart/form-data with a file field, or as the raw body with its Content-Type (parameters then go in the query).
Answers with format, report, invoice, usage.
curl https://klarbon.app/api/v1/check \
-H "Authorization: Bearer $KLARBON_API_KEY" \
-F file=@invoice.xml POST /convert
Convert an e-invoice to another format. 1 call, charged only when the written file validates. Plain PDF invoices without embedded XML return 422 unsupported; reading them is not available yet. Needs an API key.
| Name | In | Description |
|---|---|---|
Idempotency-Key | header | A unique string of 1 to 255 visible ASCII characters, without spaces. A repeat with the same key and request within 24 hours runs again without another charge. |
target (required) | query | A format id with the convertTo tool, from /formats. |
profile | query | The profile, for formats that have several. |
labelLocale | query | The language of a rendered PDF's labels; defaults to the request's language. One of en, de, fr, nl, it, es, pl, pt, ro. |
Body: multipart/form-data, application/xml, application/octet-stream. The file, at most 20 MB: as multipart/form-data with a file field, or as the raw body with its Content-Type (parameters then go in the query).
Answers with file, report, losses, credits.
curl https://klarbon.app/api/v1/convert \
-H "Authorization: Bearer $KLARBON_API_KEY" \
-H "Idempotency-Key: convert-invoice-4711" \
-F file=@invoice.xml -F target=xrechnung POST /make
Write an invoice from JSON in any format Klarbon makes. 1 call, charged only when the written file validates. Needs an API key.
| Name | In | Description |
|---|---|---|
Idempotency-Key | header | A unique string of 1 to 255 visible ASCII characters, without spaces. A repeat with the same key and request within 24 hours runs again without another charge. |
Body: application/json.
Answers with file, report, losses, credits.
curl https://klarbon.app/api/v1/make \
-H "Authorization: Bearer $KLARBON_API_KEY" \
-H "Content-Type: application/json" \
-d '{"target": "peppol-bis-billing", "invoice": { ... }}'Bank statements
POST /bank/convert
Convert a bank statement, answering what the file leaves open. When the file leaves something open (date order, opening balance, an account to choose), the answer is status need: send the same file again with the answer and resume. Nothing is charged for a need. A converted statement costs 1 call per started 500 transactions. Reading PDF statements is not available yet; PDF input returns 503 extract_failed. Structured bank files such as CAMT.053 and MT940 can be converted. Needs an API key.
| Name | In | Description |
|---|---|---|
Idempotency-Key | header | A unique string of 1 to 255 visible ASCII characters, without spaces. A repeat with the same key and request within 24 hours runs again without another charge. |
target (required) | query | A bank format id with the convertTo tool, from /formats. |
statementNumber | query | The statement number MT940 and CODA carry; digits only. |
openingBalance | query | The opening balance the file does not print, as a decimal string. |
dateOrder | query | How the file writes its dates. One of dmy, mdy, ymd. |
century | query | The century of two-digit years. One of 1900, 2000. |
currency | query | ISO 4217, for a file that states no currency. |
decimalSeparator | query | The decimal separator of the file's amounts. One of ., ,. |
account | query | For a file with several accounts: the chosen account's position in the need's preview.accounts. |
resume | query | From the last need answer, with the same file: the file is not read a second time. |
Body: multipart/form-data, application/xml, application/octet-stream. The file, at most 20 MB: as multipart/form-data with a file field, or as the raw body with its Content-Type (parameters then go in the query).
curl https://klarbon.app/api/v1/bank/convert \
-H "Authorization: Bearer $KLARBON_API_KEY" \
-F file=@statement.xml -F target=csvAccount
GET /usage
The API balance, credits left, auto top-up and today's free calls. Needs an API key.
Answers with credits, today, topUp, apiTopUp.
curl https://klarbon.app/api/v1/usage \
-H "Authorization: Bearer $KLARBON_API_KEY" GET /openapi.json
This document. No API key needed.
curl https://klarbon.app/api/v1/openapi.jsonPrices, limits and how to get a key: Klarbon for developers.