REST API Documentation

Complete technical guide to integrate the BankValidor validation API into your applications.

The BankValidor REST API lets you validate international bank coordinates (IBAN, SWIFT/BIC, ABA Routing, UK Sort Code) via simple HTTP calls. Each validation performs up to 3 layers of verification: syntax, checksum, and official registry lookup.

Authentication

All API requests require a valid API key passed in the HTTP header. Get your API key by subscribing to a Starter or Business Pack.

X-API-Key: your_api_key_here

Keep your API key secure. Never expose it in client-side code or public repositories.

Base URL

All API endpoints are accessible via HTTPS only. Use the following base URL for all your requests.

https://bankvalidor.com/api/v1

Validation Endpoints

The API exposes dedicated endpoints for each type of bank coordinate. All endpoints accept POST requests with a JSON body.

POST/api/v1/validate/us

Validates a US ABA Routing Number + Account Number pair. Checks syntax, ABA checksum, and presence in the Federal Reserve directory.

Request Body

Field	Type	Required	Description
routing_number	string	Yes	ABA Routing Number (9 digits)
account_number	string	Yes	Bank account number (4-17 digits)

Query Parameters

Field	Type	Default	Description
enrich	boolean	false	Enrich with FDIC data (official name, address, GPS coordinates)

Example Request

curl -X POST https://bankvalidor.com/api/v1/validate/us?enrich=true \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_api_key_here" \
  -d '{
    "routing_number": "021000021",
    "account_number": "1234567890"
  }'

Example Response

{
  "status": "VALID",
  "confidence": "HIGH",
  "reliability_message": "...",
  "reliability_color": "green",
  "bank_info": {
    "name": "JPMORGAN CHASE BANK, NA",
    "city": "Tampa",
    "state": "FL",
    "active": true,
    "fdic_cert": "628",
    "headquarters_address": "1111 Polaris Parkway, Columbus, OH 43240",
    "coordinates": { "latitude": 40.1289, "longitude": -82.9813 },
    "enriched": true
  },
  "validation_details": {
    "routing_number": {
      "valid": true,
      "checksum_passed": true,
      "found_in_registry": true,
      "errors": [],
      "warnings": []
    },
    "account_number": {
      "valid": true,
      "format_correct": true,
      "length_valid": true,
      "errors": [],
      "warnings": []
    }
  },
  "warnings": [],
  "errors": [],
  "cache_hit": false,
  "response_time_ms": 42
}

POST/api/v1/validate/uk

Validates a UK Sort Code + Account Number pair. Checks format, modulus check, and presence in the Pay.UK directory.

Request Body

Field	Type	Required	Description
sort_code	string	Yes	UK Sort Code (format XX-XX-XX or 6 digits)
account_number	string	Yes	Bank account number (8 digits)

Example Request

curl -X POST https://bankvalidor.com/api/v1/validate/uk \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_api_key_here" \
  -d '{
    "sort_code": "20-00-00",
    "account_number": "12345678"
  }'

Example Response

{
  "status": "VALID",
  "confidence": "HIGH",
  "reliability_message": "...",
  "reliability_color": "green",
  "bank_info": {
    "name": "BARCLAYS BANK UK PLC",
    "branch_name": "Barclays Bank",
    "city": "London",
    "country_code": "GB",
    "active": true,
    "supports_faster_payments": true,
    "supports_bacs": true,
    "supports_chaps": true
  },
  "validation_details": {
    "sort_code": {
      "valid": true,
      "modulus_check_passed": true,
      "found_in_registry": true,
      "errors": [],
      "warnings": []
    },
    "account_number": {
      "valid": true,
      "format_correct": true,
      "length_valid": true,
      "errors": [],
      "warnings": []
    }
  },
  "warnings": [],
  "errors": [],
  "cache_hit": false,
  "response_time_ms": 38
}

POST/api/v1/validate/swift

Validates an international SWIFT/BIC code. Checks ISO 9362 format and presence in the SWIFT directory.

Request Body

Field	Type	Required	Description
bic	string	Yes	SWIFT/BIC code (8 or 11 characters)

Example Request

curl -X POST https://bankvalidor.com/api/v1/validate/swift \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_api_key_here" \
  -d '{
    "bic": "CHASUS33XXX"
  }'

Example Response

