API Reference

Complete email checker API reference. Endpoints, parameters, response codes for email verification and validation.

L'API BillionVerify est un service RESTful qui fournit de puissantes capacités de vérification d'emails. Toutes les requêtes API doivent être effectuées via HTTPS.

URL de Base

https://api.billionverify.com/v1

Spécification OpenAPI

La spécification complète de l'API est disponible au format OpenAPI 3.0 :

OpenAPI YAML : https://api.billionverify.com/openapi.yaml
Documentation API Interactive : https://api.billionverify.com/docs

Vous pouvez importer la spécification OpenAPI dans des outils comme Postman, Insomnia, ou l'utiliser pour générer des bibliothèques client.

Authentification

Toutes les requêtes API nécessitent une authentification utilisant un jeton Bearer dans l'en-tête Authorization :

BV-API-KEY: YOUR_API_KEY

Obtenez votre clé API depuis le tableau de bord BillionVerify.

Exemple

curl -X POST https://api.billionverify.com/v1/verify/single \
  -H "BV-API-KEY: bv_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{"email": "test@example.com"}'

Limites de Taux

Plan	Requêtes/Heure	Requêtes/Jour
Gratuit	100	1 000
Débutant	1 000	10 000
Professionnel	10 000	100 000
Entreprise	Personnalisé	Personnalisé

Les informations de limite de taux sont incluses dans les en-têtes de réponse :

En-tête	Description
`X-RateLimit-Limit`	Nombre maximum de requêtes autorisées
`X-RateLimit-Remaining`	Requêtes restantes dans la fenêtre
`X-RateLimit-Reset`	Horodatage Unix de réinitialisation de la limite

Lorsque la limite de taux est atteinte, vous recevrez une réponse 429 Too Many Requests :

{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Rate limit exceeded. Please try again later.",
    "retry_after": 3600
  }
}

Points de Terminaison

Vérification d'Email Unique

Vérifiez une seule adresse email avec des résultats détaillés.

POST /verify/single

Requête

{
  "email": "user@example.com",
  "check_smtp": true
}

Paramètres

Paramètre	Type	Requis	Défaut	Description
`email`	string	Oui	-	Adresse email à vérifier
`smtp_check`	boolean	Non	`true`	Effectuer une vérification de boîte aux lettres SMTP
`timeout`	integer	Non	`5000`	Délai d'expiration de la requête en millisecondes (max : 30000)

Réponse

{
  "email": "user@example.com",
  "status": "valid",
  "result": {
    "deliverable": true,
    "valid_format": true,
    "valid_domain": true,
    "valid_mx": true,
    "disposable": false,
    "role": false,
    "catchall": false,
    "free": false,
    "smtp_valid": true
  },
  "score": 0.95,
  "reason": null,
  "credits_used": 1
}

Champs de Réponse

Champ	Type	Description
`email`	string	L'adresse email vérifiée
`status`	string	Statut de vérification : `valid`, `invalid`, `unknown`, `catchall`
`result`	object	Résultats de vérification détaillés
`score`	number	Score de confiance (0.0 - 1.0)
`reason`	string	Raison du statut invalide/inconnu (nullable)
`credits_used`	integer	Nombre de crédits consommés

Champs de l'Objet Result

Champ	Type	Description
`deliverable`	boolean	Indique si l'email peut recevoir des messages
`valid_format`	boolean	Indique si l'email a une syntaxe valide
`valid_domain`	boolean	Indique si le domaine existe
`valid_mx`	boolean	Indique si le domaine a des enregistrements MX
`disposable`	boolean	Indique si l'email provient d'un service jetable
`role`	boolean	Indique si l'email est basé sur un rôle (info@, support@)
`catchall`	boolean	Indique si le domaine accepte tous les emails
`free`	boolean	Indique si l'email provient d'un fournisseur gratuit
`smtp_valid`	boolean	Indique si la vérification SMTP a réussi

Vérification d'Emails en Masse

Vérifiez plusieurs adresses email de manière synchrone. Idéal pour les petits lots (maximum 50 emails).

POST /verify/bulk

Requête

