ibanforge

{'type': 'object', '$schema': 'http://json-schema.org/draft-07/schema#', 'required': ['ibans'], 'properties': {'ibans': {'type': 'array', 'items': {'type': 'string'}, 'maxItems': 100, 'minItems': 1, 'description': 'Array of IBANs (1-100)'}}}

{'type': 'object', '$schema': 'http://json-schema.org/draft-07/schema#', 'required': ['results', 'count'], 'properties': {'count': {'type': 'number', 'description': 'Number of IBANs processed.'}, 'results': {'type': 'array', 'items': {'type': 'object', 'required': ['iban', 'valid', 'cost_usdc'], 'properties': {'bic': {'anyOf': [{'type': 'object', 'required': ['code', 'bank_name', 'city'], 'properties': {'lei': {'type': ['string', 'null'], 'description': 'GLEIF identity of the resolved BIC holder, not necessarily the bank-code holder.'}, 'bic8': {'type': 'string', 'description': 'The eight characters of the institution â\x80\x94 the field to compare a supplied BIC against. code is served as the consulted source publishes it, so it is 8 or 11 characters; this one never moves. The branch code (last three characters) is informational: in a cooperative network it names the LOCAL bank and the first eight its clearing institution.'}, 'city': {'type': ['string', 'null']}, 'code': {'type': 'string'}, 'as_of': {'type': ['string', 'null']}, 'basis': {'type': 'string', 'description': 'Where the bank code to BIC pairing came from, and therefore what may be done with the BIC. national_register (the country register publishes this BIC for this bank code â\x80\x94 today DE, AT, BE, SK, CZ, BG, CH, LI and SM; settlement-grade) | curated_map (our maintained bank-code map, exact key, usually right and not an allocation record) | directory_prefix (the bic8 LIKE fallback, which can match several institutions â\x80\x94 read bank_code_check.candidates). Outside a national_register basis the BIC is ADVISORY: confirm it with the beneficiary or the bank before storing it as a routing instruction.'}, 'source': {'type': ['string', 'null'], 'description': 'Source of the bank-code/BIC pairing; keep its provenance.'}, 'address': {'anyOf': [{'type': 'object', 'required': ['type', 'street', 'post_code', 'region', 'city', 'country', 'romanized', 'romanization', 'source', 'language', 'as_of'], 'properties': {'city': {'type': ['string', 'null']}, 'type': {'type': 'string', 'const': 'registered'}, 'as_of': {'type': ['string', 'null']}, 'region': {'type': ['string', 'null']}, 'source': {'type': 'string'}, 'street': {'type': ['string', 'null']}, 'country': {'type': 'string'}, 'language': {'type': ['string', 'null']}, 'post_code': {'type': ['string', 'null']}, 'romanized': {'type': ['string', 'null']}, 'romanization': {'enum': ['original_latin', 'gleif_english', 'unavailable'], 'type': 'string'}}, 'additionalProperties': False}, {'type': 'null'}]}, 'bank_name': {'type': ['string', 'null']}, 'lei_status': {'type': ['string', 'null']}, 'source_as_of': {'type': 'string', 'description': "Year-month the source DATA is from, present ONLY when it differs from as_of. On a curated_map or directory_prefix answer it dates the directory row that supplied the name, the city, the LEI or the address when that row comes from a frozen public copy; never present on a national_register answer, whose name comes from the register and is dated by as_of. Absent means no gap has been established, never 'this is current'."}, 'authoritative': {'type': 'boolean', 'description': 'Whether this BIC may be stored and settled against. Derived from basis, so the two cannot disagree. NOT bank_code_check.authoritative, which answers a different question â\x80\x94 whether a national register was consulted about the BANK CODE. San Marino is where the two part: the pairing is the supervisorâ\x80\x99s, the code space is not its to settle.'}, 'postal_address': {'anyOf': [{'type': 'object', 'required': ['twn_nm', 'ctry', 'format', 'source', 'as_of'], 'properties': {'ctry': {'type': 'string'}, 'as_of': {'type': ['string', 'null']}, 'format': {'enum': ['structured', 'hybrid'], 'type': 'string'}, 'pst_cd': {'type': 'string'}, 'source': {'type': 'string'}, 'twn_nm': {'type': 'string'}, 'bldg_nb': {'type': 'string'}, 'strt_nm': {'type': 'string'}, 'adr_line': {'type': 'array', 'items': {'type': 'string'}}}, 'additionalProperties': False}, {'type': 'null'}]}, 'redirected_from': {'type': 'string', 'description': 'The bank code asked about, when the register answered for the one that took over its clearing (CH/LI only today: SIX marks an IID concatenated and publishes its successor). The IBAN stays valid â\x80\x94 a redirect is not a retirement.'}, 'listed_in_current_source': {'type': ['boolean', 'null'], 'description': 'Whether this BIC8 still appears in a list refreshed this cycle: GLEIF, the directory sources that carry no vintage, a national register, the EPC scheme registers. true when one of them carries it; null when it was not found in what could be read in full (never false by default). false is reserved for an index built from every list read in full, which is not the case today: the EBA STEP2 and NBP lists are only read through our deduplicated directory, so this field answers true or null. It does NOT prove the bank still exists under this name: a clearing list can keep the name of a bank that was absorbed.'}}, 'additionalProperties': False}, {'type': 'null'}]}, 'bban': {'type': 'object', 'required': ['bank_code', 'account_number'], 'properties': {'bank_code': {'type': 'string'}, 'branch_code': {'type': 'string'}, 'account_number': {'type': 'string'}}, 'additionalProperties': False}, 'iban': {'type': 'string', 'description': 'Normalized IBAN (uppercase, no spaces).'}, 'sepa': {'type': 'object', 'required': ['member', 'schemes', 'vop_required'], 'properties': {'basis': {'enum': ['country_default', 'epc_register'], 'type': 'string', 'description': 'Where `schemes` came from: read at the EPC register for this bank, or defaulted from the country.'}, 'member': {'type': 'boolean'}, 'schemes': {'type': 'array', 'items': {'type': 'string'}}, 'bank_schemes': {'anyOf': [{'type': 'array', 'items': {'type': 'string'}}, {'type': 'null'}], 'description': "The bank's own schemes from the EPC registers when bank_reachability is listed; [] for an unallocated bank code; null otherwise."}, 'vop_required': {'type': 'boolean'}, 'vop_participant': {'type': ['boolean', 'null'], 'description': 'true = resolved bank is listed as ready in the EPC VoP scheme register; null = no institution resolved, or the VoP register is not loaded (not consulted); a resolved bank outside the SEPA area is answered false from the country either way.'}, 'bank_reachability': {'type': ['string', 'null'], 'description': 'listed | not_listed | no_bank | bank_code_not_allocated, or null. Whether the EPC scheme registers list the resolved BANK, never borrowed from the country (member, schemes and basis still describe the country and are unchanged). listed: the bank has rows in the SCT, SCT Inst or SDD register. not_listed: it has none (an absence from the register is not an exclusion from the scheme). no_bank: no BIC resolved for this bank code, so no bank could be looked up in the EPC registers (a register may still name the holder: see bank_code_holder and bank_code_check). bank_code_not_allocated: the national register says nobody holds the bank code. null: the registers are not loaded on this deployment, or no bank was resolved because the bank-code check itself is unavailable (not consulted, never read as not_listed or no_bank). Absent outside SEPA.'}, 'vop_register_status': {'type': ['string', 'null'], 'description': "active | pending | inactive | not_listed, or null. The bank's status in the EPC Verification of Payee register: active (the same as vop_participant true), pending, inactive, or not_listed when the register has no row for it; null when no BIC resolved or the register was not consulted (screened false). Outside the SEPA area the country answers instead of the register (not_listed on POST /v1/iban/compliance) whether or not the register is loaded; the validation carries no sepa.vop_register_status there. It says whether the payee's bank answers VoP requests; IBANforge never runs the name check itself."}}, 'additionalProperties': False}, 'error': {'type': 'string'}, 'valid': {'type': 'boolean'}, 'checks': {'type': 'object', 'required': ['iban_structure', 'iban_checksum', 'bank_code', 'bic', 'sepa_reachability', 'national_check_digits', 'account_exists', 'payee_name', 'institution_sanctions', 'country_sanctions', 'payee_sanctions'], 'properties': {'bic': {'type': 'string', 'description': 'pass | fail | inferred | unknown | not_checked | not_applicable'}, 'bank_code': {'type': 'string', 'description': 'pass | fail | inferred | unknown | not_checked | not_applicable'}, 'payee_name': {'type': 'string', 'description': 'pass | fail | inferred | unknown | not_checked | not_applicable'}, 'iban_checksum': {'type': 'string', 'description': 'pass | fail | inferred | unknown | not_checked | not_applicable'}, 'account_exists': {'type': 'string', 'description': 'pass | fail | inferred | unknown | not_checked | not_applicable'}, 'iban_structure': {'type': 'string', 'description': 'pass | fail | inferred | unknown | not_checked | not_applicable'}, 'payee_sanctions': {'type': 'string', 'description': 'pass | fail | inferred | unknown | not_checked | not_applicable'}, 'country_sanctions': {'type': 'string', 'description': 'pass | fail | inferred | unknown | not_checked | not_applicable'}, 'sepa_reachability': {'type': 'string', 'description': 'pass | fail | inferred | unknown | not_checked | not_applicable'}, 'institution_sanctions': {'type': 'string', 'description': 'pass | fail | inferred | unknown | not_checked | not_applicable'}, 'national_check_digits': {'type': 'string', 'description': 'pass | fail | inferred | unknown | not_checked | not_applicable'}}, 'description': "One status per check: pass (checked against a source that settles it), fail (checked, and wrong), inferred (answered from a source that does not settle it), unknown (attempted, no conclusion), not_checked (IBANforge does not make this check here), not_applicable (the check has no object for this IBAN). payee_name: never checked here; the name check is made by the payee's bank through Verification of Payee (VoP), and sepa.vop_register_status says whether that bank answers VoP requests. account_exists: never checked here; only the payee's bank knows whether the account is open. payee_sanctions: never checked; the sanctions screen of POST /v1/iban/compliance is made on the payee's bank (BIC8) and country only. institution_sanctions and country_sanctions are filled by POST /v1/iban/compliance and not_checked on a validation. national_check_digits: the check key a country keeps inside the BBAN, a second check independent of mod-97. Checked for FR and MC (RIB key), BE (the last two digits, modulo 97), IT and SM (CIN) and ES (DC), with the proof in the national_check_digits block, and for GB (Vocalink modulus), with the proof in modulus_check; not_checked elsewhere (the German account-number methods are not checked yet). pass means the account number is well formed, never that the account exists; fail means it cannot have been issued as written, and valid stays true. A key may be added later; a key is never removed. Present only when valid is true.", 'additionalProperties': False}, 'issuer': {'type': 'object', 'required': ['type', 'name', 'classification'], 'properties': {'name': {'type': 'string'}, 'type': {'type': ['string', 'null'], 'description': 'bank | digital_bank | emi | payment_institution; null when unsubstantiated'}, 'iban_issuer': {'enum': ['confirmed', 'not_listed'], 'type': 'string'}, 'classification': {'type': 'string', 'description': 'curated | register | default. Whether the type was established or assumed. curated = the BIC8 is in the issuer set, so this is an identification. register = an official register names the holder of this bank code and says what it is; it carries a date and an authority in psd_registration, and it only ever replaces a default. default = nothing is on file and "bank" is the fallback, which covers 97.9% of BIC8 (measured 29/07/2026). Count curated and register when sizing virtual-IBAN exposure, never default.'}}, 'additionalProperties': False}, 'country': {'type': 'object', 'required': ['code', 'name'], 'properties': {'code': {'type': 'string', 'description': 'ISO 3166-1 alpha-2 country code.'}, 'name': {'type': 'string'}}, 'additionalProperties': False}, 'clearing': {'anyOf': [{'type': 'object', 'required': ['iid', 'name', 'type', 'town', 'sic', 'instant_payments_chf', 'eurosic', 'qr_iid', 'qr_iid_source'], 'properties': {'iid': {'type': 'string'}, 'sic': {'type': 'boolean'}, 'name': {'type': 'string'}, 'town': {'type': ['string', 'null']}, 'type': {'type': 'string'}, 'qr_iid': {'type': ['string', 'null']}, 'eurosic': {'type': 'boolean'}, 'qr_iids': {'type': 'array', 'items': {'type': 'string'}}, 'is_qr_iid': {'type': 'boolean'}, 'qr_iid_source': {'anyOf': [{'enum': ['register', 'headquarters'], 'type': 'string'}, {'type': 'null'}]}, 'instant_payments_chf': {'type': 'boolean'}}, 'additionalProperties': False}, {'type': 'null'}], 'description': 'Swiss clearing data when country is CH or LI.'}, 'cost_usdc': {'type': 'number', 'description': 'What THIS call was billed. Zero on the free MCP tier.'}, 'formatted': {'type': 'string', 'description': 'IBAN with 4-char groups for display.'}, 'next_steps': {'type': 'array', 'items': {'type': 'object', 'required': ['code', 'do', 'because'], 'properties': {'do': {'type': 'string'}, 'code': {'type': 'string', 'description': 'Stable identifier. Branch on this.'}, 'action': {'type': 'string', 'description': 'An IBANforge call that performs the step, when one exists.'}, 'because': {'type': 'string', 'description': 'The response field that produced this step.'}}, 'additionalProperties': False}, 'description': 'Ordered advice derived from THIS result: what blocks a payment first, what merely enriches it after. Branch on `code`, never on the prose. `because` names the field that produced the step so the advice is auditable. Empty for an IBAN that failed validation.'}, 'check_digits': {'type': 'string'}, 'error_detail': {'type': 'string'}, 'modulus_check': {'type': 'object', 'required': ['checked', 'passed', 'source', 'table_fetched_on'], 'properties': {'passed': {'type': ['boolean', 'null']}, 'source': {'type': 'string'}, 'checked': {'type': 'boolean'}, 'table_fetched_on': {'type': 'string'}}, 'additionalProperties': False}, 'processing_ms': {'type': 'number'}, 'bank_code_check': {'type': 'object', 'required': ['value', 'status', 'match', 'register', 'authoritative', 'as_of'], 'properties': {'as_of': {'type': 'string'}, 'match': {'type': ['string', 'null'], 'description': 'register (exact key) | prefix (bic8 LIKE heuristic) | null'}, 'value': {'type': 'string'}, 'reason': {'type': 'string', 'description': 'WHY the verdict is not verified, as one token to branch on. Absent when status is verified. not_allocated (a national register denies the code â\x80\x94 the only value that licenses "do not send") | absent_from_reference_data (our composite map does not carry it; the country register was not consulted) | no_reference_data_for_country | register_names_no_holder (the register defines the code space and publishes no holder â\x80\x94 silence, not a denial) | national_register_unavailable (the register this country is normally decided against could not be consulted) | lookup_failed (the lookup could not run: timeout, unreadable database). The last two describe IBANforge, never the beneficiary. Never escalate either into a refusal.'}, 'status': {'type': 'string', 'description': 'verified | not_in_register | unavailable. A separate verdict on the bank code, so bic:null stops meaning three different things.'}, 'retired': {'type': 'boolean', 'description': 'True when a register says the code is leaving (DE, authoritative) or has been struck off (IT, authoritative false, with retired_on). Still a verified result: it WAS allocated. Never a refusal.'}, 'register': {'type': ['string', 'null']}, 'candidates': {'type': 'number', 'description': 'BIC8 the prefix matched; >1 means the BIC may belong to another institution.'}, 'retired_on': {'type': 'string', 'description': 'YYYY-MM-DD, with retired where the register dates it (IT): the last day it lists this code for its last holder.'}, 'check_digit': {'type': 'object', 'required': ['valid', 'algorithm'], 'properties': {'valid': {'type': 'boolean'}, 'algorithm': {'type': 'string'}}, 'additionalProperties': False}, 'institution': {'type': 'object', 'required': ['name', 'street', 'post_code', 'town', 'country'], 'properties': {'lei': {'type': ['string', 'null']}, 'name': {'type': 'string'}, 'town': {'type': ['string', 'null']}, 'street': {'type': ['string', 'null']}, 'country': {'type': 'string'}, 'post_code': {'type': ['string', 'null']}}, 'additionalProperties': False}, 'authoritative': {'type': 'boolean', 'description': 'True only where the reference set is the national register (CH, LI, DE). Only then does not_in_register mean the code is not allocated.'}, 'superseded_by': {'type': 'string', 'description': 'The bank code that takes over. DE: the successor the register designates, re-paper against it. IT: the legal successor by merger or incorporation, not necessarily the bank now holding the account.'}}, 'additionalProperties': False}, 'list_price_usdc': {'type': 'number', 'description': 'Catalogue price of the same call on the paid REST/x402 route.'}, 'risk_indicators': {'type': 'object', 'required': ['issuer_type', 'country_risk', 'test_bic', 'sepa_reachable', 'sepa_reachable_scope', 'vop_coverage'], 'properties': {'test_bic': {'type': 'boolean'}, 'issuer_type': {'type': ['string', 'null'], 'description': 'Null when no institution resolved â\x80\x94 it no longer defaults to "bank".'}, 'country_risk': {'type': 'string'}, 'vop_coverage': {'type': 'boolean'}, 'sepa_reachable': {'type': 'boolean'}, 'sepa_reachable_scope': {'type': 'string', 'description': 'Scope the reachability holds at. Country-derived, not account-derived.'}}, 'additionalProperties': False}, 'bank_code_holder': {'type': 'string', 'description': 'confirmed | inferred | not_allocated | unknown. Who holds the bank code. confirmed: a register that publishes holders names the holder of this code (a national register that settles the code space, or a partial register on a hit). inferred: we name a holder from a source that cannot settle it (our composite map, the prefix fallback, a published structural rule), so read it as our inference. not_allocated: the national register says nobody holds this code, so do not send. unknown: no conclusion. valid stays true in all four: it only means the IBAN is well formed. bank_code_check.status verified means resolved; this field says whether a source settles it.'}, 'psd_registration': {'type': 'object', 'required': ['registered', 'entity_type', 'name', 'country', 'competent_authority', 'source', 'as_of'], 'properties': {'name': {'type': 'string'}, 'as_of': {'type': 'string'}, 'source': {'type': 'string'}, 'country': {'type': 'string'}, 'registered': {'type': 'boolean', 'const': True}, 'entity_type': {'type': 'string'}, 'competent_authority': {'type': 'string'}}, 'additionalProperties': False}, 'official_identity': {'type': 'object', 'required': ['name', 'lei', 'address', 'category', 'matched_by', 'source', 'free_of_charge', 'as_of', 'authoritative'], 'properties': {'lei': {'type': ['string', 'null']}, 'name': {'type': 'string', 'description': "The institution's name as the publisher writes it."}, 'as_of': {'type': 'string', 'description': 'Date of the list this row came from. Both lists are republished every business day.'}, 'source': {'type': 'string', 'description': 'The publisher, cited as their licence requires. Relay it.'}, 'address': {'type': ['string', 'null'], 'description': 'One-line registered address as published.'}, 'category': {'type': 'string'}, 'matched_by': {'type': 'string', 'description': 'lei | national_code'}, 'attribution': {'type': 'string', 'description': 'The Banco de Espana citation formula, verbatim. Spanish blocks only.'}, 'authoritative': {'type': 'boolean', 'description': 'Always false. Neither publisher allocates bank codes.'}, 'free_of_charge': {'type': 'string', 'description': 'Both publishers require buyers to be told, on every access, that the data is available free of charge from their own website. Relay it with the answer; do not strip it.'}}, 'description': 'Who a central bank says holds the resolved code (ECB by LEI and for FR bank codes, Banco de Espana for ES). Present only on a match â\x80\x94 absence is not a negative. INFORMATIONAL ONLY: it never changes valid or bank_code_check, because both publishers relay rather than allocate.', 'additionalProperties': False}, 'pra_authorisation': {'type': 'object', 'required': ['authorised', 'firm_name', 'frn', 'section', 'basis', 'source', 'list_month'], 'properties': {'frn': {'type': 'string'}, 'basis': {'type': 'string'}, 'source': {'type': 'string'}, 'section': {'type': 'string'}, 'firm_name': {'type': 'string'}, 'authorised': {'type': 'boolean', 'const': True}, 'list_month': {'type': 'string'}}, 'additionalProperties': False}, 'national_check_digits': {'type': 'object', 'required': ['country', 'scheme', 'status'], 'properties': {'detail': {'type': 'string', 'description': 'Present on fail and not_applicable only.'}, 'scheme': {'type': 'string', 'description': 'fr_rib_key | be_mod97 | it_cin | es_dc'}, 'status': {'type': 'string', 'description': 'pass | fail | not_applicable'}, 'country': {'type': 'string', 'description': 'The IBAN country (MC stays MC, SM stays SM).'}}, 'description': 'The check key a country keeps inside the BBAN, recomputed from the IBAN alone. Present only on a valid IBAN of FR, MC, BE, IT, SM or ES (GB has modulus_check instead); absent elsewhere, where checks.national_check_digits is not_checked. country is the IBAN country. scheme names the algorithm: fr_rib_key (FR and MC: the RIB key, the last two digits of the BBAN, over the bank code, branch code and account number), be_mod97 (BE: the last two digits, the first ten digits modulo 97, or 97 when the remainder is 0), it_cin (IT and SM: the CIN, the control letter at the start of the BBAN, over the ABI, CAB and account number), es_dc (ES: the two DC digits, positions 9 and 10 of the BBAN). status: pass (the key matches, so the account number is well formed; it does not prove the account exists or is open) or fail (the key does not match: this account number cannot have been issued as written, a typo or a made-up number). A fail never makes valid false, because the IBAN check digits are right: read the two separately, and confirm the details with the beneficiary before paying. not_applicable is reserved for a BBAN without the national layout, which a valid IBAN never has. detail, present on fail and not_applicable only, says which digits disagree; it never gives the expected key. checks.national_check_digits repeats status.', 'additionalProperties': False}}, 'additionalProperties': False}, 'description': 'One result per input IBAN, in the same order. Same shape as validate_iban.'}}, 'additionalProperties': False}

