Overview

Validate bank routing identifiers and look up correspondent banks. Use these endpoints to check a BIC/SWIFT code or an ABA routing number before you build a payment instruction, and to resolve the correspondent (intermediary) bank you need to route a cross-border payment through.

Prerequisites

You'll need an API key. See Quickstart or Authentication if you don't have one yet.

Note

These endpoints use an API key in the X-API-Key header, not a Bearer token. They are all POST and require an Idempotency-Key header — retries with the same key replay the original result without re-charging.

Note

In sandbox, these endpoints return seeded fixture data for a fixed set of test identifiers only; any other identifier returns TEST_NUMBER_NOT_FOUND. See Test Numbers → Bank Routing for the full list. The examples below use production-style values — in sandbox, substitute the documented test identifiers.

Validate a BIC

Check whether a BIC/SWIFT code (Business Identifier Code, ISO 9362) is structurally valid and break it into its component parts.

Terminal

curl -X POST https://api.lira.com/api/v1/verifications/bic \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Idempotency-Key: YOUR_IDEMPOTENCY_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "bic": "IRVTUS3NXXX"
  }'

Request body fields

Field	Type	Required	Description
`bic`	string	Yes	The BIC/SWIFT code to validate. 8 or 11 characters. Case-insensitive — it is normalised to uppercase before validation.

Response

The endpoint always returns 200 OK for a well-formed request. Read the valid field to determine the outcome — an invalid BIC is a normal 200 result with valid: false, not an API error.

Valid BIC

JSON

{
  "valid": true,
  "bic": "IRVTUS3NXXX",
  "institution_code": "IRVT",
  "country_code": "US",
  "location_code": "3N",
  "branch_code": "XXX",
  "is_test": false,
  "derived_country": "US"
}

Invalid BIC

JSON

{
  "valid": false,
  "bic": "IRVT",
  "reason_code": "INVALID_LENGTH"
}

Response fields

Field	Type	Description
`valid`	boolean	`true` if the BIC is structurally valid.
`bic`	string	The normalised (trimmed and uppercased) BIC.
`institution_code`	string	Characters 1–4: the institution identifier. Present when `valid` is `true`.
`country_code`	string	Characters 5–6: the ISO 3166-1 alpha-2 country code embedded in the BIC.
`location_code`	string	Characters 7–8: the location code.
`branch_code`	string	Characters 9–11: the branch code. `null` when the BIC is 8 characters.
`is_test`	boolean	`true` when the BIC is a test code (second character of the location code is `0`, per ISO 9362).
`derived_country`	string	Set when the embedded country code is a valid ISO 3166-1 alpha-2 country.
`reason_code`	string	Present only when `valid` is `false`. See Reason codes.

Validate a routing number

Check whether a US ABA routing number is valid. The endpoint normalises the input (strips non-digits, left-pads an 8-digit value to 9) and runs the ABA mod-10 checksum.

Terminal

curl -X POST https://api.lira.com/api/v1/verifications/routing-codes \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Idempotency-Key: YOUR_IDEMPOTENCY_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "routing_number": "021000018"
  }'

Request body fields

Field	Type	Required	Description
`routing_number`	string	Yes	The ABA routing number (9 digits). Send it as a string to preserve leading zeros — a JSON number drops them (e.g. `021000018` becomes `21000018`). A numeric value is still accepted and coerced to a string.

Response

Like the BIC endpoint, this always returns 200 OK for a well-formed request; check the valid field.

Valid routing number

JSON

{
  "valid": true,
  "routing_number": "021000018",
  "normalized": "021000018",
  "checksum_ok": true
}

Invalid routing number

JSON

{
  "valid": false,
  "routing_number": "12345",
  "normalized": "12345",
  "checksum_ok": false,
  "reason_code": "INVALID_LENGTH"
}

Response fields

Field	Type	Description
`valid`	boolean	`true` if the routing number passed length and checksum checks.
`routing_number`	string	The original input, exactly as supplied.
`normalized`	string	The digit-only, zero-padded 9-character form.
`checksum_ok`	boolean	Whether the ABA mod-10 checksum passed.
`reason_code`	string	Present only when `valid` is `false`. See Reason codes.

Look up correspondent banks

Given a foreign BIC, return the correspondent (intermediary) banks on file for it, sorted by confidence descending. Use this to pick the US correspondent to route a cross-border payment through.

Terminal

curl -X POST https://api.lira.com/api/v1/verifications/correspondents \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Idempotency-Key: YOUR_IDEMPOTENCY_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "bic": "AACSDE33XXX"
  }'

Request body fields

Field	Type	Required	Description
`bic`	string	Yes	The foreign BIC/SWIFT code to look up correspondents for. 8 or 11 alphanumeric characters. Case-insensitive.

Response

Correspondents found — 200 OK

JSON

{
  "bic": "AACSDE33XXX",
  "correspondents": [
    {
      "name": "BNY MELLON",
      "bic": "IRVTUS3NXXX",
      "routing_number": "021000018",
      "account_number": "8900123456",
      "confidence": 0.95,
      "last_verified": "2025-01-15"
    },
    {
      "name": "JPMORGAN CHASE BANK",
      "bic": "CHASUS33XXX",
      "routing_number": "021000021",
      "account_number": null,
      "confidence": 0.72,
      "last_verified": "2024-11-30"
    }
  ]
}

