billionverify

# BillionVerify API Skill Call the [BillionVerify](https://billionverify.com/) 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: ```bash -H "BV-API-KEY: $BILLIONVERIFY_API_KEY" ``` ## Endpoints ### Verify Single Email ```bash curl -X POST "https://api.billionverify.com/v1/verify/single" \ -H "BV-API-KEY: $BILLIONVERIFY_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "email": "user@example.com", "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) ```bash curl -X POST "https://api.billionverify.com/v1/verify/bulk" \ -H "BV-API-KEY: $BILLIONVERIFY_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "emails": ["user1@example.com", "user2@example.com"], "check_smtp": true }' ``` ### Upload File for Bulk Verification Upload CSV, Excel (.xlsx/.xls), or TXT files (max 20MB, 100,000 emails): ```bash 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): ```bash 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): ```bash 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 ```bash curl -X GET "https://api.billionverify.com/v1/credits" \ -H "BV-API-KEY: $BILLIONVERIFY_API_KEY" ``` ### Create Webhook ```bash 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. ### List Webhooks ```bash curl -X GET "https://api.billionverify.com/v1/webhooks" \ -H "BV-API-KEY: $BILLIONVERIFY_API_KEY" ``` ### Delete Webhook ```bash curl -X DELETE "https://api.billionverify.com/v1/webhooks/{webhook_id}" \ -H "BV-API-KEY: $BILLIONVERIFY_API_KEY" ``` ### Health Check (no auth required) ```bash curl -X GET "https://api.billionverify.com/health" ``` ## Credits & Billing - **Invalid** / **Unknown**: 0 credits (free) - All other statuses (valid, risky, disposable, catchall, role): 1 credit each ## Rate Limits | Endpoint | Limit | |----------|-------| | Single Verification | 6,000/min | | Batch Verification | 1,500/min | | File Upload | 300/min | | Other endpoints | 200/min | ## User Request $ARGUMENTS