{'type': 'object', '$schema': 'http://json-schema.org/draft-07/schema#', 'required': ['iban'], 'properties': {'iban': {'type': 'string', 'description': 'IBAN to check'}}}

{'type': 'object', '$schema': 'http://json-schema.org/draft-07/schema#', 'required': ['iban', 'valid', 'cost_usdc', 'compliance', 'meta'], 'properties': {'bic': {'anyOf': [{'type': 'object', 'required': ['code', 'bank_name', 'city'], 'properties': {'lei': {'type': ['string', 'null'], 'description': 'GLEIF identity of the resolved BIC holder, not necessarily the bank-code holder.'}, 'bic8': {'type': 'string', 'description': 'The eight characters of the institution â\x80\x94 the field to compare a supplied BIC against. code is served as the consulted source publishes it, so it is 8 or 11 characters; this one never moves. The branch code (last three characters) is informational: in a cooperative network it names the LOCAL bank and the first eight its clearing institution.'}, 'city': {'type': ['string', 'null']}, 'code': {'type': 'string'}, 'as_of': {'type': ['string', 'null']}, 'basis': {'type': 'string', 'description': 'Where the bank code to BIC pairing came from, and therefore what may be done with the BIC. national_register (the country register publishes this BIC for this bank code â\x80\x94 today DE, AT, BE, SK, CZ, BG, CH, LI and SM; settlement-grade) | curated_map (our maintained bank-code map, exact key, usually right and not an allocation record) | directory_prefix (the bic8 LIKE fallback, which can match several institutions â\x80\x94 read bank_code_check.candidates). Outside a national_register basis the BIC is ADVISORY: confirm it with the beneficiary or the bank before storing it as a routing instruction.'}, 'source': {'type': ['string', 'null'], 'description': 'Source of the bank-code/BIC pairing; keep its provenance.'}, 'address': {'anyOf': [{'type': 'object', 'required': ['type', 'street', 'post_code', 'region', 'city', 'country', 'romanized', 'romanization', 'source', 'language', 'as_of'], 'properties': {'city': {'type': ['string', 'null']}, 'type': {'type': 'string', 'const': 'registered'}, 'as_of': {'type': ['string', 'null']}, 'region': {'type': ['string', 'null']}, 'source': {'type': 'string'}, 'street': {'type': ['string', 'null']}, 'country': {'type': 'string'}, 'language': {'type': ['string', 'null']}, 'post_code': {'type': ['string', 'null']}, 'romanized': {'type': ['string', 'null']}, 'romanization': {'enum': ['original_latin', 'gleif_english', 'unavailable'], 'type': 'string'}}, 'additionalProperties': False}, {'type': 'null'}]}, 'bank_name': {'type': ['string', 'null']}, 'lei_status': {'type': ['string', 'null']}, 'source_as_of': {'type': 'string', 'description': "Year-month the source DATA is from, present ONLY when it differs from as_of. On a curated_map or directory_prefix answer it dates the directory row that supplied the name, the city, the LEI or the address when that row comes from a frozen public copy; never present on a national_register answer, whose name comes from the register and is dated by as_of. Absent means no gap has been established, never 'this is current'."}, 'authoritative': {'type': 'boolean', 'description': 'Whether this BIC may be stored and settled against. Derived from basis, so the two cannot disagree. NOT bank_code_check.authoritative, which answers a different question â\x80\x94 whether a national register was consulted about the BANK CODE. San Marino is where the two part: the pairing is the supervisorâ\x80\x99s, the code space is not its to settle.'}, 'postal_address': {'anyOf': [{'type': 'object', 'required': ['twn_nm', 'ctry', 'format', 'source', 'as_of'], 'properties': {'ctry': {'type': 'string'}, 'as_of': {'type': ['string', 'null']}, 'format': {'enum': ['structured', 'hybrid'], 'type': 'string'}, 'pst_cd': {'type': 'string'}, 'source': {'type': 'string'}, 'twn_nm': {'type': 'string'}, 'bldg_nb': {'type': 'string'}, 'strt_nm': {'type': 'string'}, 'adr_line': {'type': 'array', 'items': {'type': 'string'}}}, 'additionalProperties': False}, {'type': 'null'}]}, 'redirected_from': {'type': 'string', 'description': 'The bank code asked about, when the register answered for the one that took over its clearing (CH/LI only today: SIX marks an IID concatenated and publishes its successor). The IBAN stays valid â\x80\x94 a redirect is not a retirement.'}, 'listed_in_current_source': {'type': ['boolean', 'null'], 'description': 'Whether this BIC8 still appears in a list refreshed this cycle: GLEIF, the directory sources that carry no vintage, a national register, the EPC scheme registers. true when one of them carries it; null when it was not found in what could be read in full (never false by default). false is reserved for an index built from every list read in full, which is not the case today: the EBA STEP2 and NBP lists are only read through our deduplicated directory, so this field answers true or null. It does NOT prove the bank still exists under this name: a clearing list can keep the name of a bank that was absorbed.'}}, 'additionalProperties': False}, {'type': 'null'}]}, 'bban': {'type': 'object', 'required': ['bank_code', 'account_number'], 'properties': {'bank_code': {'type': 'string'}, 'branch_code': {'type': 'string'}, 'account_number': {'type': 'string'}}, 'additionalProperties': False}, 'iban': {'type': 'string', 'description': 'Normalized IBAN (uppercase, no spaces).'}, 'meta': {'type': 'object', 'required': ['scope', 'disclaimer'], 'properties': {'scope': {'type': 'string'}, 'sources': {'type': ['string', 'null']}, 'disclaimer': {'type': 'string'}, 'fatf_as_of': {'type': ['string', 'null']}, 'sanctions_as_of': {'type': ['string', 'null']}}, 'additionalProperties': {}}, 'sepa': {'type': 'object', 'required': ['member', 'schemes', 'vop_required'], 'properties': {'basis': {'enum': ['country_default', 'epc_register'], 'type': 'string', 'description': 'Where `schemes` came from: read at the EPC register for this bank, or defaulted from the country.'}, 'member': {'type': 'boolean'}, 'schemes': {'type': 'array', 'items': {'type': 'string'}}, 'bank_schemes': {'anyOf': [{'type': 'array', 'items': {'type': 'string'}}, {'type': 'null'}], 'description': "The bank's own schemes from the EPC registers when bank_reachability is listed; [] for an unallocated bank code; null otherwise."}, 'vop_required': {'type': 'boolean'}, 'vop_participant': {'type': ['boolean', 'null'], 'description': 'true = resolved bank is listed as ready in the EPC VoP scheme register; null = no institution resolved, or the VoP register is not loaded (not consulted); a resolved bank outside the SEPA area is answered false from the country either way.'}, 'bank_reachability': {'type': ['string', 'null'], 'description': 'listed | not_listed | no_bank | bank_code_not_allocated, or null. Whether the EPC scheme registers list the resolved BANK, never borrowed from the country (member, schemes and basis still describe the country and are unchanged). listed: the bank has rows in the SCT, SCT Inst or SDD register. not_listed: it has none (an absence from the register is not an exclusion from the scheme). no_bank: no BIC resolved for this bank code, so no bank could be looked up in the EPC registers (a register may still name the holder: see bank_code_holder and bank_code_check). bank_code_not_allocated: the national register says nobody holds the bank code. null: the registers are not loaded on this deployment, or no bank was resolved because the bank-code check itself is unavailable (not consulted, never read as not_listed or no_bank). Absent outside SEPA.'}, 'vop_register_status': {'type': ['string', 'null'], 'description': "active | pending | inactive | not_listed, or null. The bank's status in the EPC Verification of Payee register: active (the same as vop_participant true), pending, inactive, or not_listed when the register has no row for it; null when no BIC resolved or the register was not consulted (screened false). Outside the SEPA area the country answers instead of the register (not_listed on POST /v1/iban/compliance) whether or not the register is loaded; the validation carries no sepa.vop_register_status there. It says whether the payee's bank answers VoP requests; IBANforge never runs the name check itself."}}, 'additionalProperties': False}, 'error': {'type': 'string'}, 'valid': {'type': 'boolean'}, 'checks': {'type': 'object', 'required': ['iban_structure', 'iban_checksum', 'bank_code', 'bic', 'sepa_reachability', 'national_check_digits', 'account_exists', 'payee_name', 'institution_sanctions', 'country_sanctions', 'payee_sanctions'], 'properties': {'bic': {'type': 'string', 'description': 'pass | fail | inferred | unknown | not_checked | not_applicable'}, 'bank_code': {'type': 'string', 'description': 'pass | fail | inferred | unknown | not_checked | not_applicable'}, 'payee_name': {'type': 'string', 'description': 'pass | fail | inferred | unknown | not_checked | not_applicable'}, 'iban_checksum': {'type': 'string', 'description': 'pass | fail | inferred | unknown | not_checked | not_applicable'}, 'account_exists': {'type': 'string', 'description': 'pass | fail | inferred | unknown | not_checked | not_applicable'}, 'iban_structure': {'type': 'string', 'description': 'pass | fail | inferred | unknown | not_checked | not_applicable'}, 'payee_sanctions': {'type': 'string', 'description': 'pass | fail | inferred | unknown | not_checked | not_applicable'}, 'country_sanctions': {'type': 'string', 'description': 'pass | fail | inferred | unknown | not_checked | not_applicable'}, 'sepa_reachability': {'type': 'string', 'description': 'pass | fail | inferred | unknown | not_checked | not_applicable'}, 'institution_sanctions': {'type': 'string', 'description': 'pass | fail | inferred | unknown | not_checked | not_applicable'}, 'national_check_digits': {'type': 'string', 'description': 'pass | fail | inferred | unknown | not_checked | not_applicable'}}, 'description': "One status per check: pass (checked against a source that settles it), fail (checked, and wrong), inferred (answered from a source that does not settle it), unknown (attempted, no conclusion), not_checked (IBANforge does not make this check here), not_applicable (the check has no object for this IBAN). payee_name: never checked here; the name check is made by the payee's bank through Verification of Payee (VoP), and sepa.vop_register_status says whether that bank answers VoP requests. account_exists: never checked here; only the payee's bank knows whether the account is open. payee_sanctions: never checked; the sanctions screen of POST /v1/iban/compliance is made on the payee's bank (BIC8) and country only. institution_sanctions and country_sanctions are filled by POST /v1/iban/compliance and not_checked on a validation. national_check_digits: the check key a country keeps inside the BBAN, a second check independent of mod-97. Checked for FR and MC (RIB key), BE (the last two digits, modulo 97), IT and SM (CIN) and ES (DC), with the proof in the national_check_digits block, and for GB (Vocalink modulus), with the proof in modulus_check; not_checked elsewhere (the German account-number methods are not checked yet). pass means the account number is well formed, never that the account exists; fail means it cannot have been issued as written, and valid stays true. A key may be added later; a key is never removed. Present only when valid is true.", 'additionalProperties': False}, 'issuer': {'type': 'object', 'required': ['type', 'name', 'classification'], 'properties': {'name': {'type': 'string'}, 'type': {'type': ['string', 'null'], 'description': 'bank | digital_bank | emi | payment_institution; null when unsubstantiated'}, 'iban_issuer': {'enum': ['confirmed', 'not_listed'], 'type': 'string'}, 'classification': {'type': 'string', 'description': 'curated | register | default. Whether the type was established or assumed. curated = the BIC8 is in the issuer set, so this is an identification. register = an official register names the holder of this bank code and says what it is; it carries a date and an authority in psd_registration, and it only ever replaces a default. default = nothing is on file and "bank" is the fallback, which covers 97.9% of BIC8 (measured 29/07/2026). Count curated and register when sizing virtual-IBAN exposure, never default.'}}, 'additionalProperties': False}, 'country': {'type': 'object', 'required': ['code', 'name'], 'properties': {'code': {'type': 'string', 'description': 'ISO 3166-1 alpha-2 country code.'}, 'name': {'type': 'string'}}, 'additionalProperties': False}, 'clearing': {'anyOf': [{'type': 'object', 'required': ['iid', 'name', 'type', 'town', 'sic', 'instant_payments_chf', 'eurosic', 'qr_iid', 'qr_iid_source'], 'properties': {'iid': {'type': 'string'}, 'sic': {'type': 'boolean'}, 'name': {'type': 'string'}, 'town': {'type': ['string', 'null']}, 'type': {'type': 'string'}, 'qr_iid': {'type': ['string', 'null']}, 'eurosic': {'type': 'boolean'}, 'qr_iids': {'type': 'array', 'items': {'type': 'string'}}, 'is_qr_iid': {'type': 'boolean'}, 'qr_iid_source': {'anyOf': [{'enum': ['register', 'headquarters'], 'type': 'string'}, {'type': 'null'}]}, 'instant_payments_chf': {'type': 'boolean'}}, 'additionalProperties': False}, {'type': 'null'}], 'description': 'Swiss clearing data when country is CH or LI.'}, 'cost_usdc': {'type': 'number', 'description': 'What THIS call was billed. Zero on the free MCP tier.'}, 'formatted': {'type': 'string', 'description': 'IBAN with 4-char groups for display.'}, 'compliance': {'type': 'object', 'required': ['sanctions', 'reachability', 'vop', 'risk_score', 'risk_level', 'flags'], 'properties': {'vop': {'type': 'object', 'required': ['screened', 'participant', 'status'], 'properties': {'status': {'type': 'string'}, 'screened': {'type': 'boolean'}, 'participant': {'type': 'boolean'}, 'register_status': {'type': ['string', 'null'], 'description': "active | pending | inactive | not_listed, or null. The bank's status in the EPC Verification of Payee register: active (the same as vop_participant true), pending, inactive, or not_listed when the register has no row for it; null when no BIC resolved or the register was not consulted (screened false). Outside the SEPA area the country answers instead of the register (not_listed on POST /v1/iban/compliance) whether or not the register is loaded; the validation carries no sepa.vop_register_status there. It says whether the payee's bank answers VoP requests; IBANforge never runs the name check itself."}}, 'additionalProperties': False}, 'flags': {'type': 'array', 'items': {'type': 'string'}}, 'sanctions': {'type': 'object', 'required': ['bank_screened', 'country_sanctioned', 'bank_sanctioned', 'matched_lists', 'fatf_status'], 'properties': {'fatf_status': {'type': 'string'}, 'bank_screened': {'type': 'boolean', 'description': 'False means no bank was screened; do not interpret bank_sanctioned as a finding.'}, 'matched_lists': {'type': 'array', 'items': {'type': 'string'}}, 'payee_screened': {'type': 'boolean', 'description': 'Always false: the payee (account holder) is never screened here.'}, 'bank_sanctioned': {'type': 'boolean', 'description': 'False also when no bank was screened: read institution_listed.'}, 'country_sanctioned': {'type': 'boolean'}, 'institution_listed': {'type': ['boolean', 'null'], 'description': "Whether the payee's BANK is on a sanctions list: bank_sanctioned when a bank was screened against every list this service names, null otherwise (never false without a screen)."}}, 'additionalProperties': False}, 'risk_level': {'type': 'string', 'description': 'low | medium | elevated | high | critical | unassessable. unassessable means the IBAN itself did not validate, so no screening was possible: it is the absence of a verdict, never a favourable one.'}, 'risk_score': {'anyOf': [{'type': 'number', 'maximum': 100, 'minimum': 0}, {'type': 'null'}], 'description': '0 = safest, 100 = block. null when the IBAN could not be validated: there was nothing to score.'}, 'reachability': {'type': 'object', 'required': ['screened', 'sepa_instant', 'sct', 'sdd'], 'properties': {'sct': {'type': 'boolean'}, 'sdd': {'type': 'boolean'}, 'screened': {'type': 'boolean'}, 'sepa_instant': {'type': 'boolean'}, 'listed_in_epc_registers': {'type': ['boolean', 'null'], 'description': 'At least one of the three schemes lists the bank; null when the EPC registers were not consulted (screened false). Outside the SEPA area the country answers (false) whether or not the registers are loaded.'}}, 'additionalProperties': False}}, 'additionalProperties': False}, 'next_steps': {'type': 'array', 'items': {'type': 'object', 'required': ['code', 'do', 'because'], 'properties': {'do': {'type': 'string'}, 'code': {'type': 'string', 'description': 'Stable identifier. Branch on this.'}, 'action': {'type': 'string', 'description': 'An IBANforge call that performs the step, when one exists.'}, 'because': {'type': 'string', 'description': 'The response field that produced this step.'}}, 'additionalProperties': False}, 'description': 'Ordered advice derived from THIS result: what blocks a payment first, what merely enriches it after. Branch on `code`, never on the prose. `because` names the field that produced the step so the advice is auditable. Empty for an IBAN that failed validation.'}, 'check_digits': {'type': 'string'}, 'error_detail': {'type': 'string'}, 'modulus_check': {'type': 'object', 'required': ['checked', 'passed', 'source', 'table_fetched_on'], 'properties': {'passed': {'type': ['boolean', 'null']}, 'source': {'type': 'string'}, 'checked': {'type': 'boolean'}, 'table_fetched_on': {'type': 'string'}}, 'additionalProperties': False}, 'processing_ms': {'type': 'number'}, 'bank_code_check': {'type': 'object', 'required': ['value', 'status', 'match', 'register', 'authoritative', 'as_of'], 'properties': {'as_of': {'type': 'string'}, 'match': {'type': ['string', 'null'], 'description': 'register (exact key) | prefix (bic8 LIKE heuristic) | null'}, 'value': {'type': 'string'}, 'reason': {'type': 'string', 'description': 'WHY the verdict is not verified, as one token to branch on. Absent when status is verified. not_allocated (a national register denies the code â\x80\x94 the only value that licenses "do not send") | absent_from_reference_data (our composite map does not carry it; the country register was not consulted) | no_reference_data_for_country | register_names_no_holder (the register defines the code space and publishes no holder â\x80\x94 silence, not a denial) | national_register_unavailable (the register this country is normally decided against could not be consulted) | lookup_failed (the lookup could not run: timeout, unreadable database). The last two describe IBANforge, never the beneficiary. Never escalate either into a refusal.'}, 'status': {'type': 'string', 'description': 'verified | not_in_register | unavailable. A separate verdict on the bank code, so bic:null stops meaning three different things.'}, 'retired': {'type': 'boolean', 'description': 'True when a register says the code is leaving (DE, authoritative) or has been struck off (IT, authoritative false, with retired_on). Still a verified result: it WAS allocated. Never a refusal.'}, 'register': {'type': ['string', 'null']}, 'candidates': {'type': 'number', 'description': 'BIC8 the prefix matched; >1 means the BIC may belong to another institution.'}, 'retired_on': {'type': 'string', 'description': 'YYYY-MM-DD, with retired where the register dates it (IT): the last day it lists this code for its last holder.'}, 'check_digit': {'type': 'object', 'required': ['valid', 'algorithm'], 'properties': {'valid': {'type': 'boolean'}, 'algorithm': {'type': 'string'}}, 'additionalProperties': False}, 'institution': {'type': 'object', 'required': ['name', 'street', 'post_code', 'town', 'country'], 'properties': {'lei': {'type': ['string', 'null']}, 'name': {'type': 'string'}, 'town': {'type': ['string', 'null']}, 'street': {'type': ['string', 'null']}, 'country': {'type': 'string'}, 'post_code': {'type': ['string', 'null']}}, 'additionalProperties': False}, 'authoritative': {'type': 'boolean', 'description': 'True only where the reference set is the national register (CH, LI, DE). Only then does not_in_register mean the code is not allocated.'}, 'superseded_by': {'type': 'string', 'description': 'The bank code that takes over. DE: the successor the register designates, re-paper against it. IT: the legal successor by merger or incorporation, not necessarily the bank now holding the account.'}}, 'additionalProperties': False}, 'list_price_usdc': {'type': 'number', 'description': 'Catalogue price of the same call on the paid REST/x402 route.'}, 'risk_indicators': {'type': 'object', 'required': ['issuer_type', 'country_risk', 'test_bic', 'sepa_reachable', 'sepa_reachable_scope', 'vop_coverage'], 'properties': {'test_bic': {'type': 'boolean'}, 'issuer_type': {'type': ['string', 'null'], 'description': 'Null when no institution resolved â\x80\x94 it no longer defaults to "bank".'}, 'country_risk': {'type': 'string'}, 'vop_coverage': {'type': 'boolean'}, 'sepa_reachable': {'type': 'boolean'}, 'sepa_reachable_scope': {'type': 'string', 'description': 'Scope the reachability holds at. Country-derived, not account-derived.'}}, 'additionalProperties': False}, 'bank_code_holder': {'type': 'string', 'description': 'confirmed | inferred | not_allocated | unknown. Who holds the bank code. confirmed: a register that publishes holders names the holder of this code (a national register that settles the code space, or a partial register on a hit). inferred: we name a holder from a source that cannot settle it (our composite map, the prefix fallback, a published structural rule), so read it as our inference. not_allocated: the national register says nobody holds this code, so do not send. unknown: no conclusion. valid stays true in all four: it only means the IBAN is well formed. bank_code_check.status verified means resolved; this field says whether a source settles it.'}, 'psd_registration': {'type': 'object', 'required': ['registered', 'entity_type', 'name', 'country', 'competent_authority', 'source', 'as_of'], 'properties': {'name': {'type': 'string'}, 'as_of': {'type': 'string'}, 'source': {'type': 'string'}, 'country': {'type': 'string'}, 'registered': {'type': 'boolean', 'const': True}, 'entity_type': {'type': 'string'}, 'competent_authority': {'type': 'string'}}, 'additionalProperties': False}, 'official_identity': {'type': 'object', 'required': ['name', 'lei', 'address', 'category', 'matched_by', 'source', 'free_of_charge', 'as_of', 'authoritative'], 'properties': {'lei': {'type': ['string', 'null']}, 'name': {'type': 'string', 'description': "The institution's name as the publisher writes it."}, 'as_of': {'type': 'string', 'description': 'Date of the list this row came from. Both lists are republished every business day.'}, 'source': {'type': 'string', 'description': 'The publisher, cited as their licence requires. Relay it.'}, 'address': {'type': ['string', 'null'], 'description': 'One-line registered address as published.'}, 'category': {'type': 'string'}, 'matched_by': {'type': 'string', 'description': 'lei | national_code'}, 'attribution': {'type': 'string', 'description': 'The Banco de Espana citation formula, verbatim. Spanish blocks only.'}, 'authoritative': {'type': 'boolean', 'description': 'Always false. Neither publisher allocates bank codes.'}, 'free_of_charge': {'type': 'string', 'description': 'Both publishers require buyers to be told, on every access, that the data is available free of charge from their own website. Relay it with the answer; do not strip it.'}}, 'description': 'Who a central bank says holds the resolved code (ECB by LEI and for FR bank codes, Banco de Espana for ES). Present only on a match â\x80\x94 absence is not a negative. INFORMATIONAL ONLY: it never changes valid or bank_code_check, because both publishers relay rather than allocate.', 'additionalProperties': False}, 'pra_authorisation': {'type': 'object', 'required': ['authorised', 'firm_name', 'frn', 'section', 'basis', 'source', 'list_month'], 'properties': {'frn': {'type': 'string'}, 'basis': {'type': 'string'}, 'source': {'type': 'string'}, 'section': {'type': 'string'}, 'firm_name': {'type': 'string'}, 'authorised': {'type': 'boolean', 'const': True}, 'list_month': {'type': 'string'}}, 'additionalProperties': False}, 'national_check_digits': {'type': 'object', 'required': ['country', 'scheme', 'status'], 'properties': {'detail': {'type': 'string', 'description': 'Present on fail and not_applicable only.'}, 'scheme': {'type': 'string', 'description': 'fr_rib_key | be_mod97 | it_cin | es_dc'}, 'status': {'type': 'string', 'description': 'pass | fail | not_applicable'}, 'country': {'type': 'string', 'description': 'The IBAN country (MC stays MC, SM stays SM).'}}, 'description': 'The check key a country keeps inside the BBAN, recomputed from the IBAN alone. Present only on a valid IBAN of FR, MC, BE, IT, SM or ES (GB has modulus_check instead); absent elsewhere, where checks.national_check_digits is not_checked. country is the IBAN country. scheme names the algorithm: fr_rib_key (FR and MC: the RIB key, the last two digits of the BBAN, over the bank code, branch code and account number), be_mod97 (BE: the last two digits, the first ten digits modulo 97, or 97 when the remainder is 0), it_cin (IT and SM: the CIN, the control letter at the start of the BBAN, over the ABI, CAB and account number), es_dc (ES: the two DC digits, positions 9 and 10 of the BBAN). status: pass (the key matches, so the account number is well formed; it does not prove the account exists or is open) or fail (the key does not match: this account number cannot have been issued as written, a typo or a made-up number). A fail never makes valid false, because the IBAN check digits are right: read the two separately, and confirm the details with the beneficiary before paying. not_applicable is reserved for a BBAN without the national layout, which a valid IBAN never has. detail, present on fail and not_applicable only, says which digits disagree; it never gives the expected key. checks.national_check_digits repeats status.', 'additionalProperties': False}}, 'additionalProperties': False}