{
  "emails": [
    "user1@example.com",
    "user2@example.com",
    "user3@example.com"
  ],
  "check_smtp": true
}

Paramètres

Paramètre	Type	Requis	Défaut	Description
`emails`	array	Oui	-	Tableau d'adresses email (max : 50)
`check_smtp`	boolean	Non	`true`	Effectuer une vérification SMTP

Réponse

{
  "success": true,
  "code": "0",
  "message": "Success",
  "data": {
    "results": [
      {
        "email": "user1@example.com",
        "status": "valid",
        "score": 0.95,
        "is_deliverable": true,
        "is_disposable": false,
        "is_catchall": false,
        "is_role": false,
        "is_free": false,
        "domain": "example.com",
        "smtp_check": true,
        "reason": null,
        "credits_used": 1
      }
    ],
    "total_emails": 3,
    "valid_emails": 2,
    "invalid_emails": 1,
    "credits_used": 3,
    "process_time": 2500
  }
}

Vérifier les Crédits

Obtenez le solde de crédits actuel et les informations d'utilisation.

GET /credits

Réponse

{
  "success": true,
  "code": "0",
  "message": "Success",
  "data": {
    "account_id": "abc123",
    "api_key_id": "key_xyz",
    "api_key_name": "Default API Key",
    "credits_balance": 9500,
    "credits_consumed": 500,
    "credits_added": 10000,
    "last_updated": "2026-02-04T10:30:00Z"
  }
}

Vérification par Fichier

Téléchargez un fichier CSV ou Excel pour une vérification d'email asynchrone. Idéal pour les grandes listes.

POST /verify/file

Requête

curl -X POST https://api.billionverify.com/v1/verify/file \
  -H "BV-API-KEY: sk_your_api_key" \
  -F "file=@emails.csv"

Paramètres

Paramètre	Type	Requis	Description
`file`	file	Oui	Fichier CSV ou Excel (max : 20 Mo, 100 000 lignes)
`email_column`	string	Non	Nom de la colonne contenant les emails (détection automatique si non spécifié)

Formats de Fichiers Supportés

CSV (.csv)
Excel (.xlsx, .xls)
Texte (.txt) - un email par ligne

Réponse

{
  "success": true,
  "code": "0",
  "message": "Success",
  "data": {
    "task_id": "7143874e-21c5-43c1-96f3-2b52ea41ae6a",
    "status": "pending",
    "message": "File uploaded successfully, processing started",
    "file_name": "emails.csv",
    "file_size": 45678,
    "estimated_count": 1000,
    "unique_emails": 950,
    "total_rows": 1000,
    "email_column": "email",
    "status_url": "/v1/verify/file/7143874e-21c5-43c1-96f3-2b52ea41ae6a",
    "created_at": "2026-02-04T10:30:00Z"
  }
}

Obtenir le Statut de la Tâche Fichier

Vérifiez le statut d'une tâche de vérification de fichier.

GET /verify/file/{job_id}

Réponse (En Cours)

{
  "success": true,
  "code": "0",
  "message": "Success",
  "data": {
    "job_id": "7143874e-21c5-43c1-96f3-2b52ea41ae6a",
    "status": "processing",
    "file_name": "emails.csv",
    "total_emails": 1000,
    "processed_emails": 450,
    "progress_percent": 45,
    "valid_emails": 380,
    "invalid_emails": 50,
    "unknown_emails": 20,
    "created_at": "2026-02-04T10:30:00Z"
  }
}

Réponse (Terminée)

{
  "success": true,
  "code": "0",
  "message": "Success",
  "data": {
    "job_id": "7143874e-21c5-43c1-96f3-2b52ea41ae6a",
    "status": "completed",
    "file_name": "emails.csv",
    "total_emails": 1000,
    "processed_emails": 1000,
    "progress_percent": 100,
    "valid_emails": 850,
    "invalid_emails": 100,
    "unknown_emails": 30,
    "role_emails": 15,
    "catchall_emails": 5,
    "disposable_emails": 0,
    "credits_used": 970,
    "process_time_seconds": 125.5,
    "result_file_path": "results/2026/02/04/result_xxx.csv",
    "download_url": "/v1/verify/file/7143874e-21c5-43c1-96f3-2b52ea41ae6a/results",
    "created_at": "2026-02-04T10:30:00Z",
    "completed_at": "2026-02-04T10:32:05Z"
  }
}

