Verify a BIC (structural + optional directory lookup)
verify_bic_onlineRead-onlyIdempotent
Verifies a BIC structure using ISO 9362 rules and optionally enriches the result with bank name, city, and country from a configured directory endpoint.
Instructions
Verify a BIC structurally, optionally enriched by a directory lookup.
Two-stage verification. First an OFFLINE ISO 9362 structural check (via the
pacs008 library): confirms the 8- or 11-character shape and that the
country code (chars 5-6) is a valid ISO 3166-1 alpha-2 code. A malformed
BIC returns ``{"bic": ..., "is_structurally_valid": False, "error": ...}``
and stops there.
Then, only if a directory endpoint is configured (the ``directory_url``
argument or the ``PACS008_BIC_DIRECTORY_URL`` environment variable), the
tool performs a read-only HTTP GET against that endpoint and folds whatever
institution ``name``/``city``/``country``/``status`` it returns into a
``directory`` sub-dict. There is no free authoritative SWIFT BIC directory,
so with NO endpoint configured the tool returns the structural result plus
a ``note`` and ``directory: null`` -- it never fabricates a bank name.
Online lookups require the optional ``online`` extra (``pip install
'pacs008-mcp[online]'``, which pulls in ``httpx``); without it the tool
still returns the structural result plus an ``error`` explaining the
missing extra. Endpoint 4xx/5xx responses and transport failures are
likewise reported as a graceful ``error`` alongside the structural result.
Returns a dict with ``bic``, ``is_structurally_valid``, ``bank_code``,
``country_code``, ``location_code``, ``branch_code``, ``length`` and either
``directory`` (a dict of institution details, or ``null``) plus, when
applicable, ``note`` / ``error``.
Args:
bic: The BIC / SWIFT code to verify.
directory_url: Optional directory endpoint for online enrichment.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| bic | Yes | A BIC / SWIFT code to verify (ISO 9362), 8 or 11 characters, e.g. 'DEUTDEFF' or 'DEUTDEFF500'. Spaces and hyphens are stripped and the value is upper-cased before checking. | |
| directory_url | No | Optional base URL of a BIC directory / reference-data endpoint to enrich the result with institution details. The tool issues a read-only HTTP GET with a '?bic=<BIC>' query parameter and parses the JSON object it returns (name/city/country/status). If omitted, the PACS008_BIC_DIRECTORY_URL environment variable is used; if neither is set, only the offline structural result is returned and NO institution name is inferred. No default/public directory ships with this server. |