API Reference — Bank Statement Parser

Czech Bank Statement Parser API

REST API for extracting structured transaction data from Czech bank statement PDFs. Upload a PDF — get back JSON with account info, statement metadata, and a full list of transactions with semantic tags.

Supported banks: KB (/0100), MONETA (/0600), Air Bank (/3030), ČSOB (/0300), mBank (/6210), Raiffeisenbank (/5500), Fio (/2010), UniCredit (/2700), Česká spořitelna (/0800), Partners Banka (/6363).

Base URL

API endpoint

https://api.ginibooster.cz

All endpoints are prefixed with /api/v1. The full URL for each endpoint is shown in the examples below.

Authentication

Every request to a business endpoint must include a Bearer token in the Authorization header:

header

Authorization: Bearer YOUR_API_KEY

API keys are issued manually by the operator — contact ginibooster@gmail.com to request one. The same header accepts a JWT access token obtained via /api/v1/auth/login for browser sessions.

New accounts created via /auth/register must be approved by an administrator before they can call the business endpoints; until approval the API returns 403. API-key callers bypass this check — issuing a key implies approval.

Error codes

Status	Meaning	Body
200	Parsing successful	`{"result": {...}, "file_id": "..."}`
400	Bad request — missing or invalid file	`{"error": "..."}`
401	Missing or invalid Bearer token	`{"error": "..."}`
403	Account awaits administrator approval	`{"error": "..."}`
422	File is not a recognised bank statement	`{"error": "...", "file_id": "..."}`
500	Unexpected server error	`{"error": "...", "file_id": "..."}`

POST /api/v1/bs_parse

Upload a Czech bank statement PDF. Returns structured JSON with account details, statement period, and all parsed transactions.

Request

Two content types are accepted:

Option A — Content-Type: application/json

Field	Type	Description
filerequired	string	PDF file encoded as Base64
filenameoptional	string	Original filename (must end with `.pdf`). Default: `upload.pdf`

Option B — Content-Type: multipart/form-data

Field	Type	Description
filerequired	file	PDF file, max 20 MB

Example — cURL (Base64 JSON)

shell

B64=$(base64 -w 0 statement.pdf)
curl -X POST https://api.ginibooster.cz/api/v1/bs_parse \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"file\":\"$B64\",\"filename\":\"statement.pdf\"}"

Example — cURL (multipart)

shell

curl -X POST https://api.ginibooster.cz/api/v1/bs_parse \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@statement.pdf"

Example — Python (Base64 JSON)

python

import base64, requests

with open("statement.pdf", "rb") as f:
    b64 = base64.b64encode(f.read()).decode()

resp = requests.post(
    "https://api.ginibooster.cz/api/v1/bs_parse",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    json={"file": b64, "filename": "statement.pdf"},
)
print(resp.json())

Response — 200 OK

json

{
  "file_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890.pdf",
  "result": {
    "bank": "KB",
    "account": {
      "number":   "123456789/0100",
      "iban":     "CZ65 0800 0000 0012 3456 7890",
      "bic":      "KOMBCZPP",
      "owner":    "Jan Novák",
      "currency": "CZK",
      "type":     "Osobní účet"
    },
    "statement": {
      "number":          "12",
      "period_from":    "2026-01-01",
      "period_to":      "2026-01-31",
      "date_issued":    "2026-02-01",
      "opening_balance": 12500.00,
      "closing_balance": 18340.50,
      "total_credited":  35000.00,
      "total_debited":   -29159.50
    },
    "transactions": [ /* see Transaction object below */ ]
  }
}

POST /api/v1/report_bug

Submit a parsing error report linked to a previously uploaded file. Reports are stored server-side and reviewed manually.

Request

Content-Type: application/json

Field	Type	Description
textrequired	string	Description of the parsing issue
file_idoptional	string	UUID from a previous `/bs_parse` response
original_nameoptional	string	Original filename of the uploaded PDF
bankoptional	string	Detected bank name from the parse result

