Banks API

Access comprehensive European bank data with SWIFT/BIC codes, addresses, and autonomous IBAN-to-BIC mapping. Features reliable bank information from official central bank sources with exact-match IBAN lookup capabilities.

European Focus

Comprehensive coverage of 6 European countries with verified official data sources from central banks and financial authorities.

IBAN-to-BIC Mapping

Autonomous IBAN-to-BIC lookup without external API dependencies. Supports exact-match resolution for supported countries.

Quality Over Quantity

Only trusted, verified data sources. Unsupported countries return proper error messages instead of unreliable results.

Base URL

https://api.clients.lv/api/companies

Authentication & Permissions

All API endpoints require authentication using Bearer tokens with the following permission:

Required Permission

urcompanies:read - Required for all API access including IBAN-to-BIC mapping

The IBAN-to-BIC mapping functionality is integrated into the main companies API and uses the same authentication system.

Authentication Example

cURL Example

curl -X POST -H "Authorization: Bearer YOUR_API_TOKEN" \
     -H "Accept: application/json" \
     -H "Content-Type: application/json" \
     -d '{"iban":"DE89370400440532013000"}' \
     https://api.clients.lv/api/companies/lookup-by-iban

Supported Countries

IBAN-to-BIC mapping is available for countries with verified official data sources from central banks and financial authorities.

DE

Germany

Bundesbank (4,677 banks)

NL

Netherlands

DNB (620 banks)

BE

Belgium

NBB (312+ banks)

CH

Switzerland

SIX Group (45 banks)

AT

Austria

OENB (23 banks)

LU

Luxembourg

ABBL (11 banks)

Exact Match Policy

For unsupported countries or IBANs without exact matches, the API returns proper error messages instead of unreliable results. This ensures data quality and prevents false bank identification.

IBAN-to-BIC Mapping

POST /api/companies/lookup-by-iban

Autonomous IBAN-to-BIC lookup that validates IBAN format, extracts bank identifiers, and returns exact bank matches from official sources. No external API dependencies.

✅ What Works

IBAN validation and normalization
Bank identifier extraction
Exact-match BIC resolution
Official data sources only

⚠️ Limitations

Only 6 European countries supported
No fuzzy matching or fallbacks
Unsupported countries return errors
Missing banks return no results

Request Format

JSON Request Body

{
  "iban": "DE89370400440532013000"
}

Successful Response

Success Response (HTTP 200)

{
  "success": true,
  "accuracy": "exact",
  "source": "local_mapping",
  "search_method": "iban_bic_mapping",
  "iban_info": {
    "submitted_iban": "DE89370400440532013000",
    "normalized_iban": "DE89370400440532013000",
    "formatted_iban": "DE89 3704 0044 0532 0130 00",
    "valid": true,
    "country_code": "DE",
    "country_name": "Germany",
    "check_digits": "89",
    "bank_identifier": "37040044",
    "account_identifier": "0532013000"
  },
  "bank_info": {
    "bic": "COBADEFFXXX",
    "bank_name": "Commerzbank AG",
    "bank_city": "Frankfurt am Main",
    "bank_address": "Kaiserstraße 16, 60311 Frankfurt am Main",
    "data_source": "bundesbank"
  }
}

Error Response

Error Response (HTTP 404)

{
  "success": false,
  "error": "No exact bank match found for this IBAN",
  "iban_info": {
    "submitted_iban": "LT343500010001508741",
    "normalized_iban": "LT343500010001508741",
    "formatted_iban": "LT34 3500 0100 0150 8741",
    "valid": true,
    "country_code": "LT",
    "country_name": "Lithuania",
    "check_digits": "34",
    "bank_identifier": "35000",
    "account_identifier": "10001508741"
  }
}

Example Usage

German IBAN (Supported)

cURL Request

curl -X POST \
  "https://api.clients.lv/api/companies/lookup-by-iban" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"iban":"DE89370400440532013000"}'

Expected Result

✅ Success

Bank: Commerzbank AG

BIC: COBADEFFXXX

Source: Bundesbank

Belgian IBAN (Supported)

cURL Request

curl -X POST \
  "https://api.clients.lv/api/companies/lookup-by-iban" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"iban":"BE91967051052476"}'

Expected Result

✅ Success

Bank: Wise Europe SA

BIC: TRWIBEB1XXX

Source: NBB (manual correction)

Lithuanian IBAN (Unsupported)

cURL Request

curl -X POST \
  "https://api.clients.lv/api/companies/lookup-by-iban" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"iban":"LT343500010001508741"}'

Expected Result

❌ Not Found (HTTP 404)

Lithuania not in supported countries

IBAN valid, but no bank mapping

Error: "No exact bank match found"

HTTP Status Codes

Code	Status	Description	When This Occurs
200	OK	Exact bank match found	Valid IBAN from supported country with bank mapping
400	Bad Request	Invalid IBAN format	Malformed IBAN, wrong length, or checksum failure
401	Unauthorized	Authentication required	Missing or invalid Bearer token
404	Not Found	No bank match found	Valid IBAN but unsupported country or missing bank
422	Unprocessable Entity	Invalid IBAN details	IBAN validation failed with specific error details
429	Too Many Requests	Rate limit exceeded	Too many API requests per minute/hour

Implementation Notes

🏦 Data Sources

Germany: Bundesbank official BLZ directory (updated monthly)

Netherlands: DNB official bank code list (updated monthly)

Belgium: NBB financial institution codes (manual corrections applied)

Switzerland: SIX Group official bank directory (updated quarterly)

Austria: OENB official bank code list (updated quarterly)

Luxembourg: ABBL member directory (updated quarterly)

⚠️ Quality Assurance

• No fuzzy matching: Only exact bank identifier matches are returned

• No country fallbacks: Unsupported countries return proper 404 errors

• Single bank policy: Multiple bank matches are rejected to avoid ambiguity

• Official sources only: No unreliable data extraction or guessing algorithms

✅ Integration Benefits

• Autonomous operation: No external API dependencies or rate limits

• Consistent authentication: Uses same token system as companies API

• Reliable responses: Predictable error handling and status codes

• European focus: Comprehensive coverage of major EU banking markets