API Reference

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

De BillionVerify API is een RESTful service die krachtige e-mailverificatiemogelijkheden biedt. Alle API-verzoeken moeten via HTTPS worden gedaan.

Basis-URL

https://api.billionverify.com/v1

OpenAPI-specificatie

De volledige API-specificatie is beschikbaar in OpenAPI 3.0-formaat:

OpenAPI YAML: https://api.billionverify.com/openapi.yaml
Interactieve API-documentatie: https://api.billionverify.com/docs

U kunt de OpenAPI-specificatie importeren in tools zoals Postman, Insomnia, of gebruiken om clientbibliotheken te genereren.

Authenticatie

Alle API-verzoeken vereisen authenticatie met behulp van een Bearer-token in de Authorization-header:

BV-API-KEY: YOUR_API_KEY

Verkrijg uw API-sleutel via het BillionVerify-dashboard.

Voorbeeld

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

Snelheidslimieten

Abonnement	Verzoeken/uur	Verzoeken/dag
Gratis	100	1.000
Starter	1.000	10.000
Professional	10.000	100.000
Enterprise	Aangepast	Aangepast

Informatie over snelheidslimieten is opgenomen in de antwoordheaders:

Header	Beschrijving
`X-RateLimit-Limit`	Maximum toegestane verzoeken
`X-RateLimit-Remaining`	Resterende verzoeken in venster
`X-RateLimit-Reset`	Unix-timestamp wanneer limiet reset

Bij overschrijding van de snelheidslimiet ontvangt u een 429 Too Many Requests-antwoord:

{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Snelheidslimiet overschreden. Probeer het later opnieuw.",
    "retry_after": 3600
  }
}

Eindpunten

Enkelvoudige e-mailverificatie

Verifieer een enkel e-mailadres met gedetailleerde resultaten.

POST /verify/single

Verzoek

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

Parameters

Parameter	Type	Verplicht	Standaard	Beschrijving
`email`	string	Ja	-	Te verifiëren e-mailadres
`smtp_check`	boolean	Nee	`true`	SMTP-mailboxverificatie uitvoeren
`timeout`	integer	Nee	`5000`	Verzoek-timeout in milliseconden (max: 30000)

Antwoord

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

Antwoordvelden

Veld	Type	Beschrijving
`email`	string	Het geverifieerde e-mailadres
`status`	string	Verificatiestatus: `valid`, `invalid`, `unknown`, `catchall`
`result`	object	Gedetailleerde verificatieresultaten
`score`	number	Betrouwbaarheidsscore (0.0 - 1.0)
`reason`	string	Reden voor invalid/unknown status (nullable)
`credits_used`	integer	Aantal verbruikte credits

Resultaatobjectvelden

Veld	Type	Beschrijving
`deliverable`	boolean	Of e-mail berichten kan ontvangen
`valid_format`	boolean	Of e-mail geldige syntaxis heeft
`valid_domain`	boolean	Of domein bestaat
`valid_mx`	boolean	Of domein MX-records heeft
`disposable`	boolean	Of e-mail van wegwerpdienst is
`role`	boolean	Of e-mail rol-gebaseerd is (info@, support@)
`catchall`	boolean	Of domein alle e-mails accepteert
`free`	boolean	Of e-mail van gratis provider is
`smtp_valid`	boolean	Of SMTP-verificatie geslaagd is

Bulk e-mailverificatie

Verifieer meerdere e-mailadressen synchroon. Ideaal voor kleine batches (maximaal 50 e-mails).

POST /verify/bulk

Verzoek

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

Parameters

Parameter	Type	Verplicht	Standaard	Beschrijving
`emails`	array	Ja	-	Array van e-mailadressen (max: 50)
`check_smtp`	boolean	Nee	`true`	SMTP-verificatie uitvoeren

Antwoord

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

Credits controleren

Haal huidige creditsaldo en gebruiksinformatie op.

GET /credits

Antwoord

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

Bestandsupload verificatie

Upload een CSV- of Excel-bestand voor asynchrone e-mailverificatie. Ideaal voor grote lijsten.

POST /verify/file

Verzoek

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

Parameters

Parameter	Type	Verplicht	Beschrijving
`file`	file	Ja	CSV- of Excel-bestand (max: 20MB, 100.000 rijen)
`email_column`	string	Nee	Kolomnaam met e-mails (automatische detectie indien niet opgegeven)

Ondersteunde bestandsformaten

CSV (.csv)
Excel (.xlsx, .xls)
Tekst (.txt) - één e-mail per regel

Antwoord

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

Bestandstaakstatus ophalen

Controleer de status van een bestandsverificatietaak.

GET /verify/file/{job_id}

Antwoord (in uitvoering)

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

Antwoord (voltooid)

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

Resultaten downloaden

Download de verificatieresultaten van een voltooide taak.

GET /verify/file/{job_id}/results

Queryparameters

