API Documentation

Complete API reference for integrating VetoBounce into your applications.
Simple, RESTful endpoints with comprehensive examples.

Quick Start

1
Get Your API Key

Sign in to your dashboard and create an API key under Settings → API Keys

2
Base URL
https://api.vetobounce.com/api/v1
3
Authentication

Include your API key in the Authorization header:

Authorization: Bearer YOUR_API_KEY

Email Verification

Verify email addresses using SMTP-level validation

POST /jobs/quick-verify
🔒 Requires Authentication

Verify a single email address instantly

Request Body
{
  "email": "user@example.com"
}
Response
{
  "email": "user@example.com",
  "status": "valid",
  "reason": "SMTP verification successful",
  "creditsUsed": 1
}
cURL Example
curl -X POST https://api.vetobounce.com/api/v1/jobs/quick-verify \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com"
  }'
POST /jobs
🔒 Requires Authentication

Create a bulk email verification job

Request Body
{
  "name": "My Verification Job",
  "type": "verification",
  "inputConfig": {
    "emailColumn": "email"
  },
  "items": [
    {
      "email": "user1@example.com"
    },
    {
      "email": "user2@example.com"
    }
  ]
}
Response
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "userId": "123e4567-e89b-12d3-a456-426614174000",
  "name": "My Verification Job",
  "type": "verification",
  "status": "pending",
  "totalItems": 2,
  "processedItems": 0,
  "progress": 0,
  "stats": {
    "valid": 0,
    "invalid": 0,
    "catch_all": 0,
    "unknown": 0,
    "risky": 0
  },
  "creditsCharged": 0,
  "creditsRefunded": 0,
  "netCredits": 0,
  "createdAt": "2024-01-15T10:30:00Z",
  "expiresAt": "2024-02-14T10:30:00Z",
  "updatedAt": "2024-01-15T10:30:00Z"
}
cURL Example
curl -X POST https://api.vetobounce.com/api/v1/jobs \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Verification Job",
    "type": "verification",
    "inputConfig": {
      "emailColumn": "email"
    },
    "items": [
      {"email": "user1@example.com"},
      {"email": "user2@example.com"}
    ]
  }'

Email Discovery

Find professional email addresses using pattern matching

POST /jobs/quick-find
🔒 Requires Authentication

Find email for a single person instantly

Request Body
{
  "firstName": "John",
  "lastName": "Doe",
  "domain": "example.com",
  "patternLevel": "mid"
}
Response
{
  "emails": [
    {
      "email": "john.doe@example.com",
      "pattern": "first.last",
      "status": "valid",
      "reason": "SMTP verification successful",
      "verified": true
    }
  ],
  "creditsUsed": 1
}
cURL Example
curl -X POST https://api.vetobounce.com/api/v1/jobs/quick-find \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "firstName": "John",
    "lastName": "Doe",
    "domain": "example.com",
    "patternLevel": "mid"
  }'
POST /jobs
🔒 Requires Authentication

Create a bulk email discovery job

Request Body
{
  "name": "My Discovery Job",
  "type": "finding",
  "inputConfig": {
    "firstNameColumn": "firstName",
    "lastNameColumn": "lastName",
    "domainColumn": "domain",
    "patternLevel": "mid"
  },
  "items": [
    {
      "firstName": "John",
      "lastName": "Doe",
      "domain": "example.com"
    },
    {
      "firstName": "Jane",
      "lastName": "Smith",
      "domain": "company.com"
    }
  ]
}
Response
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "userId": "123e4567-e89b-12d3-a456-426614174000",
  "name": "My Discovery Job",
  "type": "finding",
  "status": "pending",
  "totalItems": 2,
  "processedItems": 0,
  "progress": 0,
  "stats": {
    "valid": 0,
    "invalid": 0,
    "catch_all": 0,
    "unknown": 0,
    "risky": 0,
    "unverified": 0
  },
  "creditsCharged": 0,
  "creditsRefunded": 0,
  "netCredits": 0,
  "createdAt": "2024-01-15T10:30:00Z",
  "expiresAt": "2024-02-14T10:30:00Z",
  "updatedAt": "2024-01-15T10:30:00Z"
}
cURL Example
curl -X POST https://api.vetobounce.com/api/v1/jobs \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Discovery Job",
    "type": "finding",
    "inputConfig": {
      "firstNameColumn": "firstName",
      "lastNameColumn": "lastName",
      "domainColumn": "domain",
      "patternLevel": "mid"
    },
    "items": [
      {"firstName": "John", "lastName": "Doe", "domain": "example.com"}
    ]
  }'