{'type': 'object', '$schema': 'http://json-schema.org/draft-07/schema#', 'required': ['scheme', 'address'], 'properties': {'scheme': {'enum': ['sps', 'hvps_plus', 'fedwire'], 'type': 'string', 'description': "Which rail's rules to check against: sps | hvps_plus | fedwire"}, 'address': {'type': 'object', 'properties': {'ctry': {'type': 'string', 'description': 'Ctry â\x80\x94 ISO 3166-1 alpha-2 country code'}, 'adr_tp': {'type': 'string', 'description': 'AdrTp â\x80\x94 address type (SPS forbids sending it)'}, 'pst_cd': {'type': 'string', 'description': 'PstCd â\x80\x94 postal code'}, 'twn_nm': {'type': 'string', 'description': 'TwnNm â\x80\x94 town name'}, 'bldg_nb': {'type': 'string', 'description': 'BldgNb â\x80\x94 building number'}, 'strt_nm': {'type': 'string', 'description': 'StrtNm â\x80\x94 street name'}, 'adr_line': {'type': 'array', 'items': {'type': 'string'}, 'description': 'AdrLine â\x80\x94 free-text lines of the hybrid address'}}, 'description': 'The ISO 20022 PostalAddress under test, in ISO tag vocabulary (snake_cased).', 'additionalProperties': False}}}