{
  "status": "VALID",
  "confidence": "HIGH",
  "reliability_message": "...",
  "reliability_color": "green",
  "bank_info": {
    "name": "JPMORGAN CHASE BANK, N.A.",
    "city": "New York",
    "country_code": "US",
    "country_name": "United States",
    "branch_code": "XXX",
    "active": true,
    "is_test_code": false
  },
  "validation_details": {
    "bic": {
      "valid": true,
      "format_correct": true,
      "found_in_registry": true,
      "country_valid": true,
      "errors": [],
      "warnings": []
    }
  },
  "warnings": [],
  "errors": [],
  "cache_hit": false,
  "response_time_ms": 25
}

POST/api/v1/validate/iban

Validates an international IBAN. Checks ISO 13616 syntax, check digits (mod-97), and country code.

Request Body

Field	Type	Required	Description
iban	string	Yes	Full IBAN number (15-34 characters)

Example Request

curl -X POST https://bankvalidor.com/api/v1/validate/iban \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_api_key_here" \
  -d '{
    "iban": "DE89370400440532013000"
  }'

Example Response

{
  "status": "VALID",
  "confidence": "HIGH",
  "reliability_message": "...",
  "reliability_color": "green",
  "bank_info": null,
  "validation_details": {
    "iban": {
      "valid": true,
      "syntax_valid": true,
      "checksum_valid": true,
      "country_recognized": true,
      "bban_format_valid": true,
      "is_sepa": true,
      "country_code": "DE",
      "country_name": "Germany",
      "check_digits": "89",
      "bban": "370400440532013000",
      "bank_code": "37040044",
      "account_number": "0532013000",
      "errors": [],
      "warnings": []
    }
  },
  "warnings": [],
  "errors": [],
  "cache_hit": false,
  "response_time_ms": 15
}

POST/api/v1/validate/iban/detailed

Detailed IBAN validation with full breakdown, bank information (BIC, name, address), and SEPA service status (SCT, SDD, B2B, SCT Inst).

Request Body

Field	Type	Required	Description
iban	string	Yes	Full IBAN number (15-34 characters)

Example Request

curl -X POST https://bankvalidor.com/api/v1/validate/iban/detailed \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_api_key_here" \
  -d '{
    "iban": "FR7640618803220004034973118"
  }'

Example Response

{
  "iban": "FR7640618803220004034973118",
  "is_valid": true,
  "country": {
    "code": "FR",
    "name": "France",
    "iban_length": 27
  },
  "checks": {
    "length_valid": true,
    "checksum_valid": true,
    "bank_code_valid": true,
    "account_checksum_valid": true
  },
  "bank_info": {
    "bic": "BOUSFRPP",
    "name": "BOURSORAMA",
    "address": "18 Quai du Point du Jour, 92100 Boulogne-Billancourt"
  },
  "sepa": {
    "member": true,
    "sct": true,
    "sdd": true,
    "b2b": true,
    "sct_inst": true
  }
}

GET/api/v1/health

Checks API status and service connectivity (database, cache). Useful for monitoring and health checks.

Example Request

curl https://bankvalidor.com/api/v1/health \
  -H "X-API-Key: your_api_key_here"

Example Response

{
  "status": "healthy",
  "version": "1.0.0",
  "timestamp": "2025-01-15T10:30:00Z",
  "database": "connected",
  "cache": "connected"
}

Error Handling

The API uses standard HTTP codes to indicate request results. In case of an error, the response body contains details about the problem.

Code	Status	Description
200	OK	Request processed successfully. The validation result is in the response body.
400	Bad Request	The request is malformed. Check the JSON format and required fields.
422	Unprocessable Entity	The provided data fails Pydantic schema validation.
429	Too Many Requests	Rate limit exceeded. Wait before retrying (see X-RateLimit-Reset header).
500	Internal Server Error	Internal server error. Contact support if the problem persists.

// Error response example

{
  "detail": [
    {
      "loc": ["body", "routing_number"],
      "msg": "Routing number must contain only digits",
      "type": "value_error"
    }
  ]
}

Rate Limits

The API enforces per-API-key rate limits to ensure service availability. Response headers contain quota information.

Header	Description
X-RateLimit-Limit	Maximum number of requests allowed per time window
X-RateLimit-Remaining	Number of requests remaining in the current window
X-RateLimit-Reset	Unix timestamp indicating when the counter resets

Rate limits depend on your API pack. Starter Pack: 100 req/min. Business Pack: 500 req/min. Contact us for higher needs.

REST API Documentation

Authentication

Base URL

Validation Endpoints

Request Body

Query Parameters

Example Request

Example Response

Request Body

Example Request

Example Response

Request Body

Example Request

Example Response

Request Body

Example Request

Example Response

Request Body

Example Request

Example Response

Example Request

Example Response

Error Handling

Rate Limits

Related Documentation

Bulk CSV Validation

Webhooks