Valid BIC, no routes on file — 404 Not Found

JSON

{
  "bic": "NROUTDE33XXX",
  "reason_code": "NO_ROUTE_FOUND",
  "correspondents": []
}

Structurally invalid BIC — 422 Unprocessable Entity

JSON

{
  "valid": false,
  "bic": "IRVT",
  "reason_code": "INVALID_LENGTH"
}

Response fields

Field	Type	Description
`bic`	string	The queried foreign BIC, uppercased.
`correspondents`	array	Correspondent banks sorted by confidence descending. Empty on a `404`.
`correspondents[].name`	string	Canonical name of the correspondent bank.
`correspondents[].bic`	string	BIC/SWIFT code of the correspondent bank.
`correspondents[].routing_number`	string	ABA routing number of the correspondent bank (9 digits).
`correspondents[].account_number`	string	Nostro account number held at this correspondent. `null` when not on file.
`correspondents[].confidence`	number	Confidence score for the route, between `0.0` and `1.0` (higher is better).
`correspondents[].last_verified`	string	Date the route was last verified, in `YYYY-MM-DD` format.
`reason_code`	string	Present on `404` (`NO_ROUTE_FOUND`) or `422` (a structural reason). See Reason codes.

Note

Unlike the validation endpoints, this lookup uses HTTP status to signal the outcome: 200 when routes are found, 404 when the BIC is valid but has no routes on file, and 422 when the BIC itself is malformed.

Batch validation

Validate up to 100 mixed items (BICs, routing numbers, and correspondent-route lookups) in a single request. Results are returned in the same order as the input.

Terminal

curl -X POST https://api.lira.com/api/v1/verifications/batch \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Idempotency-Key: YOUR_IDEMPOTENCY_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      { "type": "bic", "value": "IRVTUS3NXXX" },
      { "type": "routing", "value": "021000018" },
      { "type": "route", "value": "AACSDE33XXX" }
    ]
  }'

Request body fields

Field	Type	Required	Description
`items`	array	Yes	1–100 items to validate.
`items[].type`	string	Yes	`bic` (validate a BIC), `routing` (validate an ABA routing number), or `route` (correspondent route lookup for a BIC).
`items[].value`	string	Yes	The value to validate or look up. Format depends on `type`: BIC (8 or 11 chars), routing number (9 digits), or BIC for a route lookup.

Response

Always 200 OK. Each entry in results mirrors the corresponding input item and carries a result object whose shape matches the equivalent single endpoint.

JSON

{
  "results": [
    {
      "type": "bic",
      "value": "IRVTUS3NXXX",
      "result": {
        "valid": true,
        "bic": "IRVTUS3NXXX",
        "institution_code": "IRVT",
        "country_code": "US",
        "location_code": "3N",
        "branch_code": "XXX",
        "is_test": false,
        "derived_country": "US"
      }
    },
    {
      "type": "routing",
      "value": "021000018",
      "result": {
        "valid": true,
        "routing_number": "021000018",
        "normalized": "021000018",
        "checksum_ok": true
      }
    },
    {
      "type": "route",
      "value": "AACSDE33XXX",
      "result": {
        "outcome": "found",
        "bic": "AACSDE33XXX",
        "correspondents": [
          {
            "name": "BNY MELLON",
            "bic": "IRVTUS3NXXX",
            "routing_number": "021000018",
            "account_number": "8900123456",
            "confidence": 0.95,
            "last_verified": "2025-01-15"
          }
        ]
      }
    }
  ]
}

Result shapes by type

`type`	`result` shape
`bic`	Same fields as the Validate a BIC response.
`routing`	Same fields as the Validate a routing number response.
`route`	`{ "outcome": "found" \| "no_route" \| "invalid", "bic": string, "correspondents"?: array, "reason_code"?: string }`. `outcome` is `found` when routes exist, `no_route` when the BIC is valid but has none, and `invalid` when the BIC is malformed.

Reason codes

reason_code explains why a check did not pass. It is present only on a failed result.

`reason_code`	Applies to	Meaning
`INVALID_LENGTH`	BIC, routing	The value is not a valid length (BIC must be 8 or 11 chars; routing number 9 digits).
`INVALID_CHARSET`	BIC	The BIC contains characters outside the allowed alphanumeric set.
`INVALID_STRUCTURE`	BIC	The BIC's character positions don't match the ISO 9362 structure (e.g. digits in the institution-code positions).
`CHECKSUM_FAILED`	routing	The ABA mod-10 checksum did not pass.
`NO_ROUTE_FOUND`	route lookup	The BIC is structurally valid but no correspondent routes are on file for it.

Next steps

Bank Account Verification

Verify that a bank account exists and retrieve the holder's details

API Keys

Generate and manage the API keys these endpoints require

Errors

Complete error code reference

API Reference

Full request and response schemas for every endpoint

← PreviousCountry Requirements Next →Overview