API reference

Base URL https://iban.trekle.space. All responses are JSON encoded in UTF-8. Every lookup is answered from the full dataset held in memory, built from official publishers only.

Authentication

Send your API key as a bearer token on every paid endpoint:

Authorization: Bearer <your key>

You get a key right after checkout. It's shown once, so store it in a secret manager. If a key leaks, rotate it: the old key stops working immediately.

Keep keys server side. Don't ship them in browser or mobile code.

IBAN lookup

GET/v1/iban/{iban}API key

Validates the IBAN (country, length, BBAN structure from the SWIFT IBAN Registry, mod-97 check digits) and returns the bank behind it. Spaces and lowercase letters are accepted; URL-encode spaces or strip them.

curl -H "Authorization: Bearer $IBANDB_KEY" \
  https://iban.trekle.space/v1/iban/DE89370400440532013000

{"iban":"DE89370400440532013000","valid":true,"country":"DE","country_name":"Germany","sepa":true,"check_digits":"89","bban":"370400440532013000","bank_code":"37040044","bank":{"country":"DE","bank_code":"37040044","branch_code":null,"bic":"COBADEFFXXX","bic_source":"source","name":"Commerzbank","short_name":"Commerzbank Köln","city":"Köln","postal_code":"50447","address":null,"lei":"851WYGNLUQLFZBSYGB56","legal_name":"COMMERZBANK Aktiengesellschaft","sepa_schemes":["SCT","SCT_INST","SDD_B2B","SDD_CORE","VOP"],"sepa_schemes_match":"bic","sources":["de_bundesbank"]},"data_version":"2026-09-24T07:51:20+00:00"}

Status codes: 200 for a valid IBAN, whether or not the bank is known; 422 for an invalid IBAN, with the same body shape, "valid": false and an errors list.

Response fields

Field	Type	Meaning
`iban`	string	The IBAN, normalised: uppercase, no spaces.
`valid`	boolean	Country known, length and BBAN structure match the registry, and the mod-97 check passes.
`errors`	string[]	Only when invalid. For example `"invalid checksum"`, `"wrong length: got 21, want 22"`, `"unknown IBAN country XX"`, `"BBAN does not match …"` (followed by the expected structure), `"check digits must be numeric"`, `"too short"`.
`country`	string	ISO 3166-1 alpha-2 code from the IBAN.
`country_name`	string	Country name as listed in the SWIFT IBAN Registry.
`sepa`	boolean	Whether the country is in the SEPA area.
`check_digits`	string	The two IBAN check digits.
`bban`	string	The national part of the IBAN.
`bank_code`	string	Bank identifier extracted from the BBAN at the position the registry defines.
`branch_code`	string	Branch identifier, for countries whose IBAN contains one.
`bank`	object \| null	The bank object, or `null` when the IBAN is invalid or no official register lists the bank code. A branch-level entry is returned when the branch is known, else the bank-level one.
`matched_country`	string	Only when the bank was found in another country's code register. Monaco IBANs, for instance, use French bank codes and resolve against `FR`.
`data_version`	string	ISO 8601 timestamp of the dataset build that answered.
`stale_sources`	string[]	Only when set. Source ids behind this bank record that are older than twice their publisher's refresh cadence. The record is still the latest official data we have, but may be out of date.

Bank object

Returned in bank of an IBAN lookup, in banks of a BIC lookup, and as the body of a bank-code lookup. Fields the publisher doesn't provide are null; short_name, lei, legal_name and derived_from_branches are omitted when absent.

Field	Type	Meaning
`country`	string	Country of the register the record comes from.
`bank_code`	string	National bank code.
`branch_code`	string \| null	Branch code for a branch-level record; `null` for the bank-level record.
`bic`	string \| null	BIC (8 or 11 characters) as published. See `bic_source`.
`bic_source`	string \| null	Where the BIC comes from. See provenance flags.
`name`	string	Institution name as the national publisher writes it.
`short_name`	string	Short or branch name, when published.
`address`, `postal_code`, `city`	string \| null	Address as published. Not every register includes it.
`lei`	string	Legal Entity Identifier, from the national register or GLEIF.
`legal_name`	string	Registered legal name from GLEIF's LEI record.
`sepa_schemes`	string[]	EPC schemes the institution has joined: `SCT`, `SCT_INST`, `SDD_CORE`, `SDD_B2B`, `VOP` (Verification of Payee), `OCT_INST`, `SRTP`. Empty when the institution isn't in the EPC register.
`sepa_schemes_match`	string \| null	How the record was matched to the EPC register: `"bic"` or `"lei"`. `null` when there are no schemes.
`sources`	string[]	Ids of the sources this record was built from. Resolve them with `GET /v1/sources`.
`derived_from_branches`	boolean	Only when `true`: the publisher lists branches only, and this bank-level record was derived from them.

Provenance flags

bic_source