{'type': 'object', '$schema': 'http://json-schema.org/draft-07/schema#', 'required': ['scheme', 'conforms', 'findings', 'note'], 'properties': {'note': {'type': 'string', 'description': "Why 'cbpr+' is not on the menu. Served on every answer."}, 'scheme': {'type': 'string', 'description': 'sps | hvps_plus | fedwire â\x80\x94 the rule set that was applied.'}, 'conforms': {'type': 'boolean', 'description': 'True when no finding failed. not_applicable findings never count against it.'}, 'findings': {'type': 'array', 'items': {'type': 'object', 'required': ['rule', 'verdict', 'detail', 'source'], 'properties': {'rule': {'type': 'string', 'description': 'Stable identifier, safe to branch on.'}, 'detail': {'type': 'string', 'description': 'What was looked at and what was concluded.'}, 'source': {'type': 'string', 'description': 'The document the rule comes from, with its date. Relay it.'}, 'verdict': {'type': 'string', 'description': 'pass | fail | not_applicable'}}, 'additionalProperties': False}, 'description': 'One entry per rule of the scheme, in a stable order.'}}, 'additionalProperties': False}

{'type': 'object', '$schema': 'http://json-schema.org/draft-07/schema#', 'required': ['payload'], 'properties': {'payload': {'type': 'string', 'maxLength': 4000, 'minLength': 1, 'description': 'The Swiss QR Code text with real line breaks: SPC, 0200, 1, IBAN, creditor (7 lines), ultimate creditor (7 empty lines), amount, currency, ultimate debtor (7 lines), reference type, reference, message, EPD, optional billing information and alternative schemes.'}}}

