API Documentation

Complete guide to using the Lead Verification API

🚀 Quick Start

  1. Sign up for an account at Sign Up
  2. Generate your API key from the Dashboard
  3. Include your API key in the X-API-Key header
  4. Start verifying leads with our endpoints!

🔐 Authentication

All API requests require authentication using an API key in the request header:

X-API-Key: your-api-key-here
Note: You must be a registered user to access the API endpoints.

⏱️ Rate Limits

Current Limits:

  • Authenticated Users: 5 requests per month
  • Burst Protection: Rate limiting applies
  • Per API Key: Individual tracking
Portfolio Demo:
This is a portfolio project with limited usage to demonstrate functionality. For production use, contact the developer.

📡 API Endpoints

1. Single Lead Verification

POST https://lead-validator-api-production.up.railway.app/verify/

Verify a single email address and/or phone number.

Request Headers:

Content-Type: application/json
X-API-Key: your-api-key-here

Request Body:

{
    "email": "test@example.com",        // Optional
    "phone_number": "+1234567890"      // Optional
}
Note: At least one of email or phone_number is required.

Response:

{
    "email": "test@example.com",
    "phone_number": "+1234567890",
    "data": {
        "email_data": {
            "valid": true,
            "score": 85,
            "disposable": false
        },
        "phone_number_data": {
            "valid": true,
            "line_type": "mobile",
            "validation_errors": []
        }
    }
}

2. Bulk CSV Verification

POST https://lead-validator-api-production.up.railway.app/bulk-verify/

Upload a CSV file to verify multiple leads at once.

Request Headers:

Content-Type: multipart/form-data
X-API-Key: your-api-key-here

Request Body:

file: your-csv-file.csv

CSV Format:

email,phone_number
test1@example.com,+1234567890
test2@example.com,+0987654321
user@domain.com,+1122334455

Response:

[
    {
        "email": "test1@example.com",
        "phone_number": "+1234567890",
        "data": {
            "email_data": { "valid": true, "score": 85, "disposable": false },
            "phone_number_data": { "valid": true, "line_type": "mobile", "validation_errors": [] }
        }
    },
    // ... more results
]

❌ Error Responses

Common Error Codes:

Status Code Description Example Response
401 Invalid or missing API key {"detail": "Invalid API Key"}
400 Bad request (validation error) {"error": "Either email or phone number are required"}
429 Rate limit exceeded {"detail": "Request was throttled"}
500 Server error {"error": "Internal server error"}

💻 Code Examples

Python (requests)

import requests

# Single verification
url = "https://lead-validator-api-production.up.railway.app/verify/"
headers = {
    "Content-Type": "application/json",
    "X-API-Key": "your-api-key-here"
}
data = {
    "email": "test@example.com",
    "phone_number": "+1234567890"
}

response = requests.post(url, json=data, headers=headers)
result = response.json()
print(result)

JavaScript (fetch)

// Single verification
const response = await fetch('https://lead-validator-api-production.up.railway.app/verify/', {
    method: 'POST',
    headers: {
        'Content-Type': 'application/json',
        'X-API-Key': 'your-api-key-here'
    },
    body: JSON.stringify({
        email: 'test@example.com',
        phone_number: '+1234567890'
    })
});

const result = await response.json();
console.log(result);

cURL

# Single verification
curl -X POST "https://lead-validator-api-production.up.railway.app/verify/" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-api-key-here" \
  -d '{
    "email": "test@example.com",
    "phone_number": "+1234567890"
  }'

# CSV upload
curl -X POST "https://lead-validator-api-production.up.railway.app/bulk-verify/" \
  -H "X-API-Key: your-api-key-here" \
  -F "file=@leads.csv"

📊 Response Data Explained

Email Verification Fields:

  • valid: Boolean indicating if the email is valid
  • score: Confidence score (0-100) for email validity
  • disposable: Boolean indicating if it's a disposable email

Phone Number Verification Fields:

  • valid: Boolean indicating if the phone number is valid
  • line_type: Type of phone line (mobile, landline, etc.)
  • validation_errors: Array of any validation errors found

✅ Best Practices

  • Store your API key securely - Never expose it in client-side code
  • Handle rate limits gracefully - Implement proper retry logic
  • Validate input data - Ensure proper email/phone formats before API calls
  • Use bulk verification - For multiple leads, use CSV upload for efficiency
  • Monitor your usage - Check your dashboard for request counts

🆘 Support

This is a portfolio project created by Abraham Deeb.

Need help? This API is designed for demonstration purposes. For questions about implementation or to discuss production usage, please contact the developer.