"source": the BIC is stated by the national publisher (or, for countries covered through GLEIF, by GLEIF's BIC data).
"gleif_lei": the national register gives no BIC for this bank. We filled it from GLEIF's official BIC-to-LEI mapping; when the LEI has several BICs, the one registered in the EPC SEPA register is used.
"gleif_lei_not_sepa": as above, but that BIC is not registered in any EPC SEPA scheme (e.g. a leasing company's passive BIC). Verify before using it for SEPA payments.
"epc_name_match": the national register gives no BIC; the bank's legal name is identical (ignoring case, accents, punctuation and a compatible legal form such as A/S or S.A.) to exactly one participant of the EPC SEPA register in the same country. No fuzzy matching.

sepa_schemes_match

"bic": the bank's BIC is listed in the EPC Register of Participants.
"lei": the BIC isn't listed, but an EPC participant has the same LEI. The EPC lists one BIC per adhering legal entity, so other BICs of that entity are matched this way.

An empty sepa_schemes in a SEPA country usually means the institution reaches SEPA through another payment service provider, not that payments to it will fail.

BIC lookup

GET/v1/bic/{bic}API key

Every bank record using a BIC. Accepts 8 or 11 characters, case-insensitive.

curl -H "Authorization: Bearer $IBANDB_KEY" \
  https://iban.trekle.space/v1/bic/COBADEFFXXX

{ "bic": "COBADEFFXXX", "banks": [ { …bank object… }, … ] }

400 if the BIC isn't 8 or 11 characters, 404 if no record uses it.

Bank-code lookup

GET/v1/banks/{country}/{code}?branch={branch}API key

Look up a national bank code directly, without an IBAN. branch is optional; when the branch isn't known you get the bank-level record. The body is a single bank object.

curl -H "Authorization: Bearer $IBANDB_KEY" \
  "https://iban.trekle.space/v1/banks/IT/05428?branch=11101"

404 with {"error": "unknown bank code"} when the code isn't in the register.

Public endpoints

No key needed.

GET/v1/sources

Every source in the current dataset: publisher, dataset name, homepage, countries, refresh cadence in days, published_at (the publisher's date, when it states one), fetched_at, record count and a stale flag.

{"data_version":"2026-09-24T08:04:43+00:00","sources":{"de_bundesbank":{"kind":"banks","publisher":"Deutsche Bundesbank","dataset":"Bankleitzahlendatei","homepage":"https://www.bundesbank.de/…","countries":["DE"],"refresh_days":92,"fetched_at":"2026-09-24T07:58:12+00:00","published_at":"2026-09-07","records":3505,"stale":false}}}

GET/v1/coverage

Per country: number of bank codes and branches, share of bank codes with a BIC (bic_pct), share with SEPA schemes (sepa_pct, null outside SEPA) and the source ids used.

GET/v1/plans

Current plans with price in cents, currency, billing interval and monthly quota.

GET/demo/iban/{iban}

Same response as /v1/iban, without a key, limited to 10 requests a minute per IP address. It exists for trying the API on the homepage; don't build on it.

Errors

Errors other than an invalid IBAN have a JSON body with an error message.

Status	When	Body
`400`	Malformed input, such as a BIC that isn't 8 or 11 characters.	`{"error": "BIC must be 8 or 11 characters"}`
`401`	Missing, malformed, rotated or revoked API key.	`{"error": "missing or invalid API key"}`
`402`	The subscription isn't active, for example after a failed payment.	`{"error": "…"}`
`404`	Unknown BIC or bank code. An IBAN lookup never returns 404: an unknown bank gives `200` with `"bank": null`.	`{"error": "unknown BIC"}`
`422`	Invalid IBAN.	The full IBAN response with `"valid": false` and `errors`.
`429`	Monthly quota used up, or demo rate limit reached.	`{"error": "monthly quota exceeded", "quota": 10000, "used": 10000}`

Quotas and limits

Each plan has a monthly lookup quota. Successful lookups and lookups that return 404 or 422 count toward it.
When the quota is used up, paid endpoints return 429 until the next billing month, or until you upgrade from the billing portal.
Check usage any time with GET /v1/account. Account calls don't count toward the quota.
The demo endpoint allows 10 requests a minute per IP address.

Account

Manage your key and subscription with the key itself.

GET/v1/accountAPI key

{"plan":"pro","monthly_quota":100000,"used_this_month":18234,"status":"active"}

POST/v1/account/rotateAPI key

Issues a new key and disables the one used for the call. The new key is returned once.

{"api_key":"<new key>"}

Deploy the new key before your next request: the old key returns 401 as soon as this call succeeds.

POST/v1/account/portalAPI key

Returns a short-lived link to the Stripe billing portal, where you can download invoices, change plan, update your card or cancel.

curl -X POST -H "Authorization: Bearer $IBANDB_KEY" \
  https://iban.trekle.space/v1/account/portal
{"url": "https://billing.stripe.com/p/session/…"}

Data terms

Your subscription lets you use lookup results in your own products and processes. The underlying data comes from third-party publishers and stays under their terms. SEPA scheme data is reused from the European Payments Council (Source: European Payments Council); GLEIF data is CC0; the IBAN structure comes from the SWIFT IBAN Registry. Some national registers and the EPC restrict commercial redistribution of their datasets, so don't republish or resell the data in bulk. See the terms and the list of publishers in the footer.