{'type': 'object', '$schema': 'http://json-schema.org/draft-07/schema#', 'required': ['valid', 'ready_for_2026_11_14', 'qr_type', 'version', 'coding', 'creditor_iban', 'creditor', 'ultimate_creditor_empty', 'amount', 'currency', 'ultimate_debtor', 'reference', 'unstructured_message', 'trailer', 'billing_information', 'alternative_schemes', 'findings', 'next_steps', 'source'], 'properties': {'valid': {'type': 'boolean', 'description': 'True when no finding has severity error.'}, 'amount': {'type': ['string', 'null']}, 'coding': {'type': 'string'}, 'source': {'type': 'string'}, 'qr_type': {'type': 'string'}, 'trailer': {'type': 'string'}, 'version': {'type': 'string'}, 'creditor': {'type': 'object', 'required': ['present', 'address', 'structured', 'sps_check', 'proposed_structured'], 'properties': {'address': {'type': 'object', 'required': ['type', 'name', 'line1', 'line2', 'postal_code', 'town', 'country'], 'properties': {'name': {'type': 'string'}, 'town': {'type': 'string'}, 'type': {'type': 'string', 'description': 'AdrTp as carried: S (structured), K (combined) or empty.'}, 'line1': {'type': 'string', 'description': 'StrtNm for type S, AdrLine1 for type K.'}, 'line2': {'type': 'string', 'description': 'BldgNb for type S, AdrLine2 (postal code and town) for type K.'}, 'country': {'type': 'string'}, 'postal_code': {'type': 'string'}}, 'additionalProperties': False}, 'present': {'type': 'boolean'}, 'sps_check': {'anyOf': [{'type': 'object', 'required': ['scheme', 'conforms', 'findings', 'note'], 'properties': {'note': {'type': 'string'}, 'scheme': {'type': 'string'}, 'conforms': {'type': 'boolean'}, 'findings': {'type': 'array', 'items': {'type': 'object', 'required': ['rule', 'verdict', 'detail', 'source'], 'properties': {'rule': {'type': 'string'}, 'detail': {'type': 'string'}, 'source': {'type': 'string'}, 'verdict': {'type': 'string'}}, 'additionalProperties': False}}}, 'additionalProperties': False}, {'type': 'null'}], 'description': 'The SPS structured-address verdicts for a type S address; null otherwise.'}, 'structured': {'type': ['boolean', 'null'], 'description': 'true = type S, false = type K (combined), null = absent or invalid type.'}, 'proposed_structured': {'anyOf': [{'type': 'object', 'required': ['confidence', 'note'], 'properties': {'ctry': {'type': 'string'}, 'note': {'type': 'string'}, 'pst_cd': {'type': 'string'}, 'twn_nm': {'type': 'string'}, 'bldg_nb': {'type': 'string'}, 'strt_nm': {'type': 'string'}, 'confidence': {'type': 'string', 'description': 'high | low'}}, 'additionalProperties': False}, {'type': 'null'}], 'description': 'For a combined (K) address: the type S fields derived from the combined lines.'}}, 'additionalProperties': False}, 'currency': {'type': ['string', 'null']}, 'findings': {'type': 'array', 'items': {'type': 'object', 'required': ['code', 'severity', 'field', 'detail', 'source'], 'properties': {'code': {'type': 'string', 'description': 'Stable identifier, safe to branch on.'}, 'field': {'type': 'string'}, 'detail': {'type': 'string'}, 'source': {'type': 'string', 'description': 'The SIX document the rule comes from. Relay it.'}, 'severity': {'type': 'string', 'description': 'error | warning'}}, 'additionalProperties': False}}, 'reference': {'type': 'object', 'required': ['type', 'value', 'valid', 'note'], 'properties': {'note': {'type': 'string'}, 'type': {'type': 'string', 'description': 'QRR | SCOR | NON as carried.'}, 'valid': {'type': ['boolean', 'null']}, 'value': {'type': 'string'}}, 'additionalProperties': False}, 'next_steps': {'type': 'array', 'items': {'type': 'string'}}, 'creditor_iban': {'type': 'object', 'required': ['value', 'valid', 'country', 'qr_iban', 'iid'], 'properties': {'iid': {'type': ['string', 'null']}, 'valid': {'type': 'boolean'}, 'value': {'type': 'string'}, 'country': {'type': ['string', 'null']}, 'qr_iban': {'type': 'boolean', 'description': 'IID in 30000-31999, which requires reference type QRR.'}}, 'additionalProperties': False}, 'ultimate_debtor': {'type': 'object', 'required': ['present', 'address', 'structured', 'sps_check', 'proposed_structured'], 'properties': {'address': {'type': 'object', 'required': ['type', 'name', 'line1', 'line2', 'postal_code', 'town', 'country'], 'properties': {'name': {'type': 'string'}, 'town': {'type': 'string'}, 'type': {'type': 'string', 'description': 'AdrTp as carried: S (structured), K (combined) or empty.'}, 'line1': {'type': 'string', 'description': 'StrtNm for type S, AdrLine1 for type K.'}, 'line2': {'type': 'string', 'description': 'BldgNb for type S, AdrLine2 (postal code and town) for type K.'}, 'country': {'type': 'string'}, 'postal_code': {'type': 'string'}}, 'additionalProperties': False}, 'present': {'type': 'boolean'}, 'sps_check': {'anyOf': [{'type': 'object', 'required': ['scheme', 'conforms', 'findings', 'note'], 'properties': {'note': {'type': 'string'}, 'scheme': {'type': 'string'}, 'conforms': {'type': 'boolean'}, 'findings': {'type': 'array', 'items': {'type': 'object', 'required': ['rule', 'verdict', 'detail', 'source'], 'properties': {'rule': {'type': 'string'}, 'detail': {'type': 'string'}, 'source': {'type': 'string'}, 'verdict': {'type': 'string'}}, 'additionalProperties': False}}}, 'additionalProperties': False}, {'type': 'null'}], 'description': 'The SPS structured-address verdicts for a type S address; null otherwise.'}, 'structured': {'type': ['boolean', 'null'], 'description': 'true = type S, false = type K (combined), null = absent or invalid type.'}, 'proposed_structured': {'anyOf': [{'type': 'object', 'required': ['confidence', 'note'], 'properties': {'ctry': {'type': 'string'}, 'note': {'type': 'string'}, 'pst_cd': {'type': 'string'}, 'twn_nm': {'type': 'string'}, 'bldg_nb': {'type': 'string'}, 'strt_nm': {'type': 'string'}, 'confidence': {'type': 'string', 'description': 'high | low'}}, 'additionalProperties': False}, {'type': 'null'}], 'description': 'For a combined (K) address: the type S fields derived from the combined lines.'}}, 'additionalProperties': False}, 'alternative_schemes': {'type': 'array', 'items': {'type': 'string'}}, 'billing_information': {'type': ['string', 'null']}, 'ready_for_2026_11_14': {'type': 'boolean', 'description': 'valid AND every present address is structured (type S): what banks require from 14.11.2026.'}, 'unstructured_message': {'type': ['string', 'null']}, 'ultimate_creditor_empty': {'type': 'boolean'}}, 'additionalProperties': False}

{'type': 'object', '$schema': 'http://json-schema.org/draft-07/schema#', 'required': ['bic'], 'properties': {'bic': {'type': 'string', 'description': 'BIC/SWIFT code (8 or 11 chars)'}}}

