BillionVerify API Skill

Call the BillionVerify API to verify email addresses — single, batch, or bulk file processing.

Setup

API key must be set in environment variable BILLIONVERIFY_API_KEY. Get your API key at: https://billionverify.com/auth/sign-in?next=/home/api-keys

Base URL

https://api.billionverify.com

Authentication

All requests require an API key header:

-H "BV-API-KEY: $BILLIONVERIFY_API_KEY"

Endpoints

Verify Single Email

curl -X POST "https://api.billionverify.com/v1/verify/single" \
  -H "BV-API-KEY: $BILLIONVERIFY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "check_smtp": true
  }'

Response includes: status (valid/invalid/unknown/risky/disposable/catchall/role), score (0-1), is_deliverable, is_disposable, is_catchall, is_role, is_free, domain, domain_age, mx_records, domain_reputation, smtp_check, reason, suggestion, response_time, credits_used.

Verify Batch Emails (max 50)

curl -X POST "https://api.billionverify.com/v1/verify/bulk" \
  -H "BV-API-KEY: $BILLIONVERIFY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "emails": ["[email protected]", "[email protected]"],
    "check_smtp": true
  }'

Upload File for Bulk Verification

Upload CSV, Excel (.xlsx/.xls), or TXT files (max 20MB, 100,000 emails):

curl -X POST "https://api.billionverify.com/v1/verify/file" \
  -H "BV-API-KEY: $BILLIONVERIFY_API_KEY" \
  -F "file=@/path/to/emails.csv" \
  -F "check_smtp=true" \
  -F "email_column=email" \
  -F "preserve_original=true"

Returns task_id for tracking the async job.

Get File Job Status

Supports long-polling with timeout parameter (0-300 seconds):

curl -X GET "https://api.billionverify.com/v1/verify/file/{task_id}?timeout=30" \
  -H "BV-API-KEY: $BILLIONVERIFY_API_KEY"

Status values: pending, processing, completed, failed.

Download Verification Results

Without filters returns redirect to full result file. With filters returns CSV of matching emails (filters combined with OR logic):

curl -X GET "https://api.billionverify.com/v1/verify/file/{task_id}/results?valid=true&invalid=true" \
  -H "BV-API-KEY: $BILLIONVERIFY_API_KEY" \
  -L -o results.csv

Filter parameters: valid, invalid, catchall, role, unknown, disposable, risky.

Get Credit Balance

curl -X GET "https://api.billionverify.com/v1/credits" \
  -H "BV-API-KEY: $BILLIONVERIFY_API_KEY"

Create Webhook

curl -X POST "https://api.billionverify.com/v1/webhooks" \
  -H "BV-API-KEY: $BILLIONVERIFY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-app.com/webhooks/billionverify",
    "events": ["file.completed", "file.failed"]
  }'

The secret is only returned on creation — store it securely.