API Documentation

Integrate email verification directly into your app. All endpoints return JSON.

Authentication

All API requests require authentication via a Bearer token. You can use either a JWT access token (from the login endpoint) or an API key (created in your dashboard). API keys start with vf_sk_.

bash

# Using an API key
curl https://api.valideefy.com/api/v1/auth/me \
  -H "Authorization: Bearer vf_sk_your_api_key_here"

Quick Start

Verify an email address in a single API call:

curl

curl -X POST https://api.valideefy.com/api/v1/verify/single \
  -H "Authorization: Bearer vf_sk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"email": "john@company.com"}'

python

import requests

API_KEY = "vf_sk_your_api_key"
BASE_URL = "https://api.valideefy.com"

response = requests.post(
    f"{BASE_URL}/api/v1/verify/single",
    headers={"Authorization": f"Bearer {API_KEY}"},
    json={"email": "john@company.com"},
)

result = response.json()
print(f"Result: {result['result']}")   # valid, invalid, catch_all, risky, unknown
print(f"Score:  {result['score']}")    # 0-100 confidence score
print(f"Cost:   {result['credits_used']} credit(s)")

javascript

const API_KEY = "vf_sk_your_api_key";
const BASE_URL = "https://api.valideefy.com";

const response = await fetch(`${BASE_URL}/api/v1/verify/single`, {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ email: "john@company.com" }),
});

const result = await response.json();
console.log(`Result: ${result.result}`);   // valid, invalid, catch_all, risky, unknown
console.log(`Score:  ${result.score}`);    // 0-100 confidence score

Response Format

Every verification returns a complete result object:

json

{
  "email": "john@company.com",
  "result": "valid",
  "sub_result": "deliverable",
  "score": 92,
  "checks": {
    "syntax": true,
    "dns": true,
    "mx_found": true,
    "smtp_connected": true,
    "mailbox_exists": true,
    "catch_all": false,
    "disposable": false,
    "role_based": false,
    "free_provider": false
  },
  "tags": [],
  "mx_record": "mail.company.com",
  "provider": "Google Workspace",
  "credits_used": 1,
  "verified_at": "2026-03-30T12:00:00Z"
}

Result Values

valid Mailbox exists and accepts mail
invalid Mailbox doesn't exist or is disabled
catch_all Server accepts all addresses
risky Greylisted or temporarily unavailable
unknown Could not determine (timeout/error)

Credits Charged

valid 1 credit
invalid 1 credit
risky 1 credit
catch_all 0 credits (free)
unknown 0 credits (free)
duplicate 0 credits (free)

Endpoints Reference

Verification

POST/api/v1/verify/singleAUTH REQUIRED

Verify a single email address. Returns the full verification result.

Request body

{ "email": "john@company.com" }

Response

{
  "email": "john@company.com",
  "result": "valid",
  "score": 92,
  "credits_used": 1,
  ...
}

POST/api/v1/verify/bulkAUTH REQUIRED

Upload a CSV, TXT, or XLSX file to start a bulk verification job. Returns the job immediately — processing happens asynchronously.

Request body

multipart/form-data with file field

Response

{
  "id": "uuid",
  "status": "pending",
  "total_emails": 5000,
  ...
}

GET/api/v1/verify/jobsAUTH REQUIRED

List your verification jobs, newest first. Supports pagination with ?page=1&per_page=20.

Response

[{ "id": "uuid", "status": "completed", "total_emails": 5000, ... }]

GET/api/v1/verify/jobs/{job_id}AUTH REQUIRED

Get detailed status, stats, and progress for a specific job.

Response

{
  "id": "uuid",
  "status": "completed",
  "valid_count": 4200,
  "invalid_count": 650,
  ...
}

GET/api/v1/verify/jobs/{job_id}/resultsAUTH REQUIRED

Get paginated verification results for a job. Filter by result type with ?result=valid.

Response

{
  "items": [{ "email": "...", "result": "valid", "score": 95 }],
  "total": 5000,
  "page": 1,
  "per_page": 50
}

GET/api/v1/verify/jobs/{job_id}/downloadAUTH REQUIRED

Download the full results as a CSV file.

Response

CSV file download

Credits

GET/api/v1/credits/balanceAUTH REQUIRED

Get your current credit balance and lifetime usage.

Response

{ "balance": 4500, "lifetime_used": 12300 }

GET/api/v1/credits/packages

List available credit packages with pricing. No auth required.

Response

[{ "name": "Starter", "credits": 1000, "price_usd_cents": 500 }, ...]

API Keys

GET/api/v1/keysAUTH REQUIRED

List your API keys (prefix only — full key is shown once at creation).

Response

[{ "id": "uuid", "key_prefix": "vf_sk_ab12..", "name": "Production", "is_active": true }]

POST/api/v1/keysAUTH REQUIRED

Create a new API key. The full key is returned ONCE in this response.

Request body

{ "name": "Production Key" }

Response

{
  "id": "uuid",
  "key": "vf_sk_aBcDeFgH...",
  "key_prefix": "vf_sk_aBcDeF",
  "name": "Production Key"
}

DELETE/api/v1/keys/{key_id}AUTH REQUIRED

Revoke (deactivate) an API key. This action is irreversible.

Response

{ "message": "API key revoked successfully." }

Rate Limits

Endpoint	Limit
POST /verify/single	60 requests / minute
POST /verify/bulk	10 uploads / hour
POST /auth/login	10 requests / minute
All other endpoints	120 requests / minute

When rate limited, the API returns 429 Too Many Requests with a Retry-After header.

OpenAPI Specification

The full OpenAPI 3.1 spec is available at /api/v1/openapi.json. You can also explore the interactive Swagger UI at /api/docs.