API Documentation

Integrate qualified revenue opportunities directly into your stack.

Data Pipeline Overview

All uploaded leads pass through our 5-phase validation pipeline:

01 Ingest

Parse CSV/API

02 Normalize

Standardize

03 Validate

Email + Phone

04 Enrich

Apollo/Clearbit

05 Dedup

Fuzzy Match

06 Score

Smart Scoring

Only leads marked QUALIFIED are returned in the final output.

Endpoints

POST /api/upload

Upload a file (CSV or JSON) for processing.

Response
{ "filename": "leads.csv", "size": 1024, "file_path": "..." }
POST /api/process

Start a background processing job for an uploaded file.

Request Body
{ "filename": "leads.csv" }
GET /api/batches

Retrieve a list of all batch jobs and their status.

GET /api/download/{job_id}

Download the result CSV for a completed job.

Qualified Lead Schema (JSON)
{
  "status": "QUALIFIED",
  "score": 98.5,
  "account": {
    "name": "TechFlow Systems",
    "domain": "techflow.com",
    "signals": ["Series B", "Hiring"],
    "technologies": ["AWS", "Salesforce"]
  },
  "contact": {
    "full_name": "Sarah Miller",
    "title_normalized": "VP of Sales",
    "email": "sarah@techflow.com",
    "email_status": "verified_deliverable",
    "phone": "+1-555-0199",
    "phone_status": "mobile_active"
  },
  "dedup_confidence": 0.99
}

Billing & Subscription API

POST /api/billing/create-checkout

Create a Stripe checkout session for subscription purchase.

Request Body
{ "plan_id": "professional" }
Response
{ "checkout_url": "https://checkout.stripe.com/...", "session_id": "..." }
GET /api/billing/subscription

Get current subscription details and credit balance.

Response
{
  "plan_id": "professional",
  "plan_name": "Professional",
  "credits_total": 5000,
  "credits_remaining": 3250,
  "billing_cycle_start": "2026-02-01",
  "billing_cycle_end": "2026-03-01",
  "status": "active"
}
POST /api/billing/subscription/upgrade

Upgrade subscription plan (immediate, resets credits).

Request Body
{ "plan_id": "enterprise" }
POST /api/billing/subscription/downgrade

Schedule downgrade at end of billing cycle.

Request Body
{ "plan_id": "starter" }
GET /api/billing/usage?days=30

Get usage statistics for the specified period.

Response
{
  "total_consumed": 1750,
  "daily_usage": [
    {"date": "2026-02-01", "credits": 50},
    {"date": "2026-02-02", "credits": 75}
  ]
}
POST /api/billing/refund

Request a refund for a specific order.

Request Body
{ 
  "order_id": "ord_abc123",
  "amount": 49900,
  "reason": "Customer request"
}
GET /api/billing/invoices

List all invoices for the current user.

Response
[
  {
    "invoice_number": "INV-2026-001",
    "amount": 499.00,
    "status": "paid",
    "created_at": "2026-02-01T10:00:00Z"
  }
]
GET /api/billing/invoices/{invoice_number}/pdf

Download invoice PDF.

Phase 3 API Endpoints

Access advanced caching, predictive enrichment, and multi-source validation features.

GET /v1/cache/stats

Cache Performance Metrics

Get real-time cache performance statistics including hit rates, latency, and cost savings.

Response
{
  "l1_cache": {
    "hit_rate": 0.94,
    "avg_latency_ms": 0.8,
    "total_hits": 15420,
    "total_misses": 980
  },
  "l2_cache": {
    "hit_rate": 0.89,
    "avg_latency_ms": 12.5,
    "total_hits": 8730,
    "total_misses": 1080
  },
  "similarity_matches": {
    "total": 3240,
    "threshold": 0.85
  },
  "cost_savings": {
    "api_calls_saved": 24150,
    "estimated_savings_usd": 1207.50
  }
}
GET /v1/enrichment/predictive

Predictive Enrichment Status

Check the status of predictive enrichment including detected patterns and pre-enriched leads.

Response
{
  "patterns_detected": {
    "company_batches": 12,
    "sequential_patterns": 8,
    "domain_patterns": 15
  },
  "predictions": {
    "total_generated": 450,
    "pre_enriched": 360,
    "success_rate": 0.80
  },
  "performance": {
    "avg_prediction_accuracy": 0.82,
    "zero_latency_requests": 0.78,
    "throughput_increase": 2.1
  },
  "background_queue": {
    "pending": 45,
    "processing": 12,
    "completed": 360
  }
}
GET /v1/validation/multi-source

Multi-Source Validation Results

Retrieve cross-validated data with source attribution and confidence scores.

Request
GET /v1/validation/multi-source?email=john.smith@techcorp.com
Response
{
  "lead": {
    "email": "john.smith@techcorp.com",
    "name": "John Smith",
    "title": "VP of Engineering",
    "company": "TechCorp Inc",
    "phone": "+1-555-0123",
    "linkedin": "https://linkedin.com/in/johnsmith"
  },
  "validation": {
    "confidence_score": 0.96,
    "data_quality": 0.99,
    "coverage": 0.98
  },
  "sources": {
    "hunter_io": {
      "agreement": true,
      "confidence": 0.95,
      "fields_provided": ["email", "name", "title", "company"]
    },
    "clearbit": {
      "agreement": true,
      "confidence": 0.98,
      "fields_provided": ["name", "title", "company", "linkedin"]
    },
    "snov_io": {
      "agreement": true,
      "confidence": 0.94,
      "fields_provided": ["email", "phone", "company"]
    }
  },
  "consensus": {
    "email": { "agreement_score": 1.0, "sources": 3 },
    "name": { "agreement_score": 1.0, "sources": 3 },
    "title": { "agreement_score": 0.95, "sources": 2 },
    "company": { "agreement_score": 1.0, "sources": 3 }
  }
}

Phase 3 Metrics

Enhanced batch and lead responses now include Phase 3 performance metrics.

Example: Enhanced Batch Response
{
  "batch_id": "batch_123",
  "status": "completed",
  "leads_processed": 1000,
  "leads_qualified": 847,
  "phase3_metrics": {
    "cache_hit_rate": 0.94,
    "predictive_matches": 780,
    "multi_source_validated": 847,
    "avg_confidence": 0.96
  }
}

Webhook Signature Verification

All Stripe webhooks are verified using HMAC-SHA256 signatures:

Python Example
import hmac
import hashlib

def verify_webhook(payload: bytes, signature: str, secret: str) -> bool:
    expected = hmac.new(
        secret.encode(),
        payload,
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, signature)