Télécharger les Résultats

Téléchargez les résultats de vérification d'une tâche terminée.

GET /verify/file/{job_id}/results

Paramètres de Requête

Paramètre	Type	Défaut	Description
`valid`	boolean	-	Inclure les emails valides
`invalid`	boolean	-	Inclure les emails invalides
`catchall`	boolean	-	Inclure les emails catch-all
`role`	boolean	-	Inclure les emails de rôle
`unknown`	boolean	-	Inclure les emails inconnus

Sans paramètres de filtre, retourne le fichier de résultats complet. Avec des filtres, retourne un CSV avec uniquement les emails correspondants.

Exemple : Télécharger les Emails Livrables

curl -o deliverable.csv \
  "https://api.billionverify.com/v1/verify/file/{job_id}/results?valid=true&catchall=true&role=true" \
  -H "BV-API-KEY: sk_your_api_key"

Webhooks

Recevez des notifications en temps réel lorsque les tâches de vérification de fichiers sont terminées.

Créer un Webhook

POST /webhooks

Requête

{
  "url": "https://your-app.com/webhooks/billionverify",
  "events": ["file.completed", "file.failed"]
}

Paramètres

Paramètre	Type	Requis	Description
`url`	string	Oui	URL HTTPS pour recevoir les notifications webhook
`events`	array	Oui	Événements auxquels s'abonner

Réponse

{
  "success": true,
  "code": "0",
  "message": "Success",
  "data": {
    "id": "673f3bff-81ea-4730-9cef-af1eb7f134bf",
    "url": "https://your-app.com/webhooks/billionverify",
    "events": ["file.completed", "file.failed"],
    "secret": "5c609e6893ab3b65ce8940549a030bc165762fe171e0b38f880bd570099619bf",
    "is_active": true,
    "created_at": "2026-02-04T10:30:00Z",
    "updated_at": "2026-02-04T10:30:00Z"
  }
}

Important : Le secret n'est renvoyé que lors de la création du webhook. Conservez-le en sécurité - vous en aurez besoin pour vérifier les signatures des webhooks.

Lister les Webhooks

GET /webhooks

Réponse

{
  "success": true,
  "code": "0",
  "message": "Success",
  "data": {
    "webhooks": [
      {
        "id": "673f3bff-81ea-4730-9cef-af1eb7f134bf",
        "url": "https://your-app.com/webhooks/billionverify",
        "events": ["file.completed", "file.failed"],
        "is_active": true,
        "created_at": "2026-02-04T10:30:00Z",
        "updated_at": "2026-02-04T10:30:00Z"
      }
    ],
    "total": 1
  }
}

Supprimer un Webhook

DELETE /webhooks/{webhook_id}

Réponse

{
  "success": true,
  "code": "0",
  "message": "Success",
  "data": {
    "message": "Webhook deleted successfully",
    "webhook_id": "673f3bff-81ea-4730-9cef-af1eb7f134bf"
  }
}

Événements Webhook

Événement	Description
`file.completed`	Tâche de vérification de fichier terminée avec succès
`file.failed`	Tâche de vérification de fichier échouée

Charge Utile Webhook

Lorsqu'un événement se produit, nous envoyons une requête POST à votre URL webhook :

{
  "event": "file.completed",
  "timestamp": "2026-02-04T10:35:00Z",
  "data": {
    "job_id": "7143874e-21c5-43c1-96f3-2b52ea41ae6a",
    "file_name": "emails.csv",
    "total_emails": 1000,
    "valid_emails": 850,
    "invalid_emails": 100,
    "role_emails": 30,
    "catchall_emails": 10,
    "unknown_emails": 10,
    "disposable_emails": 0,
    "credits_used": 990,
    "process_time_seconds": 125.5,
    "result_file_path": "results/2026/02/04/result_xxx.csv",
    "download_url": ""
  }
}

En-têtes Webhook