Jobs Management

Manage and monitor your verification and discovery jobs

GET /jobs
🔒 Requires Authentication

List all jobs for authenticated user

Response
[
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "My Job",
    "type": "verification",
    "status": "completed",
    "totalItems": 100,
    "processedItems": 100,
    "progress": 100,
    "stats": {
      "valid": 85,
      "invalid": 10,
      "catch_all": 3,
      "unknown": 2,
      "risky": 0
    },
    "creditsCharged": -100,
    "creditsRefunded": 5,
    "netCredits": -95,
    "createdAt": "2024-01-15T10:30:00Z",
    "completedAt": "2024-01-15T10:35:00Z",
    "expiresAt": "2024-02-14T10:30:00Z"
  }
]
cURL Example
curl -X GET https://api.vetobounce.com/api/v1/jobs \
  -H "Authorization: Bearer YOUR_API_KEY"
GET /jobs/:id
🔒 Requires Authentication

Get details of a specific job

Response
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "My Job",
  "type": "verification",
  "status": "completed",
  "totalItems": 100,
  "processedItems": 100,
  "progress": 100,
  "stats": {
    "valid": 85,
    "invalid": 10,
    "catch_all": 3,
    "unknown": 2,
    "risky": 0
  },
  "creditsCharged": -100,
  "creditsRefunded": 5,
  "netCredits": -95,
  "createdAt": "2024-01-15T10:30:00Z",
  "completedAt": "2024-01-15T10:35:00Z",
  "expiresAt": "2024-02-14T10:30:00Z"
}
cURL Example
curl -X GET https://api.vetobounce.com/api/v1/jobs/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer YOUR_API_KEY"
GET /jobs/:id/download
🔒 Requires Authentication

Download job results as CSV

Response
"CSV file download"
cURL Example
curl -X GET https://api.vetobounce.com/api/v1/jobs/550e8400-e29b-41d4-a716-446655440000/download \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -o results.csv
DELETE /jobs/:id
🔒 Requires Authentication

Delete a job

Response
{
  "message": "job deleted"
}
cURL Example
curl -X DELETE https://api.vetobounce.com/api/v1/jobs/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer YOUR_API_KEY"

File Upload

Parse and upload CSV/XLSX/XLS files for bulk processing

POST /upload/parse

Parse uploaded file and return preview

Request Body
"multipart/form-data with file field"
Response
{
  "fileName": "contacts.csv",
  "fileSize": 1024,
  "totalRows": 100,
  "headers": [
    "email",
    "firstName",
    "lastName"
  ],
  "previewRows": [
    {
      "email": "john@example.com",
      "firstName": "John",
      "lastName": "Doe"
    }
  ],
  "allRows": [],
  "hasHeaders": true,
  "detectedType": "csv"
}
cURL Example
curl -X POST https://api.vetobounce.com/api/v1/upload/parse \
  -F "file=@contacts.csv"

API Keys

Manage API keys for authentication

POST /api-keys
🔒 Requires Authentication

Create a new API key

Request Body
{
  "name": "Production API Key",
  "ipWhitelist": [
    "192.168.1.1"
  ],
  "rateLimit": 100
}
Response
{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "key": "vb_live_1234567890abcdef",
  "keyPrefix": "vb_live_****cdef",
  "name": "Production API Key",
  "createdAt": "2024-01-15T10:30:00Z"
}
cURL Example
curl -X POST https://api.vetobounce.com/api/v1/api-keys \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production API Key",
    "rateLimit": 100
  }'
GET /api-keys
🔒 Requires Authentication

List all API keys

Response
{
  "keys": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "keyPrefix": "vb_live_****cdef",
      "name": "Production API Key",
      "isActive": true,
      "rateLimit": 100,
      "createdAt": "2024-01-15T10:30:00Z"
    }
  ],
  "total": 1
}
cURL Example
curl -X GET https://api.vetobounce.com/api/v1/api-keys \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"
DELETE /api-keys/:id
🔒 Requires Authentication

Delete an API key

Response
{
  "message": "API key deleted successfully"
}
cURL Example
curl -X DELETE https://api.vetobounce.com/api/v1/api-keys/123e4567-e89b-12d3-a456-426614174000 \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Webhooks