{'type': 'object', '$schema': 'http://json-schema.org/draft-07/schema#', 'required': ['bic'], 'properties': {'bic': {'type': 'string', 'description': 'Echo of the input, normalized to uppercase.'}, 'lei': {'type': ['string', 'null'], 'description': 'Legal Entity Identifier (ISO 17442) if available.'}, 'bic8': {'type': 'string', 'description': '8-char form (institution-level).'}, 'city': {'type': ['string', 'null'], 'description': 'Null, never an empty string, when the source leaves the town blank.'}, 'note': {'type': 'string', 'description': 'Present only when found is false and the part of the directory served from a private file (EBA STEP2, NBP and OeNB records) is not loaded on this deployment: the absence was not looked up there.'}, 'bic11': {'type': 'string', 'description': '11-char form including branch.'}, 'error': {'type': 'string'}, 'found': {'type': 'boolean', 'description': 'True only when the row names an institution: a record is complete or not found.'}, 'valid': {'type': 'boolean', 'description': 'Set when the BIC failed format validation.'}, 'source': {'type': ['string', 'null'], 'description': 'Code of the dataset this row comes from.'}, 'country': {'type': 'object', 'required': ['code', 'name'], 'properties': {'code': {'type': 'string'}, 'name': {'type': 'string'}}, 'description': "Same shape as REST GET /v1/bic/:code. name is the row's country name, then the ISO name, and falls back to the country code only when neither exists.", 'additionalProperties': False}, 'lei_status': {'type': ['string', 'null']}, 'branch_code': {'type': 'string'}, 'branch_info': {'type': ['string', 'null']}, 'institution': {'type': ['string', 'null'], 'description': 'Bank legal name.'}, 'is_test_bic': {'type': 'boolean'}, 'source_name': {'type': ['string', 'null'], 'description': 'source names the dataset of this row and source_name spells it out; source_as_of is present only when that dataset is a copy frozen at that month. listed_in_current_source says whether this BIC8 still appears in a list refreshed this cycle (GLEIF, a national register, the EPC scheme registers, the EBA STEP2 and NBP lists): true when one of them carries it, null when it was not found in what could be read in full. It never answers false today: the EBA STEP2 and NBP lists are only read through our deduplicated directory, which can drop a BIC they carry, so an absence is not proven. It does not prove the bank still exists under this name.'}, 'country_code': {'type': 'string', 'description': 'DEPRECATED since 1.4.0, removed no earlier than 2027-01-01. Use country.code.'}, 'country_name': {'type': ['string', 'null'], 'description': "DEPRECATED since 1.4.0, removed no earlier than 2027-01-01. Use country.name, which is never null: the row's country name, else the ISO name, else the code."}, 'source_as_of': {'type': 'string', 'description': 'Year-month the source DATA is from, present only for a frozen copy.'}, 'valid_format': {'type': 'boolean'}, 'listed_in_current_source': {'type': ['boolean', 'null'], 'description': 'Whether this BIC8 still appears in a list refreshed this cycle: GLEIF, the directory sources that carry no vintage, a national register, the EPC scheme registers. true when one of them carries it; null when it was not found in what could be read in full (never false by default). false is reserved for an index built from every list read in full, which is not the case today: the EBA STEP2 and NBP lists are only read through our deduplicated directory, so this field answers true or null. It does NOT prove the bank still exists under this name: a clearing list can keep the name of a bank that was absorbed.'}}, 'additionalProperties': False}

{'type': 'object', '$schema': 'http://json-schema.org/draft-07/schema#', 'required': ['iid'], 'properties': {'iid': {'type': 'string', 'description': 'Swiss IID (1-5 digit number)'}}}

{'type': 'object', '$schema': 'http://json-schema.org/draft-07/schema#', 'properties': {'bic': {'type': ['string', 'null'], 'description': 'BIC if mapped.'}, 'iid': {'type': 'string', 'description': 'Normalized 5-digit BC-Nummer.'}, 'note': {'type': 'string'}, 'error': {'type': 'string'}, 'found': {'type': 'boolean'}, 'qr_iid': {'type': ['string', 'null'], 'description': 'QR-bill enabled IID.'}, 'address': {'type': 'object', 'required': ['street', 'building_number', 'post_code', 'town', 'country'], 'properties': {'town': {'type': ['string', 'null']}, 'street': {'type': ['string', 'null']}, 'country': {'type': 'string'}, 'post_code': {'type': ['string', 'null']}, 'building_number': {'type': ['string', 'null']}}, 'additionalProperties': False}, 'message': {'type': 'string'}, 'sic_iid': {'type': ['string', 'null']}, 'valid_on': {'type': 'string'}, 'cost_usdc': {'type': 'number', 'description': 'What THIS call was billed. Zero on the free MCP tier.'}, 'institution': {'type': 'object', 'required': ['name', 'type', 'iid_type', 'headquarters_iid'], 'properties': {'name': {'type': 'string'}, 'type': {'type': 'string', 'description': 'bank | cantonal_bank | postfinance | raiffeisen | central_bank | foreign_participant'}, 'iid_type': {'type': 'string', 'description': 'headquarters | branch | other'}, 'headquarters_iid': {'type': 'string'}}, 'additionalProperties': False}, 'list_price_usdc': {'type': 'number', 'description': 'Catalogue price of the same call on the paid REST/x402 route.'}, 'redirected_from': {'type': 'string'}, 'payment_services': {'type': 'object', 'required': ['sic', 'rtgs_chf', 'instant_payments_chf', 'eurosic', 'lsv_bdd_chf', 'lsv_bdd_eur'], 'properties': {'sic': {'type': 'boolean', 'description': 'Swiss Interbank Clearing.'}, 'eurosic': {'type': 'boolean'}, 'rtgs_chf': {'type': 'boolean'}, 'lsv_bdd_chf': {'type': 'boolean'}, 'lsv_bdd_eur': {'type': 'boolean'}, 'instant_payments_chf': {'type': 'boolean'}}, 'additionalProperties': False}}, 'additionalProperties': False}

{'type': 'object', '$schema': 'http://json-schema.org/draft-07/schema#', 'properties': {'device_code': {'type': 'string', 'description': 'Optional. Leave it empty to reuse the last request from this session.'}}}

{'type': 'object', '$schema': 'http://json-schema.org/draft-07/schema#', 'required': ['status', 'api_key', 'key_prefix', 'tier', 'monthly_limit', 'email', 'retry_in_seconds', 'expires_in', 'config_line', 'message'], 'properties': {'tier': {'anyOf': [{'enum': ['anonymous', 'email', 'claimed', 'paid'], 'type': 'string'}, {'type': 'null'}], 'description': 'anonymous = the entry allowance, email/claimed/paid = the raised one.'}, 'email': {'type': ['string', 'null'], 'description': 'Absent on the anonymous tier: no address was ever given.'}, 'status': {'enum': ['authorization_pending', 'approved', 'access_denied', 'expired_token', 'invalid_grant'], 'type': 'string', 'description': 'authorization_pending is normal: wait `retry_in_seconds` and call again.'}, 'api_key': {'type': ['string', 'null'], 'description': 'Present exactly once, on the first approved poll.'}, 'message': {'type': 'string', 'description': 'One sentence for the human.'}, 'expires_in': {'type': ['number', 'null']}, 'key_prefix': {'type': ['string', 'null']}, 'config_line': {'type': ['string', 'null'], 'description': 'The exact command line to give the human. Do not run it yourself.'}, 'monthly_limit': {'type': ['number', 'null']}, 'retry_in_seconds': {'type': ['number', 'null']}}, 'additionalProperties': False}

{'type': 'object', '$schema': 'http://json-schema.org/draft-07/schema#', 'properties': {'reason': {'type': 'string', 'maxLength': 200, 'description': 'Optional. What the key is for, shown to the human on the approval page.'}, 'client_name': {'type': 'string', 'maxLength': 60, 'description': 'Optional. Who is asking, shown to the human on the approval page.'}}}

{'type': 'object', '$schema': 'http://json-schema.org/draft-07/schema#', 'required': ['status', 'user_code', 'verification_uri', 'verification_uri_complete', 'expires_in', 'interval', 'display_to_human'], 'properties': {'status': {'enum': ['ok', 'device_rate_limited', 'device_unavailable'], 'type': 'string', 'description': 'ok means a code was issued. Anything else: read display_to_human and fall back.'}, 'interval': {'type': ['number', 'null'], 'description': 'Minimum seconds between two poll_api_key calls.'}, 'user_code': {'type': ['string', 'null'], 'description': 'Show this to the human, exactly as written, e.g. WDJB-MJHT.'}, 'expires_in': {'type': ['number', 'null'], 'description': 'Seconds until the code stops working.'}, 'display_to_human': {'type': 'string', 'description': 'A ready-made block of text to show verbatim. Do not paraphrase it.'}, 'verification_uri': {'type': ['string', 'null'], 'description': 'The page the human opens. Never open it yourself.'}, 'verification_uri_complete': {'type': ['string', 'null'], 'description': 'Same page with the code pre-filled. This is the one to show.'}}, 'additionalProperties': False}

{'type': 'object', '$schema': 'http://json-schema.org/draft-07/schema#', 'required': ['error_type', 'notes'], 'properties': {'got': {'type': 'string', 'maxLength': 1000, 'description': 'What you received instead (for data errors).'}, 'agent': {'type': 'string', 'maxLength': 120, 'description': 'Which agent/model is reporting, e.g. "claude-sonnet-5 via MCP".'}, 'notes': {'type': 'string', 'maxLength': 4000, 'minLength': 3, 'description': 'What happened, what you needed, or what blocked you â\x80\x94 free text.'}, 'contact': {'type': 'string', 'maxLength': 255, 'description': 'Where we may answer you (e-mail) â\x80\x94 optional, reports can be anonymous.'}, 'endpoint': {'type': 'string', 'maxLength': 200, 'description': 'Endpoint or tool concerned, e.g. /v1/iban/batch.'}, 'expected': {'type': 'string', 'maxLength': 1000, 'description': 'What you expected (for data errors).'}, 'error_type': {'enum': ['wrong_validation', 'stale_bic', 'missing_data', 'incorrect_classification', 'latency', 'other'], 'type': 'string', 'description': 'Category of the report. Use "other" for product feedback, pricing/payment blockers or feature needs.'}}}

{'type': 'object', '$schema': 'http://json-schema.org/draft-07/schema#', 'required': ['ok', 'id'], 'properties': {'id': {'type': 'number', 'description': 'Report id â\x80\x94 check status at GET /v1/feedback/{id}.'}, 'ok': {'type': 'boolean'}}, 'additionalProperties': False}

{'type': 'object', '$schema': 'http://json-schema.org/draft-07/schema#', 'required': ['iban'], 'properties': {'iban': {'type': 'string', 'description': 'IBAN to validate (spaces/hyphens stripped automatically)'}}}

