Introduction

BillScan is a REST API for parsing Swiss QR-bills from PDF files. It extracts all structured payment data — IBAN, creditor, debtor, amount, and reference — and returns clean JSON.

The API follows the Swiss Payments Code specification (SIX Group, v2.2). Files are processed in memory and never stored.

Base URLhttps://billscan.ch/api

Authentication

All requests except /api/health require an API key in the X-API-Key header.

curl -X POST https://billscan.ch/api/parse \
  -H "X-API-Key: bsk_live_your_key_here" \
  -F "file=@invoice.pdf"

Get your API key from the dashboard after signing up. Keys follow the format bsk_live_xxxxxxxx...

Quick Start

Sign up at billscan.ch/signup
Copy your API key from the dashboard
Make your first API call

curl -X POST https://billscan.ch/api/parse \
  -H "X-API-Key: bsk_live_your_key_here" \
  -F "file=@your-swiss-invoice.pdf"

POST /api/parse

POST/api/parse

Accepts a Swiss QR-bill PDF and returns structured payment data as JSON.

Request

Parameter	Location	Required	Description
X-API-Key	Header	Yes	Your API key
file	Form field (multipart)	Yes	The PDF file to parse

Example request

curl -X POST https://billscan.ch/api/parse \
  -H "X-API-Key: bsk_live_your_key_here" \
  -F "file=@invoice.pdf"

Response 200

{
  "iban": "CH5604835012345678009",
  "creditor": {
    "addressType": "S",
    "name": "Muster Rechnung AG",
    "street": "Musterstrasse",
    "buildingNumber": "123",
    "postalCode": "8000",
    "city": "Zürich",
    "country": "CH"
  },
  "amount": 199.00,
  "amountFormatted": "199.00",
  "currency": "CHF",
  "debtor": {
    "addressType": "S",
    "name": "Max Muster",
    "street": "Musterstrasse",
    "buildingNumber": "1",
    "postalCode": "8000",
    "city": "Zürich",
    "country": "CH"
  },
  "reference": {
    "type": "QRR",
    "reference": "210000000003139471430009017"
  },
  "unstructuredMessage": "Rechnung Nr. 2026-001",
  "billingInformation": null
}

Response fields

Field	Type	Description
iban	string	Creditor IBAN in compact format (no spaces)
creditor	object	Creditor name and address
ultimateCreditor	object or null	Ultimate creditor if present in QR data
amount	number or null	Payment amount as a number
amountFormatted	string or null	Amount formatted to 2 decimal places
currency	string	CHF or EUR
debtor	object or null	Debtor name and address
reference.type	string	QRR, SCOR, or NON
reference.reference	string	Reference number
unstructuredMessage	string or null	Free text message field
billingInformation	string or null	Structured billing info starting with //S1/

GET /api/health

GET/api/health

Health check endpoint. No authentication required.

curl https://billscan.ch/api/health

Response 200

{
  "status": "ok",
  "timestamp": "2026-05-25T10:00:00.000Z"
}

Error Codes

All error responses follow this shape:

{
  "error": {
    "code": "INVALID_API_KEY",
    "message": "Invalid or inactive API key."
  }
}

Code	HTTP Status	Description
MISSING_API_KEY	401	No API key provided in X-API-Key header
INVALID_API_KEY	401	API key not found or inactive
RATE_LIMIT_EXCEEDED	429	Monthly parse limit reached. Upgrade to Pro.
NO_FILE	400	No file field in the request body
INVALID_FILE	400	File provided is not a PDF
NO_PAGES	422	PDF could not be decoded or has no pages
NO_QR_CODE	422	No QR code found in any page of the PDF
NOT_SWISS_QR	422	QR code found but not a Swiss Payments Code
PARSE_ERROR	422	QR data found but could not be parsed against SIX spec

Rate Limits

Plan	Parses per month	Per-minute limit	Price
Free	50	10	0 CHF
Pro	1,000	60	9 CHF/month
Custom	10,000+	Custom	Contact us

When the monthly limit is reached, all requests return 429 RATE_LIMIT_EXCEEDED until the limit resets at the start of the next calendar month.

Upgrade your plan →

QR-bill Spec

BillScan implements version 2.2 of the Swiss Payments Code (SPC) specification, defined by SIX Group.

The QR code embedded in a Swiss invoice contains structured payment data across 28–32 newline-separated fields. BillScan handles:

Native PDFs generated by accounting software
Scanned PDFs from photographed paper invoices
Multi-page PDFs where the QR code appears on any page
Both QRR (QR reference) and SCOR (creditor reference) formats

Official SIX specification →