En-tête	Description
`X-Webhook-Event`	Type d'événement (ex. `file.completed`)
`X-Webhook-Signature`	Signature HMAC-SHA256 pour vérification
`X-Webhook-Timestamp`	Horodatage Unix d'envoi du webhook
`User-Agent`	`BillionVerify-Webhook/1.0`

Vérification des Signatures Webhook

Pour vérifier qu'un webhook provient d'BillionVerify, calculez la signature HMAC-SHA256 :

const crypto = require('crypto');

function verifyWebhookSignature(payload, signature, secret) {
  const expectedSignature = 'sha256=' +
    crypto.createHmac('sha256', secret)
      .update(payload)
      .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expectedSignature)
  );
}

import hmac
import hashlib

def verify_webhook_signature(payload: bytes, signature: str, secret: str) -> bool:
    expected = 'sha256=' + hmac.new(
        secret.encode(),
        payload,
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(signature, expected)

Statut de Vérification

Statut	Score	Signification	Action Recommandée
`valid`	0.9+	L'email existe et peut recevoir des messages	Envoi sécurisé
`invalid`	0.1	L'email n'existe pas ou ne peut pas recevoir	Retirer de la liste
`unknown`	0.5	Impossible de déterminer la validité	Réessayer plus tard ou utiliser avec prudence
`risky`	0.4	L'email peut avoir des problèmes de livraison	Utiliser avec prudence, surveiller les rebonds
`disposable`	0.3	L'email provient d'un service jetable	Envisager de retirer
`catchall`	0.7	Le domaine accepte tous les emails (catch-all)	Surveiller les rebonds
`role`	0.6	Email basé sur un rôle (info@, support@)	Généralement livrable, peut avoir un engagement plus faible

Réponses d'Erreur

Toutes les erreurs suivent un format cohérent :

{
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable error message",
    "details": "Additional context (optional)"
  }
}

Codes de Statut HTTP

Code	Description
`200`	Succès
`400`	Requête Invalide - Paramètres invalides
`401`	Non Autorisé - Clé API invalide ou manquante
`403`	Interdit - Permissions insuffisantes
`404`	Non Trouvé - La ressource n'existe pas
`429`	Trop de Requêtes - Limite de taux dépassée
`500`	Erreur Serveur Interne
`503`	Service Non Disponible

Codes d'Erreur

Code	Statut HTTP	Description
`INVALID_API_KEY`	401	La clé API est invalide ou manquante
`RATE_LIMIT_EXCEEDED`	429	Trop de requêtes
`INSUFFICIENT_CREDITS`	403	Pas assez de crédits
`INVALID_EMAIL`	400	Le format de l'email est invalide
`INVALID_REQUEST`	400	Le corps de la requête est malformé
`JOB_NOT_FOUND`	404	ID de tâche en masse non trouvé
`TIMEOUT`	504	Délai de vérification expiré

Meilleures Pratiques

1. Utiliser des Variables d'Environnement

Ne codez jamais les clés API en dur :

// Bien
const apiKey = process.env.BV_API_KEY;

// Mal - ne faites pas cela
const apiKey = 'bv_live_xxx';

2. Gérer les Limites de Taux

Implémentez un backoff exponentiel :

async function verifyWithRetry(email, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await verify(email);
    } catch (error) {
      if (error.code === 'RATE_LIMIT_EXCEEDED') {
        await sleep(Math.pow(2, i) * 1000);
        continue;
      }
      throw error;
    }
  }
}

3. Utiliser le Mode en Masse pour Plusieurs Emails

Pour vérifier plus de 10 emails, utilisez le point de terminaison en masse :

// Bien - un seul appel API
const job = await client.verifyBulk(emails);

// Mal - beaucoup d'appels individuels
for (const email of emails) {
  await client.verify(email);
}

4. Implémenter des Webhooks pour les Tâches en Masse

N'interrogez pas constamment ; utilisez des webhooks :

// Soumettre avec webhook
const job = await client.verifyBulk(emails, {
  webhookUrl: 'https://your-app.com/webhook',
});

API Reference

Node.js

Python

Go

PHP

Java

TypeScript

Guide de Démarrage Rapide

Types de Vérification

Guides d'Intégration

On this page