{'type': 'object', '$schema': 'http://json-schema.org/draft-07/schema#', 'required': ['iban', 'valid', 'cost_usdc'], 'properties': {'bic': {'anyOf': [{'type': 'object', 'required': ['code', 'bank_name', 'city'], 'properties': {'lei': {'type': ['string', 'null'], 'description': 'GLEIF identity of the resolved BIC holder, not necessarily the bank-code holder.'}, 'bic8': {'type': 'string', 'description': 'The eight characters of the institution â\x80\x94 the field to compare a supplied BIC against. code is served as the consulted source publishes it, so it is 8 or 11 characters; this one never moves. The branch code (last three characters) is informational: in a cooperative network it names the LOCAL bank and the first eight its clearing institution.'}, 'city': {'type': ['string', 'null']}, 'code': {'type': 'string'}, 'as_of': {'type': ['string', 'null']}, 'basis': {'type': 'string', 'description': 'Where the bank code to BIC pairing came from, and therefore what may be done with the BIC. national_register (the country register publishes this BIC for this bank code â\x80\x94 today DE, AT, BE, SK, CZ, BG, CH, LI and SM; settlement-grade) | curated_map (our maintained bank-code map, exact key, usually right and not an allocation record) | directory_prefix (the bic8 LIKE fallback, which can match several institutions â\x80\x94 read bank_code_check.candidates). Outside a national_register basis the BIC is ADVISORY: confirm it with the beneficiary or the bank before storing it as a routing instruction.'}, 'source': {'type': ['string', 'null'], 'description': 'Source of the bank-code/BIC pairing; keep its provenance.'}, 'address': {'anyOf': [{'type': 'object', 'required': ['type', 'street', 'post_code', 'region', 'city', 'country', 'romanized', 'romanization', 'source', 'language', 'as_of'], 'properties': {'city': {'type': ['string', 'null']}, 'type': {'type': 'string', 'const': 'registered'}, 'as_of': {'type': ['string', 'null']}, 'region': {'type': ['string', 'null']}, 'source': {'type': 'string'}, 'street': {'type': ['string', 'null']}, 'country': {'type': 'string'}, 'language': {'type': ['string', 'null']}, 'post_code': {'type': ['string', 'null']}, 'romanized': {'type': ['string', 'null']}, 'romanization': {'enum': ['original_latin', 'gleif_english', 'unavailable'], 'type': 'string'}}, 'additionalProperties': False}, {'type': 'null'}]}, 'bank_name': {'type': ['string', 'null']}, 'lei_status': {'type': ['string', 'null']}, 'source_as_of': {'type': 'string', 'description': "Year-month the source DATA is from, present ONLY when it differs from as_of. On a curated_map or directory_prefix answer it dates the directory row that supplied the name, the city, the LEI or the address when that row comes from a frozen public copy; never present on a national_register answer, whose name comes from the register and is dated by as_of. Absent means no gap has been established, never 'this is current'."}, 'authoritative': {'type': 'boolean', 'description': 'Whether this BIC may be stored and settled against. Derived from basis, so the two cannot disagree. NOT bank_code_check.authoritative, which answers a different question â\x80\x94 whether a national register was consulted about the BANK CODE. San Marino is where the two part: the pairing is the supervisorâ\x80\x99s, the code space is not its to settle.'}, 'postal_address': {'anyOf': [{'type': 'object', 'required': ['twn_nm', 'ctry', 'format', 'source', 'as_of'], 'properties': {'ctry': {'type': 'string'}, 'as_of': {'type': ['string', 'null']}, 'format': {'enum': ['structured', 'hybrid'], 'type': 'string'}, 'pst_cd': {'type': 'string'}, 'source': {'type': 'string'}, 'twn_nm': {'type': 'string'}, 'bldg_nb': {'type': 'string'}, 'strt_nm': {'type': 'string'}, 'adr_line': {'type': 'array', 'items': {'type': 'string'}}}, 'additionalProperties': False}, {'type': 'null'}]}, 'redirected_from': {'type': 'string', 'description': 'The bank code asked about, when the register answered for the one that took over its clearing (CH/LI only today: SIX marks an IID concatenated and publishes its successor). The IBAN stays valid â\x80\x94 a redirect is not a retirement.'}, 'listed_in_current_source': {'type': ['boolean', 'null'], 'description': 'Whether this BIC8 still appears in a list refreshed this cycle: GLEIF, the directory sources that carry no vintage, a national register, the EPC scheme registers. true when one of them carries it; null when it was not found in what could be read in full (never false by default). false is reserved for an index built from every list read in full, which is not the case today: the EBA STEP2 and NBP lists are only read through our deduplicated directory, so this field answers true or null. It does NOT prove the bank still exists under this name: a clearing list can keep the name of a bank that was absorbed.'}}, 'additionalProperties': False}, {'type': 'null'}]}, 'bban': {'type': 'object', 'required': ['bank_code', 'account_number'], 'properties': {'bank_code': {'type': 'string'}, 'branch_code': {'type': 'string'}, 'account_number': {'type': 'string'}}, 'additionalProperties': False}, 'iban': {'type': 'string', 'description': 'Normalized IBAN (uppercase, no spaces).'}, 'sepa': {'type': 'object', 'required': ['member', 'schemes', 'vop_required'], 'properties': {'basis': {'enum': ['country_default', 'epc_register'], 'type': 'string', 'description': 'Where `schemes` came from: read at the EPC register for this bank, or defaulted from the country.'}, 'member': {'type': 'boolean'}, 'schemes': {'type': 'array', 'items': {'type': 'string'}}, 'bank_schemes': {'anyOf': [{'type': 'array', 'items': {'type': 'string'}}, {'type': 'null'}], 'description': "The bank's own schemes from the EPC registers when bank_reachability is listed; [] for an unallocated bank code; null otherwise."}, 'vop_required': {'type': 'boolean'}, 'vop_participant': {'type': ['boolean', 'null'], 'description': 'true = resolved bank is listed as ready in the EPC VoP scheme register; null = no institution resolved, or the VoP register is not loaded (not consulted); a resolved bank outside the SEPA area is answered false from the country either way.'}, 'bank_reachability': {'type': ['string', 'null'], 'description': 'listed | not_listed | no_bank | bank_code_not_allocated, or null. Whether the EPC scheme registers list the resolved BANK, never borrowed from the country (member, schemes and basis still describe the country and are unchanged). listed: the bank has rows in the SCT, SCT Inst or SDD register. not_listed: it has none (an absence from the register is not an exclusion from the scheme). no_bank: no BIC resolved for this bank code, so no bank could be looked up in the EPC registers (a register may still name the holder: see bank_code_holder and bank_code_check). bank_code_not_allocated: the national register says nobody holds the bank code. null: the registers are not loaded on this deployment, or no bank was resolved because the bank-code check itself is unavailable (not consulted, never read as not_listed or no_bank). Absent outside SEPA.'}, 'vop_register_status': {'type': ['string', 'null'], 'description': "active | pending | inactive | not_listed, or null. The bank's status in the EPC Verification of Payee register: active (the same as vop_participant true), pending, inactive, or not_listed when the register has no row for it; null when no BIC resolved or the register was not consulted (screened false). Outside the SEPA area the country answers instead of the register (not_listed on POST /v1/iban/compliance) whether or not the register is loaded; the validation carries no sepa.vop_register_status there. It says whether the payee's bank answers VoP requests; IBANforge never runs the name check itself."}}, 'additionalProperties': False}, 'error': {'type': 'string'}, 'valid': {'type': 'boolean'}, 'checks': {'type': 'object', 'required': ['iban_structure', 'iban_checksum', 'bank_code', 'bic', 'sepa_reachability', 'national_check_digits', 'account_exists', 'payee_name', 'institution_sanctions', 'country_sanctions', 'payee_sanctions'], 'properties': {'bic': {'type': 'string', 'description': 'pass | fail | inferred | unknown | not_checked | not_applicable'}, 'bank_code': {'type': 'string', 'description': 'pass | fail | inferred | unknown | not_checked | not_applicable'}, 'payee_name': {'type': 'string', 'description': 'pass | fail | inferred | unknown | not_checked | not_applicable'}, 'iban_checksum': {'type': 'string', 'description': 'pass | fail | inferred | unknown | not_checked | not_applicable'}, 'account_exists': {'type': 'string', 'description': 'pass | fail | inferred | unknown | not_checked | not_applicable'}, 'iban_structure': {'type': 'string', 'description': 'pass | fail | inferred | unknown | not_checked | not_applicable'}, 'payee_sanctions': {'type': 'string', 'description': 'pass | fail | inferred | unknown | not_checked | not_applicable'}, 'country_sanctions': {'type': 'string', 'description': 'pass | fail | inferred | unknown | not_checked | not_applicable'}, 'sepa_reachability': {'type': 'string', 'description': 'pass | fail | inferred | unknown | not_checked | not_applicable'}, 'institution_sanctions': {'type': 'string', 'description': 'pass | fail | inferred | unknown | not_checked | not_applicable'}, 'national_check_digits': {'type': 'string', 'description': 'pass | fail | inferred | unknown | not_checked | not_applicable'}}, 'description': "One status per check: pass (checked against a source that settles it), fail (checked, and wrong), inferred (answered from a source that does not settle it), unknown (attempted, no conclusion), not_checked (IBANforge does not make this check here), not_applicable (the check has no object for this IBAN). payee_name: never checked here; the name check is made by the payee's bank through Verification of Payee (VoP), and sepa.vop_register_status says whether that bank answers VoP requests. account_exists: never checked here; only the payee's bank knows whether the account is open. payee_sanctions: never checked; the sanctions screen of POST /v1/iban/compliance is made on the payee's bank (BIC8) and country only. institution_sanctions and country_sanctions are filled by POST /v1/iban/compliance and not_checked on a validation. national_check_digits: the check key a country keeps inside the BBAN, a second check independent of mod-97. Checked for FR and MC (RIB key), BE (the last two digits, modulo 97), IT and SM (CIN) and ES (DC), with the proof in the national_check_digits block, and for GB (Vocalink modulus), with the proof in modulus_check; not_checked elsewhere (the German account-number methods are not checked yet). pass means the account number is well formed, never that the account exists; fail means it cannot have been issued as written, and valid stays true. A key may be added later; a key is never removed. Present only when valid is true.", 'additionalProperties': False}, 'issuer': {'type': 'object', 'required': ['type', 'name', 'classification'], 'properties': {'name': {'type': 'string'}, 'type': {'type': ['string', 'null'], 'description': 'bank | digital_bank | emi | payment_institution; null when unsubstantiated'}, 'iban_issuer': {'enum': ['confirmed', 'not_listed'], 'type': 'string'}, 'classification': {'type': 'string', 'description': 'curated | register | default. Whether the type was established or assumed. curated = the BIC8 is in the issuer set, so this is an identification. register = an official register names the holder of this bank code and says what it is; it carries a date and an authority in psd_registration, and it only ever replaces a default. default = nothing is on file and "bank" is the fallback, which covers 97.9% of BIC8 (measured 29/07/2026). Count curated and register when sizing virtual-IBAN exposure, never default.'}}, 'additionalProperties': False}, 'country': {'type': 'object', 'required': ['code', 'name'], 'properties': {'code': {'type': 'string', 'description': 'ISO 3166-1 alpha-2 country code.'}, 'name': {'type': 'string'}}, 'additionalProperties': False}, 'clearing': {'anyOf': [{'type': 'object', 'required': ['iid', 'name', 'type', 'town', 'sic', 'instant_payments_chf', 'eurosic', 'qr_iid', 'qr_iid_source'], 'properties': {'iid': {'type': 'string'}, 'sic': {'type': 'boolean'}, 'name': {'type': 'string'}, 'town': {'type': ['string', 'null']}, 'type': {'type': 'string'}, 'qr_iid': {'type': ['string', 'null']}, 'eurosic': {'type': 'boolean'}, 'qr_iids': {'type': 'array', 'items': {'type': 'string'}}, 'is_qr_iid': {'type': 'boolean'}, 'qr_iid_source': {'anyOf': [{'enum': ['register', 'headquarters'], 'type': 'string'}, {'type': 'null'}]}, 'instant_payments_chf': {'type': 'boolean'}}, 'additionalProperties': False}, {'type': 'null'}], 'description': 'Swiss clearing data when country is CH or LI.'}, 'cost_usdc': {'type': 'number', 'description': 'What THIS call was billed. Zero on the free MCP tier.'}, 'formatted': {'type': 'string', 'description': 'IBAN with 4-char groups for display.'}, 'next_steps': {'type': 'array', 'items': {'type': 'object', 'required': ['code', 'do', 'because'], 'properties': {'do': {'type': 'string'}, 'code': {'type': 'string', 'description': 'Stable identifier. Branch on this.'}, 'action': {'type': 'string', 'description': 'An IBANforge call that performs the step, when one exists.'}, 'because': {'type': 'string', 'description': 'The response field that produced this step.'}}, 'additionalProperties': False}, 'description': 'Ordered advice derived from THIS result: what blocks a payment first, what merely enriches it after. Branch on `code`, never on the prose. `because` names the field that produced the step so the advice is auditable. Empty for an IBAN that failed validation.'}, 'check_digits': {'type': 'string'}, 'error_detail': {'type': 'string'}, 'modulus_check': {'type': 'object', 'required': ['checked', 'passed', 'source', 'table_fetched_on'], 'properties': {'passed': {'type': ['boolean', 'null']}, 'source': {'type': 'string'}, 'checked': {'type': 'boolean'}, 'table_fetched_on': {'type': 'string'}}, 'additionalProperties': False}, 'processing_ms': {'type': 'number'}, 'bank_code_check': {'type': 'object', 'required': ['value', 'status', 'match', 'register', 'authoritative', 'as_of'], 'properties': {'as_of': {'type': 'string'}, 'match': {'type': ['string', 'null'], 'description': 'register (exact key) | prefix (bic8 LIKE heuristic) | null'}, 'value': {'type': 'string'}, 'reason': {'type': 'string', 'description': 'WHY the verdict is not verified, as one token to branch on. Absent when status is verified. not_allocated (a national register denies the code â\x80\x94 the only value that licenses "do not send") | absent_from_reference_data (our composite map does not carry it; the country register was not consulted) | no_reference_data_for_country | register_names_no_holder (the register defines the code space and publishes no holder â\x80\x94 silence, not a denial) | national_register_unavailable (the register this country is normally decided against could not be consulted) | lookup_failed (the lookup could not run: timeout, unreadable database). The last two describe IBANforge, never the beneficiary. Never escalate either into a refusal.'}, 'status': {'type': 'string', 'description': 'verified | not_in_register | unavailable. A separate verdict on the bank code, so bic:null stops meaning three different things.'}, 'retired': {'type': 'boolean', 'description': 'True when a register says the code is leaving (DE, authoritative) or has been struck off (IT, authoritative false, with retired_on). Still a verified result: it WAS allocated. Never a refusal.'}, 'register': {'type': ['string', 'null']}, 'candidates': {'type': 'number', 'description': 'BIC8 the prefix matched; >1 means the BIC may belong to another institution.'}, 'retired_on': {'type': 'string', 'description': 'YYYY-MM-DD, with retired where the register dates it (IT): the last day it lists this code for its last holder.'}, 'check_digit': {'type': 'object', 'required': ['valid', 'algorithm'], 'properties': {'valid': {'type': 'boolean'}, 'algorithm': {'type': 'string'}}, 'additionalProperties': False}, 'institution': {'type': 'object', 'required': ['name', 'street', 'post_code', 'town', 'country'], 'properties': {'lei': {'type': ['string', 'null']}, 'name': {'type': 'string'}, 'town': {'type': ['string', 'null']}, 'street': {'type': ['string', 'null']}, 'country': {'type': 'string'}, 'post_code': {'type': ['string', 'null']}}, 'additionalProperties': False}, 'authoritative': {'type': 'boolean', 'description': 'True only where the reference set is the national register (CH, LI, DE). Only then does not_in_register mean the code is not allocated.'}, 'superseded_by': {'type': 'string', 'description': 'The bank code that takes over. DE: the successor the register designates, re-paper against it. IT: the legal successor by merger or incorporation, not necessarily the bank now holding the account.'}}, 'additionalProperties': False}, 'list_price_usdc': {'type': 'number', 'description': 'Catalogue price of the same call on the paid REST/x402 route.'}, 'risk_indicators': {'type': 'object', 'required': ['issuer_type', 'country_risk', 'test_bic', 'sepa_reachable', 'sepa_reachable_scope', 'vop_coverage'], 'properties': {'test_bic': {'type': 'boolean'}, 'issuer_type': {'type': ['string', 'null'], 'description': 'Null when no institution resolved â\x80\x94 it no longer defaults to "bank".'}, 'country_risk': {'type': 'string'}, 'vop_coverage': {'type': 'boolean'}, 'sepa_reachable': {'type': 'boolean'}, 'sepa_reachable_scope': {'type': 'string', 'description': 'Scope the reachability holds at. Country-derived, not account-derived.'}}, 'additionalProperties': False}, 'bank_code_holder': {'type': 'string', 'description': 'confirmed | inferred | not_allocated | unknown. Who holds the bank code. confirmed: a register that publishes holders names the holder of this code (a national register that settles the code space, or a partial register on a hit). inferred: we name a holder from a source that cannot settle it (our composite map, the prefix fallback, a published structural rule), so read it as our inference. not_allocated: the national register says nobody holds this code, so do not send. unknown: no conclusion. valid stays true in all four: it only means the IBAN is well formed. bank_code_check.status verified means resolved; this field says whether a source settles it.'}, 'psd_registration': {'type': 'object', 'required': ['registered', 'entity_type', 'name', 'country', 'competent_authority', 'source', 'as_of'], 'properties': {'name': {'type': 'string'}, 'as_of': {'type': 'string'}, 'source': {'type': 'string'}, 'country': {'type': 'string'}, 'registered': {'type': 'boolean', 'const': True}, 'entity_type': {'type': 'string'}, 'competent_authority': {'type': 'string'}}, 'additionalProperties': False}, 'official_identity': {'type': 'object', 'required': ['name', 'lei', 'address', 'category', 'matched_by', 'source', 'free_of_charge', 'as_of', 'authoritative'], 'properties': {'lei': {'type': ['string', 'null']}, 'name': {'type': 'string', 'description': "The institution's name as the publisher writes it."}, 'as_of': {'type': 'string', 'description': 'Date of the list this row came from. Both lists are republished every business day.'}, 'source': {'type': 'string', 'description': 'The publisher, cited as their licence requires. Relay it.'}, 'address': {'type': ['string', 'null'], 'description': 'One-line registered address as published.'}, 'category': {'type': 'string'}, 'matched_by': {'type': 'string', 'description': 'lei | national_code'}, 'attribution': {'type': 'string', 'description': 'The Banco de Espana citation formula, verbatim. Spanish blocks only.'}, 'authoritative': {'type': 'boolean', 'description': 'Always false. Neither publisher allocates bank codes.'}, 'free_of_charge': {'type': 'string', 'description': 'Both publishers require buyers to be told, on every access, that the data is available free of charge from their own website. Relay it with the answer; do not strip it.'}}, 'description': 'Who a central bank says holds the resolved code (ECB by LEI and for FR bank codes, Banco de Espana for ES). Present only on a match â\x80\x94 absence is not a negative. INFORMATIONAL ONLY: it never changes valid or bank_code_check, because both publishers relay rather than allocate.', 'additionalProperties': False}, 'pra_authorisation': {'type': 'object', 'required': ['authorised', 'firm_name', 'frn', 'section', 'basis', 'source', 'list_month'], 'properties': {'frn': {'type': 'string'}, 'basis': {'type': 'string'}, 'source': {'type': 'string'}, 'section': {'type': 'string'}, 'firm_name': {'type': 'string'}, 'authorised': {'type': 'boolean', 'const': True}, 'list_month': {'type': 'string'}}, 'additionalProperties': False}, 'national_check_digits': {'type': 'object', 'required': ['country', 'scheme', 'status'], 'properties': {'detail': {'type': 'string', 'description': 'Present on fail and not_applicable only.'}, 'scheme': {'type': 'string', 'description': 'fr_rib_key | be_mod97 | it_cin | es_dc'}, 'status': {'type': 'string', 'description': 'pass | fail | not_applicable'}, 'country': {'type': 'string', 'description': 'The IBAN country (MC stays MC, SM stays SM).'}}, 'description': 'The check key a country keeps inside the BBAN, recomputed from the IBAN alone. Present only on a valid IBAN of FR, MC, BE, IT, SM or ES (GB has modulus_check instead); absent elsewhere, where checks.national_check_digits is not_checked. country is the IBAN country. scheme names the algorithm: fr_rib_key (FR and MC: the RIB key, the last two digits of the BBAN, over the bank code, branch code and account number), be_mod97 (BE: the last two digits, the first ten digits modulo 97, or 97 when the remainder is 0), it_cin (IT and SM: the CIN, the control letter at the start of the BBAN, over the ABI, CAB and account number), es_dc (ES: the two DC digits, positions 9 and 10 of the BBAN). status: pass (the key matches, so the account number is well formed; it does not prove the account exists or is open) or fail (the key does not match: this account number cannot have been issued as written, a typo or a made-up number). A fail never makes valid false, because the IBAN check digits are right: read the two separately, and confirm the details with the beneficiary before paying. not_applicable is reserved for a BBAN without the national layout, which a valid IBAN never has. detail, present on fail and not_applicable only, says which digits disagree; it never gives the expected key. checks.national_check_digits repeats status.', 'additionalProperties': False}}, 'additionalProperties': False}

