Documentation API REST

Guide technique complet pour intégrer l'API de validation bancaire BankValidor dans vos applications.

L'API REST BankValidor permet de valider des coordonnées bancaires internationales (IBAN, SWIFT/BIC, ABA Routing, Sort Code UK) via des appels HTTP simples. Chaque validation effectue jusqu'à 3 couches de vérification : syntaxe, checksum et registre officiel.

Authentification

Toutes les requêtes API nécessitent une clé API valide transmise dans l'en-tête HTTP. Obtenez votre clé API en souscrivant à un Pack Starter ou Business.

X-API-Key: your_api_key_here

Conservez votre clé API en sécurité. Ne l'exposez jamais dans du code côté client ou dans des dépôts publics.

URL de base

Tous les endpoints de l'API sont accessibles via HTTPS uniquement. Utilisez l'URL de base suivante pour toutes vos requêtes.

https://bankvalidor.com/api/v1

Endpoints de validation

L'API expose des endpoints dédiés pour chaque type de coordonnée bancaire. Tous les endpoints acceptent des requêtes POST avec un corps JSON.

POST/api/v1/validate/us

Valide un couple ABA Routing Number + Account Number américain. Vérifie la syntaxe, le checksum ABA et la présence dans le répertoire de la Federal Reserve.

Corps de la requête

Champ	Type	Requis	Description
routing_number	string	Oui	ABA Routing Number (9 chiffres)
account_number	string	Oui	Numéro de compte bancaire (4-17 chiffres)

Paramètres de requête

Champ	Type	Par défaut	Description
enrich	boolean	false	Enrichir avec les données FDIC (nom officiel, adresse, coordonnées GPS)

Exemple de requête

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"
  }'

Exemple de réponse

{
  "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

Valide un couple Sort Code + Account Number britannique. Vérifie le format, le modulus check et la présence dans le répertoire Pay.UK.

Corps de la requête

Champ	Type	Requis	Description
sort_code	string	Oui	Sort Code britannique (format XX-XX-XX ou 6 chiffres)
account_number	string	Oui	Numéro de compte bancaire (8 chiffres)

Exemple de requête

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"
  }'

Exemple de réponse

{
  "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

Valide un code SWIFT/BIC international. Vérifie le format ISO 9362 et la présence dans l'annuaire SWIFT.

Corps de la requête

Champ	Type	Requis	Description
bic	string	Oui	Code SWIFT/BIC (8 ou 11 caractères)

Exemple de requête

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"
  }'

Exemple de réponse

{
  "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

Valide un IBAN international. Vérifie la syntaxe ISO 13616, les chiffres de contrôle (mod-97) et le code pays.

Corps de la requête

Champ	Type	Requis	Description
iban	string	Oui	Numéro IBAN complet (15-34 caractères)

Exemple de requête

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"
  }'

Exemple de réponse

{
  "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

Validation IBAN détaillée avec décomposition complète, informations bancaires (BIC, nom, adresse) et statut des services SEPA (SCT, SDD, B2B, SCT Inst).

Corps de la requête

Champ	Type	Requis	Description
iban	string	Oui	Numéro IBAN complet (15-34 caractères)

Exemple de requête

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"
  }'

Exemple de réponse

{
  "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

Vérifie l'état de l'API et la connectivité aux services (base de données, cache). Utile pour le monitoring et les health checks.

Exemple de requête

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

Exemple de réponse

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

Gestion des erreurs

L'API utilise les codes HTTP standards pour indiquer le résultat d'une requête. En cas d'erreur, le corps de la réponse contient des détails sur le problème.

Code	Statut	Description
200	OK	Requête traitée avec succès. Le résultat de la validation est dans le corps de la réponse.
400	Bad Request	La requête est mal formée. Vérifiez le format JSON et les champs requis.
422	Unprocessable Entity	Les données fournies ne passent pas la validation de schéma Pydantic.
429	Too Many Requests	Limite de débit dépassée. Attendez avant de réessayer (voir en-tête X-RateLimit-Reset).
500	Internal Server Error	Erreur interne du serveur. Contactez le support si le problème persiste.

// Error response example

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

Limites de débit

L'API applique des limites de débit par clé API pour garantir la disponibilité du service. Les en-têtes de réponse contiennent les informations de quota.

En-tête	Description
X-RateLimit-Limit	Nombre maximum de requêtes autorisées par fenêtre de temps
X-RateLimit-Remaining	Nombre de requêtes restantes dans la fenêtre courante
X-RateLimit-Reset	Timestamp Unix indiquant la réinitialisation du compteur

Les limites de débit dépendent de votre pack API. Pack Starter : 100 req/min. Pack Business : 500 req/min. Contactez-nous pour des besoins supérieurs.

Documentation associée

Validation CSV en masse

Validez des milliers de coordonnées bancaires en une seule requête via l'upload CSV.

Consulter →

Webhooks

Recevez des notifications en temps réel lors de la complétion de vos validations.

Consulter →

Dernière mise à jour : février 2026