Documentation

Email Lookup & Username Search API.

Integrate email lookup, username search, breach detection, and OSINT enrichment into your applications through a single REST API — built for security, fraud-prevention, and authorized investigation teams.

Revealer.US is not a consumer reporting agency. API results may not be used for any FCRA-covered purpose, including employment, credit, tenant screening, or insurance eligibility. See our Terms of Service.

Quick Start

01

Get API Key

API access is on the Unlimited plan. Contact sales to get set up.

02

Make Request

Send authenticated REST requests

03

Get Results

Receive structured JSON responses

Authentication

Include your API key in the Authorization header:

Authorization: Bearer sk_live_your_api_key

Security: Never expose your API key in client-side code. Make API calls from your backend.

Example

import requests

API_KEY = "sk_live_..."
BASE_URL = "https://revealer.us"

headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json"
}

# Verify your API key first
def verify_api_key():
    response = requests.get(f"{BASE_URL}/api/v1/verify", headers=headers)
    return response.json()

# Resolve a username/handle
def resolve_handle(handle):
    response = requests.post(
        f"{BASE_URL}/api/resolve",
        headers=headers,
        json={"handle": handle}
    )
    return response.json()

# Search breach records
def search_breaches(search_type, term):
    response = requests.post(
        f"{BASE_URL}/api/database/search",
        headers=headers,
        json={"type": search_type, "term": term}
    )
    return response.json()

# Search stealer logs (Elite plan)
def search_stealer_logs(search_type, term, limit=35):
    response = requests.post(
        f"{BASE_URL}/api/stealer-logs/search",
        headers=headers,
        json={"type": search_type, "term": term, "limit": limit}
    )
    return response.json()

# Example usage
result = search_breaches("email", "[email protected]")
if result.get("success"):
    print(f"Found {result['data']['found']} records")

Endpoints

GET/api/v1/infoPublic

Get API information, available endpoints, and your detected IP address (no auth required)

GET/api/v1/verifyUnlimited

Verify API key is working and check your access level

POST/api/resolveUnlimited

Resolve a handle/username to associated profiles, breach data, and device exposures

POST/api/database/searchUnlimited

Search breach records across connected sources for exposed credentials and personal data

POST/api/stealer-logs/searchUnlimited

Search device exposures for compromised credentials (full results require the Elite plan)

POST/api/stealer-logs/file/[id]/[type]Unlimited

Browse detailed contents of a stealer log file

POST/api/discord/lookupUnlimited

Lookup Discord user profiles by user ID

GET/api/saved-incidentsUnlimited

List all saved credentials/incidents

POST/api/saved-incidentsUnlimited

Save a credential/incident to your account

DELETE/api/saved-incidents/[id]Unlimited

Delete a saved incident by ID

GET/api/auth/meUnlimited

Get current account information, tier, quota, and verify API key

Rate Limits & Quotas

PlanAPIBreach LookupsSocial LookupsDevice ExposuresRateIPs
Free1/day1/day
StarterUnlimited25/day
BasicUnlimited150/day
ProUnlimited500/dayPreviews
EliteUnlimitedUnlimited100/day
Unlimited

API access: Available on the Unlimited plan. Contact sales to get set up. Once enabled, configure allowed IPs in Dashboard → Settings → API Access before using the API.

Error Responses

CodeStatusDescription
400Bad RequestInvalid request body or missing required parameters
401UnauthorizedMissing or invalid API key
403ForbiddenIP not whitelisted or insufficient tier access
404Not FoundResource not found
409ConflictResource already exists (e.g., duplicate saved incident)
429Too Many RequestsRate limit or quota exceeded
500Internal Server ErrorServer error - contact support if persistent

Error Response Format:

{
  "success": false,
  "error": "Error message",
  "message": "Human-readable description"
}

Response Headers

Rate limit information is included in response headers:

X-RateLimit-Limit: Maximum requests per second
X-RateLimit-Remaining: Remaining requests in window
X-RateLimit-Reset: Unix timestamp when limit resets
X-API-Authenticated: "true" when authenticated
X-Client-IP: Your detected IP address

Troubleshooting

403 Forbidden or Cloudflare Challenge

If you receive 403 errors or see Cloudflare challenge pages:

  1. 1.Check your IP via GET /api/v1/info
  2. 2.Whitelist IP in Dashboard → Settings → API Access
  3. 3.Verify key via GET /api/v1/verify
  4. 4.Confirm your account has Unlimited plan API access (contact sales if not)

IP Mismatch

Your server's outgoing IP may differ from local, especially with:

  • Cloud providers (AWS, GCP, Azure): use the instance public IP
  • VPNs and proxies: whitelist the exit node IP
  • NAT gateways: whitelist the NAT public IP

Required Headers

Authorization: Bearer sk_live_your_api_key
Content-Type: application/json
Get Started

Ready to integrate?

API access is available on the Unlimited plan. Get in touch and we'll set you up.