API Reference

BlueWeb API Documentation

Find verified email addresses, search company domains, verify deliverability, and enrich contacts — all through a simple REST API.

Base URL

https://blueweb.ai/api/v1

Auth

Bearer bw_live_*

Format

JSON

Authentication

All API requests require a Bearer token in the Authorization header. Generate API keys from your dashboard.

http

Authorization: Bearer bw_live_xxxxxxxxxxxxxxxxxxxxxxxx

API access requires a Starter ($49/mo) plan or above. Free plans can only use the dashboard. View pricing

Endpoints

POST/api/v1/email-finder

Find a professional email address for a person at a company. Returns a job ID — poll the result endpoint until status is completed.

Request Body

Parameter	Type	Description
`first_name`required	string	The person's first name
`last_name`required	string	The person's last name
`domain`required	string	The company domain (e.g. stripe.com)

Response 202 Accepted

json

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "processing",
  "poll_url": "/api/v1/email-finder/a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

Completed Result

json

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "first_name": "Sarah",
  "last_name": "Chen",
  "domain": "stripe.com",
  "email": "sarah.chen@stripe.com",
  "confidence": 96,
  "verification_status": "valid",
  "sources": ["pattern_match", "smtp_verified"],
  "duration_ms": 1800,
  "status": "completed"
}

Example

bash

curl -X POST https://blueweb.ai/api/v1/email-finder \
  -H "Authorization: Bearer bw_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "first_name": "Sarah",
    "last_name": "Chen",
    "domain": "stripe.com"
  }'

POST/api/v1/domain-search

Discover all professional email addresses associated with a company domain. Returns a job ID — poll for completion.

Request Body

Parameter	Type	Description
`domain`required	string	The company domain to search (e.g. stripe.com)

Response 202 Accepted

json

{
  "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
  "status": "processing",
  "poll_url": "/api/v1/domain-search/b2c3d4e5-f6a7-8901-bcde-f12345678901"
}

Completed Result

json

{
  "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
  "domain": "stripe.com",
  "company_name": "Stripe",
  "total_results": 127,
  "status": "completed",
  "duration_ms": 4200,
  "results": [
    {
      "email": "sarah.chen@stripe.com",
      "first_name": "Sarah",
      "last_name": "Chen",
      "position": "Head of Growth",
      "department": "Marketing",
      "confidence": 96,
      "verification_status": "valid"
    },
    {
      "email": "james.liu@stripe.com",
      "first_name": "James",
      "last_name": "Liu",
      "position": "VP Engineering",
      "department": "Engineering",
      "confidence": 94,
      "verification_status": "valid"
    }
  ]
}

POST/api/v1/email-verifier

Verify whether an email address is valid and deliverable. Runs a 9-step verification pipeline synchronously and returns results immediately.

Request Body

Parameter	Type	Description
`email`required	string	The email address to verify

Response 200 OK

json

{
  "id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
  "email": "sarah.chen@stripe.com",
  "result": "valid",
  "score": 98,
  "checks": {
    "format": "pass",
    "gibberish": "pass",
    "disposable": "pass",
    "webmail": "pass",
    "mx_records": "pass",
    "smtp_connect": "pass",
    "smtp_accept": "pass",
    "catch_all": "pass",
    "deliverability": "pass"
  },
  "is_disposable": false,
  "is_free_provider": false,
  "is_role_account": false,
  "is_catch_all": false,
  "mx_records": ["aspmx.l.google.com"],
  "duration_ms": 620
}

Verification Results

Result	Description
`valid`	Email is valid, deliverable, and accepted by the mail server
`invalid`	Email was rejected by the mail server or failed verification checks
`risky`	Email may be deliverable but has risk factors (catch-all domain, disposable provider, etc.)
`unknown`	Could not determine deliverability (server timeout, greylisting, etc.)

POST/api/v1/enrich

Enrich an email address with professional details — name, title, company, department, and verification status.

Request Body

