API Reference
API Reference
Complete reference for BillionVerify API endpoints
API Reference
The BillionVerify API is a RESTful service that provides powerful email verification capabilities. All API requests should be made over HTTPS.
Base URL
https://api.billionverify.com/v1Authentication
All API requests require authentication using a Bearer token:
Authorization: Bearer YOUR_API_KEYGet your API key from the dashboard.
Rate Limits
- Free Plan: 100 requests per hour
- Basic Plan: 1,000 requests per hour
- Pro Plan: 10,000 requests per hour
- Enterprise: Custom limits
Rate limit information is included in response headers:
X-RateLimit-Limit: Maximum requests per hourX-RateLimit-Remaining: Requests remainingX-RateLimit-Reset: Unix timestamp when limit resets
Core Endpoints
Single Email Verification
Verify a single email address with detailed results.
POST /verifyRequest Body
{
"email": "user@example.com",
"smtp_check": true,
"timeout": 5000
}Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| string | Yes | Email address to verify | |
| smtp_check | boolean | No | Perform SMTP validation (default: true) |
| timeout | integer | No | Timeout in milliseconds (default: 5000) |
Response
{
"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
}Bulk Email Verification
Verify multiple email addresses in a single request.
POST /verify/bulkRequest Body
{
"emails": [
"user1@example.com",
"user2@example.com",
"user3@example.com"
],
"smtp_check": true
}Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| emails | array | Yes | Array of email addresses (max: 1000) |
| smtp_check | boolean | No | Perform SMTP validation (default: true) |
Response
{
"job_id": "job_123456",
"status": "processing",
"total": 3,
"processed": 0,
"credits_used": 3
}Check Bulk Job Status
GET /verify/bulk/{job_id}Response
{
"job_id": "job_123456",
"status": "completed",
"total": 3,
"processed": 3,
"results": [
{
"email": "user1@example.com",
"status": "valid",
"score": 0.95
},
{
"email": "user2@example.com",
"status": "invalid",
"score": 0.15
},
{
"email": "user3@example.com",
"status": "valid",
"score": 0.88
}
]
}Status Codes
| Status | Description |
|---|---|
| valid | Email is valid and deliverable |
| invalid | Email is invalid or undeliverable |
| unknown | Unable to determine validity |
| accept_all | Server accepts all emails (catch-all) |
Error Responses
All errors follow this format:
{
"error": {
"code": "INVALID_EMAIL",
"message": "The email address format is invalid",
"details": "Missing @ symbol"
}
}Common Error Codes
| Code | Description |
|---|---|
| INVALID_API_KEY | API key is invalid or missing |
| RATE_LIMIT_EXCEEDED | Too many requests |
| INVALID_EMAIL | Email format is invalid |
| INSUFFICIENT_CREDITS | Not enough credits |
| TIMEOUT | Request timed out |
Webhooks
Configure webhooks to receive real-time notifications about verification results.
Setting Up Webhooks
POST /webhooks{
"url": "https://your-app.com/webhook",
"events": ["verification.completed", "bulk.completed"]
}Webhook Payload
{
"event": "verification.completed",
"timestamp": "2024-01-15T10:30:00Z",
"data": {
"email": "user@example.com",
"status": "valid",
"score": 0.95
}
}SDKs & Libraries
Official SDKs are available for:
Code Examples
cURL
curl -X POST https://api.billionverify.com/v1/verify \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"email": "test@example.com"}'JavaScript
const response = await fetch('https://api.billionverify.com/v1/verify', {
method: 'POST',
headers: {
'Authorization': 'Bearer YOUR_API_KEY',
'Content-Type': 'application/json'
},
body: JSON.stringify({ email: 'test@example.com' })
});Python
import requests
response = requests.post(
'https://api.billionverify.com/v1/verify',
headers={'Authorization': 'Bearer YOUR_API_KEY'},
json={'email': 'test@example.com'}
)