{'type': 'object', '$schema': 'http://json-schema.org/draft-07/schema#', 'required': ['reference'], 'properties': {'iban': {'type': 'string', 'description': 'Optional creditor IBAN â\x80\x94 supply it to get the pairing verdict'}, 'reference': {'type': 'string', 'description': 'The reference as printed; spaces, slashes and the +++â\x80¦+++ wrapper are stripped'}, 'reference_type': {'type': 'string', 'description': 'Optional hint: rf | scor | qrr | ogm | vcs | viitenumero | kid | ocr'}}}

{'type': 'object', '$schema': 'http://json-schema.org/draft-07/schema#', 'required': ['reference', 'scheme', 'valid', 'status', 'source', 'note'], 'properties': {'note': {'type': 'string', 'description': 'What was checked, and what was not.'}, 'as_of': {'type': 'string', 'description': 'YYYY-MM of that document.'}, 'valid': {'type': ['boolean', 'null'], 'description': 'null means the scheme was recognised and cannot be checked without the creditor bank configuration. Never report null as false.'}, 'scheme': {'type': ['string', 'null'], 'description': 'rf | qrr | ogm | viitenumero | kid | ocr, or null when nothing matched.'}, 'source': {'type': ['string', 'null'], 'description': 'The document publishing the rule. Null only when no scheme matched. Relay it.'}, 'status': {'type': 'string', 'description': 'checked | unverifiable_without_creditor_config | unrecognised'}, 'pairing': {'type': 'string', 'description': 'Present only when an iban was supplied: ok | qrr_requires_qr_iban | scor_forbidden_with_qr_iban | not_applicable'}, 'reference': {'type': 'string', 'description': 'Normalized: uppercase, separators removed.'}, 'also_valid_as': {'type': 'object', 'required': ['scheme', 'valid'], 'properties': {'valid': {'type': 'boolean'}, 'scheme': {'type': 'string'}, 'check_digit_expected': {'type': 'string'}}, 'description': 'The second reading of an ambiguous string, with its own verdict.', 'additionalProperties': False}, 'pairing_as_of': {'type': 'string'}, 'pairing_source': {'type': 'string', 'description': 'The document publishing the pairing rule â\x80\x94 a DIFFERENT one from source.'}, 'check_digit_expected': {'type': 'string', 'description': 'A STRING, so a two-digit value beginning with zero survives (OGM remainder 3 is "03", remainder 0 is "97").'}}, 'additionalProperties': False}