Example — cURL

shell

curl -X POST https://api.ginibooster.cz/api/v1/report_bug \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "file_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890.pdf",
    "original_name": "statement.pdf",
    "bank": "KB",
    "text": "Transaction on 2026-01-15 is missing from the output."
  }'

Response — 200 OK

json

{ "ok": true }

GET /uploads/<file_id>

Download or display a previously uploaded PDF by its UUID. Useful for embedding an in-browser PDF preview alongside the parse result.

Path parameter

Parameter	Type	Description
file_idrequired	string	UUID returned by `/api/v1/bs_parse`, e.g. `a1b2c3d4…pdf`

Example — cURL

shell

curl https://api.ginibooster.cz/uploads/a1b2c3d4-e5f6-7890-abcd-ef1234567890.pdf \
  -H "Authorization: Bearer YOUR_API_KEY" \
  --output statement.pdf

Response

Returns the raw PDF file with Content-Type: application/pdf.

Response object

Top-level shape returned by /api/v1/bs_parse.

account

Field	Type	Notes
number	string\|null	Local format, e.g. `123456789/0100`
iban	string\|null
bic	string\|null
owner	string\|null	Account holder name
currency	string	Always `"CZK"`
type	string\|null	Account type label

statement

Field	Type	Notes
number	string\|null	Statement serial number
period_from	string\|null	ISO date `YYYY-MM-DD`
period_to	string\|null	ISO date `YYYY-MM-DD`
date_issued	string\|null	ISO date
opening_balance	float\|null
closing_balance	float\|null
total_credited	float\|null	Sum of incoming transactions
total_debited	float\|null	Negative value

Transaction object

Each item in transactions[]. Unused fields are null. Debit amounts are negative floats. Dates are ISO YYYY-MM-DD.

Field	Type	Notes
date_posted	string\|null	Accounting date
date_valuta	string\|null	Value date
amount	float\|null	Negative = debit, positive = credit
currency	string	Always `"CZK"`
type	string\|null	Transaction category from the bank
description	string\|null	Payment message / note
counterparty_account	string\|null	E.g. `987654321/0600`
counterparty_name	string\|null
vs	string\|null	Variable symbol
ks	string\|null	Constant symbol
ss	string\|null	Specific symbol
fee	float\|null	Transaction fee (Air Bank only)
transaction_id	string\|null	Bank-assigned transaction ID
balance_after	float\|null	Running balance after this transaction
raw_line	string\|null	Raw PDF text line (debug only)
tags	string[]	Semantic tags — see below

Example transaction

json

{
  "date_posted":          "2026-01-05",
  "date_valuta":          "2026-01-05",
  "amount":               35000.00,
  "currency":             "CZK",
  "type":                 "Příchozí úhrada",
  "description":          "Mzda leden 2026",
  "counterparty_account": "987654321/0600",
  "counterparty_name":    "Acme s.r.o.",
  "vs":                   "20260105",
  "ks":                   "0308",
  "ss":                   null,
  "fee":                  null,
  "transaction_id":       "20260105001",
  "balance_after":        47500.00,
  "raw_line":             null,
  "tags":                 ["salary"]
}

Transaction tags

Tags in tags[] are assigned automatically after parsing. A transaction can have multiple tags simultaneously.

salary gambling

Tag definitions

Tag	Applied when
salary	KS=138, or SEPA salary reference, or salary keywords in description (mzda, plat…). Excludes ČSSZ payments.
social	Counterparty is ČSSZ, or social benefit keywords in description (nemocenská, mateřská…).
gambling	Gambling brand names in description or counterparty name (Fortuna, Tipsport, Betano, Sazka, …).

POST /api/v1/id_parse

Upload a photo of a Czech identity card (Občanský průkaz) and receive structured JSON with extracted fields. Powered by AI vision — handles rotated images, both card generations (pre-2012 and current), front and back sides.

