API documentation

All tools on this site are available as a free JSON API. No API key, no sign-up. CORS is enabled, so you can call it from the browser.

Base URL: https://swissinvoice.dev/api/v1
Rate limit: Requests are rate-limited per IP address: 60 per minute for validation, 120 per minute for IBAN checks and generation. Above that you get HTTP 429 with a Retry-After header.
Language: Add ?lang=de, fr or it to get error messages in German, French or Italian. Default is English.
Errors: Validation endpoints always return HTTP 200 with valid: true/false and lists of errors and warnings. Each issue has a stable code, the affected field, the line in the payload (if applicable) and a human-readable message. Malformed requests return HTTP 4xx with an error object.

Validate a QR-bill payload

POST/api/v1/qr-bill/validate

Send the raw QR code text as text/plain (or as JSON {"payload": "…"}).

curl

curl -X POST "https://swissinvoice.dev/api/v1/qr-bill/validate?lang=en" \
  -H "Content-Type: text/plain" \
  --data-binary @payload.txt

Response

{
  "valid": false,
  "errors": [
    {
      "code": "iban.checksum",
      "field": "account",
      "line": 4,
      "message": "The check digits do not match. There is probably a typo in the IBAN."
    },
    {
      "code": "address.combined",
      "field": "creditor",
      "line": 5,
      "message": "Combined addresses (type K) are no longer accepted since 21 November 2025. Use a structured address (type S)."
    }
  ],
  "warnings": [
    {
      "code": "amount.decimals",
      "field": "amount",
      "line": 19,
      "params": {
        "value": "100.5"
      },
      "message": "The amount \"100.5\" should have exactly two decimals, e.g. 100.00."
    }
  ],
  "data": {
    "version": "0200",
    "account": "CH4431999123000889013",
    "…": "…"
  }
}

Check an IBAN

GET/api/v1/iban?iban=…

Pass the IBAN as a query parameter. Spaces are allowed.

curl

curl "https://swissinvoice.dev/api/v1/iban?iban=CH0430000001234567890"

Response

{
  "valid": true,
  "input": "CH0430000001234567890",
  "iban": "CH0430000001234567890",
  "formatted": "CH04 3000 0001 2345 6789 0",
  "country": "CH",
  "swiss": {
    "iid": "30000",
    "isQrIban": true,
    "referenceTypes": [
      "QRR"
    ],
    "bank": {
      "iid": "30000",
      "name": "PostFinance AG",
      "town": "Bern",
      "bic": "POFICHBEXXX"
    }
  },
  "errors": [],
  "warnings": []
}

Generate a QR-bill

POST/api/v1/qr-bill

Send JSON, get back an SVG (default) or a PDF. Set format to pdf and paperSize to a4 or slip.

curl

curl -X POST https://swissinvoice.dev/api/v1/qr-bill \
  -H "Content-Type: application/json" \
  -d '{
  "creditor": {
    "account": "CH04 3000 0001 2345 6789 0",
    "name": "Robert Schneider AG",
    "street": "Rue du Lac",
    "buildingNumber": "1268",
    "postalCode": "2501",
    "town": "Biel",
    "country": "CH"
  },
  "debtor": {
    "name": "Pia-Maria Rutschmann-Schnyder",
    "street": "Grosse Marktgasse",
    "buildingNumber": "28",
    "postalCode": "9400",
    "town": "Rorschach",
    "country": "CH"
  },
  "amount": 1949.75,
  "currency": "CHF",
  "reference": "210000000003139471430009017",
  "message": "Order of 15 June 2026",
  "language": "en",
  "format": "pdf",
  "paperSize": "a4"
}' \
  -o qr-bill.pdf

Request fields

creditor.account	string	IBAN or QR-IBAN (CH/LI). Spaces allowed.
creditor.name	string ≤70	Required.
creditor.street / buildingNumber	string ≤70 / ≤16	Optional.
creditor.postalCode / town	string ≤16 / ≤35	Required.
creditor.country	string	ISO 3166-1 alpha-2, e.g. CH.
debtor	object	Optional. Same fields as creditor, without account.
amount	number	Optional. 0.01–999999999.99, at most two decimals.
currency	"CHF" \| "EUR"	Default CHF.
reference	string	QR reference (27 digits) for QR-IBANs, RF creditor reference or empty otherwise.
message	string ≤140	Optional unstructured message.
billInformation	string ≤140	Optional structured bill information, e.g. Swico S1. Combined with message max. 140.
language	"en" \| "de" \| "fr" \| "it" \| "rm"	Language of the payment part. Default en.
format	"svg" \| "pdf"	Default svg.
paperSize	"a4" \| "slip"	PDF only. Default a4.

If no valid QR-bill can be built from the input, the endpoint returns HTTP 422. error.code is invalid_input for malformed fields or invalid_qr_bill for QR-bill rule violations; error.details lists the issues with code, field and message.