Parameter	Type	Description
`email`required	string	The email address to enrich

Response 200 OK

json

{
  "email": "sarah.chen@stripe.com",
  "firstName": "Sarah",
  "lastName": "Chen",
  "company": "Stripe",
  "domain": "stripe.com",
  "title": "Head of Growth",
  "department": "Marketing",
  "verificationStatus": "valid",
  "confidence": 96,
  "company_info": {
    "name": "Stripe",
    "domain": "stripe.com",
    "industry": null,
    "size": null
  }
}

Error Handling

All errors return a JSON object with an error field.

Status	Meaning	Example
400	Bad Request	{"error": "first_name is required"}
401	Unauthorised	{"error": "Invalid or missing API key"}
404	Not Found	{"error": "Search not found"}
429	Rate Limited	{"error": "Monthly credit limit reached"}

Code Examples

JavaScript / TypeScript

typescript

const API_KEY = "bw_live_your_api_key";
const BASE = "https://blueweb.ai/api/v1";
const headers = {
  Authorization: `Bearer ${API_KEY}`,
  "Content-Type": "application/json",
};

// 1. Find an email (async — returns job, poll for result)
const { id, poll_url } = await fetch(`${BASE}/email-finder`, {
  method: "POST",
  headers,
  body: JSON.stringify({
    first_name: "Sarah",
    last_name: "Chen",
    domain: "stripe.com",
  }),
}).then(r => r.json());

// 2. Poll until complete
let result;
do {
  await new Promise(r => setTimeout(r, 2000));
  result = await fetch(`${BASE}${poll_url}`, {
    headers: { Authorization: `Bearer ${API_KEY}` },
  }).then(r => r.json());
} while (result.status === "processing" || result.status === "pending");

console.log(result.email);       // sarah.chen@stripe.com
console.log(result.confidence);  // 96

// 3. Verify an email (synchronous — returns immediately)
const verification = await fetch(`${BASE}/email-verifier`, {
  method: "POST",
  headers,
  body: JSON.stringify({ email: "sarah.chen@stripe.com" }),
}).then(r => r.json());

console.log(verification.result);  // "valid"
console.log(verification.score);   // 98

Python

python

import requests, time

API_KEY = "bw_live_your_api_key"
BASE = "https://blueweb.ai/api/v1"
headers = {"Authorization": f"Bearer {API_KEY}"}

# 1. Find an email (async)
job = requests.post(f"{BASE}/email-finder", headers=headers, json={
    "first_name": "Sarah",
    "last_name": "Chen",
    "domain": "stripe.com",
}).json()

# 2. Poll until complete
while True:
    result = requests.get(
        f"{BASE}{job['poll_url']}", headers=headers
    ).json()
    if result["status"] in ("completed", "failed"):
        break
    time.sleep(2)

print(result["email"])       # sarah.chen@stripe.com
print(result["confidence"])  # 96

# 3. Verify an email (synchronous)
verification = requests.post(f"{BASE}/email-verifier", headers=headers, json={
    "email": "sarah.chen@stripe.com",
}).json()

print(verification["result"])  # "valid"
print(verification["score"])   # 98

cURL

bash

# Domain search — discover all emails at a company
curl -X POST https://blueweb.ai/api/v1/domain-search \
  -H "Authorization: Bearer bw_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"domain": "stripe.com"}'

# Enrich a contact
curl -X POST https://blueweb.ai/api/v1/enrich \
  -H "Authorization: Bearer bw_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"email": "sarah.chen@stripe.com"}'

Usage & Limits

Each email search, domain search, or verification consumes 1 credit from your monthly allowance. Usage resets at the start of each calendar month.

Plan	Price	Credits/month	API Access
Free	$0	50	Dashboard only
Starter	$49/mo	2,000	Yes
Growth	$149/mo	10,000	Yes
Business	$299/mo	50,000	Yes

Ready to find verified emails?

Create your free account and get 50 searches/month — no credit card required.

Get started free Generate API key