Configure webhooks to receive job completion notifications

POST /webhooks
🔒 Requires Authentication

Create a webhook

Request Body
{
  "name": "Job Completion Hook",
  "url": "https://your-app.com/webhook",
  "events": [
    "job.completed",
    "job.failed"
  ],
  "customHeaders": {
    "X-Custom-Header": "value"
  },
  "retryCount": 3
}
Response
{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "name": "Job Completion Hook",
  "url": "https://your-app.com/webhook",
  "events": [
    "job.completed",
    "job.failed"
  ],
  "isActive": true,
  "retryCount": 3,
  "createdAt": "2024-01-15T10:30:00Z"
}
cURL Example
curl -X POST https://api.vetobounce.com/api/v1/webhooks \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Job Completion Hook",
    "url": "https://your-app.com/webhook",
    "events": ["job.completed"]
  }'
GET /webhooks
🔒 Requires Authentication

List all webhooks

Response
{
  "webhooks": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "name": "Job Completion Hook",
      "url": "https://your-app.com/webhook",
      "events": [
        "job.completed"
      ],
      "isActive": true,
      "createdAt": "2024-01-15T10:30:00Z"
    }
  ],
  "total": 1
}
cURL Example
curl -X GET https://api.vetobounce.com/api/v1/webhooks \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"
DELETE /webhooks/:id
🔒 Requires Authentication

Delete a webhook

Response
{
  "message": "Webhook deleted successfully"
}
cURL Example
curl -X DELETE https://api.vetobounce.com/api/v1/webhooks/123e4567-e89b-12d3-a456-426614174000 \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Credits

Check credit balance and transaction history

GET /credits
🔒 Requires Authentication

Get current credit balance

Response
{
  "balance": 5000,
  "userId": "123e4567-e89b-12d3-a456-426614174000"
}
cURL Example
curl -X GET https://api.vetobounce.com/api/v1/credits \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"
GET /credits/transactions
🔒 Requires Authentication

List credit transactions

Response
{
  "transactions": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "type": "purchase",
      "amount": 10000,
      "balance": 10000,
      "description": "Credit purchase",
      "createdAt": "2024-01-15T10:30:00Z"
    },
    {
      "id": "223e4567-e89b-12d3-a456-426614174000",
      "type": "charge",
      "amount": -100,
      "balance": 9900,
      "description": "Email verification job",
      "createdAt": "2024-01-15T11:00:00Z"
    },
    {
      "id": "323e4567-e89b-12d3-a456-426614174000",
      "type": "refund",
      "amount": 5,
      "balance": 9905,
      "description": "Unknown/catch-all refund",
      "createdAt": "2024-01-15T11:05:00Z"
    }
  ],
  "total": 3,
  "page": 1,
  "limit": 20,
  "totalPages": 1
}
cURL Example
curl -X GET https://api.vetobounce.com/api/v1/credits/transactions?page=1&limit=20 \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Response Status Codes

200OK - Request successful
201Created - Resource created successfully
400Bad Request - Invalid request data
401Unauthorized - Invalid or missing API key
403Forbidden - Access denied
404Not Found - Resource doesn't exist
500Server Error - Internal server error

Rate Limits

Default Rate Limit

100 requests/minute

Configurable per API key in your dashboard

Rate Limit Headers
X-RateLimit-Limit: 100X-RateLimit-Remaining: 95X-RateLimit-Reset: 1642253400
429 Response

When rate limit exceeded, you'll receive a 429 status with retry information

Webhook Events

Subscribe to these events to receive real-time notifications

job.completed

Triggered when a verification or discovery job finishes successfully

job.failed

Triggered when a job fails due to an error

job.started

Triggered when a job begins processing

credits.low

Triggered when credit balance falls below threshold

Example Webhook Payload
{
  "event": "job.completed",
  "timestamp": "2024-01-15T10:35:00Z",
  "data": {
    "jobId": "550e8400-e29b-41d4-a716-446655440000",
    "name": "My Verification Job",
    "type": "verification",
    "status": "completed",
    "totalItems": 100,
    "processedItems": 100,
    "stats": {
      "valid": 85,
      "invalid": 10,
      "catch_all": 3,
      "unknown": 2
    },
    "creditsCharged": -100,
    "creditsRefunded": 5,
    "netCredits": -95
  }
}

Need Help?

Our support team is here to help you integrate VetoBounce

Contact Support View Code Examples