Parameter	Type	Standaard	Beschrijving
`valid`	boolean	-	Geldige e-mails opnemen
`invalid`	boolean	-	Ongeldige e-mails opnemen
`catchall`	boolean	-	Catch-all e-mails opnemen
`role`	boolean	-	Rol-e-mails opnemen
`unknown`	boolean	-	Onbekende e-mails opnemen

Zonder filterparameters wordt het volledige resultaatbestand geretourneerd. Met filters wordt een CSV met alleen overeenkomende e-mails geretourneerd.

Voorbeeld: Afleverbare e-mails downloaden

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

Ontvang real-time meldingen wanneer bestandsverificatietaken zijn voltooid.

Webhook aanmaken

POST /webhooks

Verzoek

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

Parameters

Parameter	Type	Verplicht	Beschrijving
`url`	string	Ja	HTTPS-URL om webhook-meldingen te ontvangen
`events`	array	Ja	Evenementen om op te abonneren

Antwoord

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

Belangrijk: Het secret wordt alleen geretourneerd bij het aanmaken van de webhook. Bewaar het veilig - je hebt het nodig om webhook-handtekeningen te verifiëren.

Webhooks weergeven

GET /webhooks

Antwoord

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

Webhook verwijderen

DELETE /webhooks/{webhook_id}

Antwoord

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

Webhook-events

Event	Beschrijving
`file.completed`	Bestandsverificatietaak succesvol voltooid
`file.failed`	Bestandsverificatietaak mislukt

Webhook-payload

Wanneer een event plaatsvindt, sturen we een POST-verzoek naar uw webhook-URL:

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

Webhook-headers

Header	Beschrijving
`X-Webhook-Event`	Eventtype (bijv. `file.completed`)
`X-Webhook-Signature`	HMAC-SHA256-handtekening voor verificatie
`X-Webhook-Timestamp`	Unix-tijdstempel wanneer webhook is verzonden
`User-Agent`	`BillionVerify-Webhook/1.0`

Webhook-handtekeningen verifiëren

Om te controleren of een webhook van BillionVerify komt, bereken de HMAC-SHA256-handtekening:

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)

Verificatiestatus

Status	Score	Betekenis	Aanbevolen actie
`valid`	0.9+	E-mail bestaat en kan berichten ontvangen	Veilig om te verzenden
`invalid`	0.1	E-mail bestaat niet of kan niet ontvangen	Verwijderen van lijst
`unknown`	0.5	Kon geldigheid niet bepalen	Later opnieuw proberen of voorzichtig zijn
`risky`	0.4	E-mail kan bezorgproblemen hebben	Voorzichtig zijn, bounces monitoren
`disposable`	0.3	E-mail is van wegwerpdienst	Overweeg te verwijderen
`catchall`	0.7	Domein accepteert alle e-mails (catch-all)	Controleren op bounces
`role`	0.6	Rol-gebaseerde e-mail (info@, support@)	Meestal afleverbaar, kan lagere engagement hebben

Foutantwoorden

Alle fouten volgen een consistent formaat:

{
  "error": {
    "code": "ERROR_CODE",
    "message": "Leesbare foutmelding",
    "details": "Aanvullende context (optioneel)"
  }
}

HTTP-statuscodes

Code	Beschrijving
`200`	Succes
`400`	Bad Request - Ongeldige parameters
`401`	Unauthorized - Ongeldige of ontbrekende API-sleutel
`403`	Forbidden - Onvoldoende rechten
`404`	Not Found - Resource bestaat niet
`429`	Too Many Requests - Snelheidslimiet overschreden
`500`	Internal Server Error
`503`	Service Unavailable

Foutcodes

Code	HTTP-status	Beschrijving
`INVALID_API_KEY`	401	API-sleutel is ongeldig of ontbreekt
`RATE_LIMIT_EXCEEDED`	429	Te veel verzoeken
`INSUFFICIENT_CREDITS`	403	Niet genoeg credits
`INVALID_EMAIL`	400	E-mailformaat is ongeldig
`INVALID_REQUEST`	400	Verzoekbody is onjuist geformatteerd
`JOB_NOT_FOUND`	404	Bulktaak-ID niet gevonden
`TIMEOUT`	504	Verificatie time-out

Best practices

1. Gebruik omgevingsvariabelen

Codeer API-sleutels nooit hard:

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

// Fout - doe dit niet
const apiKey = 'bv_live_xxx';

2. Snelheidslimieten afhandelen

Implementeer exponential backoff:

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. Gebruik bulk voor meerdere e-mails

Gebruik voor het verifiëren van meer dan 10 e-mails het bulk-eindpunt:

// Goed - enkele API-aanroep
const job = await client.verifyBulk(emails);

// Fout - veel individuele aanroepen
for (const email of emails) {
  await client.verify(email);
}

4. Implementeer webhooks voor bulktaken

Poll niet constant; gebruik webhooks:

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

API Reference

Node.js

Python

Go

PHP

Java

TypeScript

Snelstartgids

Verificatietypes

Integratiegidsen

On this page