Request

Two content types are accepted:

Option A — Content-Type: application/json

Field	Type	Description
filerequired	string	Image file encoded as Base64
filenameoptional	string	Original filename (must end with `.jpg`, `.jpeg`, `.png`, or `.webp`). Default: `upload.jpg`

Option B — Content-Type: multipart/form-data

Field	Type	Description
filerequired	file	JPG / PNG / WEBP image, max 20 MB

Example — cURL (Base64 JSON)

shell

B64=$(base64 -w 0 id_card_front.jpg)
curl -X POST https://api.ginibooster.cz/api/v1/id_parse \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"file\":\"$B64\",\"filename\":\"id_card_front.jpg\"}"

Example — cURL (multipart)

shell

curl -X POST https://api.ginibooster.cz/api/v1/id_parse \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@id_card_front.jpg"

Example — Python (Base64 JSON)

python

import base64, requests

with open("id_card_front.jpg", "rb") as f:
    b64 = base64.b64encode(f.read()).decode()

resp = requests.post(
    "https://api.ginibooster.cz/api/v1/id_parse",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    json={"file": b64, "filename": "id_card_front.jpg"},
)
print(resp.json())

Response — 200 OK (front side)

json

{
  "file_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890.jpg",
  "result": {
    "document_type": "cz_id",
    "side":          "front",
    "front": {
      "document_number": "217095421",
      "surname":         "HOYER",
      "given_names":     "HUBERT",
      "date_of_birth":   "22.02.1949",
      "sex":             "M",
      "place_of_birth":  "PRAHA 5",
      "nationality":     "ČESKÁ REPUBLIKA",
      "date_of_issue":   "24.04.2024",
      "date_of_expiry":  "24.04.2059",
      "personal_number": "958535"
    },
    "back": null
  }
}

Response — 200 OK (back side)

json

{
  "file_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890.jpg",
  "result": {
    "document_type": "cz_id",
    "side":          "back",
    "front": null,
    "back": {
      "address":         "Praha, Holešovice, Přístávní č.p. 2657/4",
      "personal_number": "960536/0553",
      "marital_status":  "svobodná",
      "mrz_line1":       "IDCZE196563055<<<<<<<<<<<<<<<<<<<<<<<<6",
      "mrz_line2":       "9005053F3601028CZE<<ANDREA"
    }
  }
}

Response — 422 (not a Czech ID)

json

{ "error": "Not a recognised Czech identity card.", "file_id": "..." }

ID document object

Top-level shape returned by /api/v1/id_parse.

Top-level fields

Field	Type	Values
document_type	string	`"cz_id"` · `"unknown"`
side	string	`"front"` · `"back"` · `"unknown"`
front	object\|null	Populated when `side = "front"`
back	object\|null	Populated when `side = "back"`

front object

Field	Type	Notes
document_number	string\|null	9-digit number (ČÍSLO DOKLADU)
surname	string\|null	PŘÍJMENÍ
given_names	string\|null	JMÉNO
date_of_birth	string\|null	DD.MM.YYYY
sex	string\|null	`"M"` or `"F"`
place_of_birth	string\|null	MÍSTO NAROZENÍ
nationality	string\|null	STÁTNÍ OBČANSTVÍ
date_of_issue	string\|null	DD.MM.YYYY (DATUM VYDÁNÍ)
date_of_expiry	string\|null	DD.MM.YYYY (PLATNOST DO)
personal_number	string\|null	6-digit partial rodné číslo shown on front

back object

Field	Type	Notes
address	string\|null	Full address (street, city, district)
personal_number	string\|null	Full rodné číslo from MRZ, e.g. `960536/0553`
marital_status	string\|null	Rodinný stav if visible
mrz_line1	string\|null	First MRZ line (starts with IDCZE)
mrz_line2	string\|null	Second MRZ line