API Documentation

Complete reference for the Business Outreach Platform API

API Active Check Health

Quick Navigation

Getting Started Authentication Lead Scoring Batch API Pipeline Entities Contacts Intelligence System

Getting Started

Quick guide to start using the API in your applications

Choose Your Endpoint

Pick the right endpoint for your use case:

For Lead Lists

/api/batch/leads

Get leads by industry with emails & pain points

For Quality Filtering

/api/leads/scored

Get leads ranked by quality score (A-F grades)

Make Your First Request

Try this example to get technology companies with emails:

curl "http://157.90.130.242:8080/api/batch/leads?industry=technology&has_email=1&limit=10"

Use the Data

Each lead includes everything you need for outreach:

✓ Company name, location, website
✓ Contact emails with names and titles
✓ Industry classification (NAICS)
✓ Pain points for personalized outreach
✓ Lead quality score (0-100)

Common Use Cases

Healthcare Outreach

Get healthcare companies with verified emails and quality score of B or higher:

curl "http://157.90.130.242:8080/api/batch/leads?industry=healthcare&has_email=1&min_score=60"

Regional Campaign

Get construction companies in Texas sorted by lead quality:

curl "http://157.90.130.242:8080/api/leads/scored?industry=construction&state=TX&has_email=1"

Bulk Export

Get 500 IT consulting companies with pagination:

curl "http://157.90.130.242:8080/api/batch/leads?industry=consulting&has_email=1&limit=500"

Use offset=500 to get the next page

Single Company Deep Dive

Get full details for a specific company (all emails, all pain points):

curl "http://157.90.130.242:8080/api/batch/entity/J3DDPT1EAKG6"

Pro Tips

• Always add has_email=1 to get leads you can actually contact
• Use min_score=40 for qualified leads, min_score=60 for high-quality
• Pain points make your outreach more personalized and effective
• Check /api/leads/score-distribution to see how many leads are in each grade

Authentication

The API uses API Key authentication for the /api/v2/ endpoints. Include your API key in the request header.

X-API-Key: your-api-key-here

Note

The /api/ endpoints (without v2) do not require authentication and are used by the web interface.

Pipeline Endpoints

Endpoints for managing the entity enrichment pipeline

GET /api/pipeline/entities

Get entities with enrichment data for pipeline view

Query Parameters

Parameter	Type	Description
`page`	int	Page number (default: 1)
`limit`	int	Results per page (default: 50)
`search`	string	Search by company name or entity ID
`state`	string	Filter by state (e.g., CA, NY)
`naics`	string	Filter by NAICS code prefix
`stage`	string	Filter by stage: raw, enriched, qualified, ready
`has_email`	string	Set to "1" to filter entities with emails

Response Example

{
  "entities": [
    {
      "id": "UNIQUE_ENTITY_ID",
      "name": "Company Name",
      "city": "San Francisco",
      "state": "CA",
      "naics": "541611",
      "website": "https://example.com",
      "email_count": 3,
      "contacts": [
        {
          "email": "contact@example.com",
          "name": "John Doe",
          "type": "govt_bus_poc",
          "verified": true
        }
      ],
      "enrichment": 70,
      "hasWebsite": true,
      "hasIntel": true,
      "painLevel": "medium",
      "stage": "qualified"
    }
  ],
  "total": 1500,
  "page": 1,
  "limit": 50
}

cURL Example

curl -X GET "http://localhost:8080/api/pipeline/entities?page=1&limit=10&state=CA"

GET /api/pipeline/stage-counts

Get counts for each pipeline stage (raw, enriched, qualified, ready)

Response Example

{
  "raw": 5000,
  "enriched": 3000,
  "qualified": 1500,
  "ready": 500,
  "stats": {
    "total": 10000,
    "with_website": 4500,
    "with_emails": 3500,
    "with_intel": 1200,
    "with_pain": 800
  }
}

cURL Example

curl -X GET "http://localhost:8080/api/pipeline/stage-counts"

Entity Endpoints

Get detailed information about specific entities

GET /api/entities/{entity_id}/intelligence

Get company intelligence data scraped from websites

Path Parameters

entity_id Unique entity identifier (e.g., SAMQQ1234ABC)

Response Example

{
  "has_intel": true,
  "company_name": "Acme Corp",
  "intel_data": {
    "extracted_info": {
      "services": ["Consulting", "IT Solutions"],
      "about": "Leading technology provider...",
      "team": ["John Smith - CEO", "Jane Doe - CTO"]
    },
    "intelligence_score": 75
  },
  "pages_scraped": 5,
  "scrape_date": "2025-01-15T10:30:00"
}

cURL Example

curl -X GET "http://localhost:8080/api/entities/SAMQQ1234ABC/intelligence"

GET /api/entities/{entity_id}/pain-points

Get pain points and challenges identified for a company

Response Example

{
  "has_pain_points": true,
  "count": 5,
  "pain_level": "medium",
  "avg_severity": 3.2,
  "pain_points": [
    {
      "id": 123,
      "category": "customer_service",
      "source": "bbb_scraper",
      "title": "Response Time Issues",
      "content": "Customers report slow response times...",
      "sentiment": "negative",
      "severity": 4,
      "url": "https://bbb.org/...",
      "date_found": "2025-01-10"
    }
  ],
  "categories": ["customer_service", "quality"]
}

cURL Example

curl -X GET "http://localhost:8080/api/entities/SAMQQ1234ABC/pain-points"

POST /api/entities/{entity_id}/enrich

Queue an entity for enrichment processing

Response Example

{
  "status": "queued",
  "entity_id": "SAMQQ1234ABC",
  "message": "Entity queued for enrichment"
}

cURL Example

curl -X POST "http://localhost:8080/api/entities/SAMQQ1234ABC/enrich"

Contacts & Statistics

Endpoints for contacts and platform statistics

GET /api/contacts

Get paginated list of entities with their contacts

Query Parameters

Parameter	Type	Description
`source`	string	Data source: samgov, state (default: samgov)
`page`	int	Page number (default: 1)
`per_page`	int	Results per page (default: 50)
`search`	string	Search by name or entity ID
`state`	string	Filter by state
`naics`	string	Filter by NAICS code

cURL Example

curl -X GET "http://localhost:8080/api/contacts?page=1&per_page=25&state=CA"

GET /api/stats

Get platform-wide statistics

Response Example

{
  "general": {
    "total_entities": 15000,
    "total_contacts": 45000,
    "contacts_with_email": 12000,
    "tracked_entities": 5000,
    "entities_with_websites": 8000
  },
  "website_stats": {
    "with_websites": 8000,
    "without_websites": 7000,
    "percentage": 53.3
  }
}

cURL Example

curl -X GET "http://localhost:8080/api/stats"

GET /api/filters

Get available filter options (states, NAICS codes, statuses)

Response Example

{
  "states": [
    {"value": "CA", "count": 5000},
    {"value": "TX", "count": 3000}
  ],
  "naics_codes": [
    {"value": "541611", "count": 1500, "label": "541611 - Administrative Management (1,500)"}
  ],
  "statuses": [
    {"value": "new", "label": "New"},
    {"value": "active", "label": "Active"}
  ]
}

Intelligence & Pain Points

Endpoints for company intelligence and pain point analysis

GET /api/company-intelligence/{entity_id}

Get detailed company intelligence data

Response Example

{
  "company_intelligence": {
    "extracted_info": {
      "services": ["IT Consulting", "Software Development"],
      "about": "We are a leading provider of...",
      "certifications": ["ISO 9001", "SOC 2"]
    },
    "homepage_description": "Enterprise solutions provider",
    "pages_scraped": 8,
    "scrape_date": "2025-01-15T14:30:00"
  }
}

GET /api/pain-points/{entity_id}

Get comprehensive pain points data including competitors and industry challenges

Response Example

{
  "pain_points": [...],
  "competitors": [
    {
      "name": "Competitor Inc",
      "relationship": "direct",
      "intelligence_type": "market_share",
      "details": "Growing market presence..."
    }
  ],
  "industry_challenges": [...],
  "review_summary": {
    "platform": "Glassdoor",
    "rating": 3.5,
    "total_reviews": 150
  },
  "pain_score": 45,
  "email_strategy": {
    "approach": "Consultative approach...",
    "key_points": ["Address customer satisfaction", "..."],
    "subject_lines": ["Solution for Your Challenges", "..."]
  }
}

POST /api/deep-analysis

Trigger deep analysis for a company (runs in background)

Request Body

{
  "entity_id": "SAMQQ1234ABC",
  "company_name": "Acme Corp"  // optional, can use either
}

cURL Example

curl -X POST "http://localhost:8080/api/deep-analysis" \
  -H "Content-Type: application/json" \
  -d '{"entity_id": "SAMQQ1234ABC"}'

System & Process Status

Endpoints for monitoring system health and processes

GET /api/system/stats

Get system-wide statistics and enrichment percentages

Response Example

{
  "totalEntities": 15000,
  "withWebsites": 8000,
  "withEmails": 5000,
  "withIntel": 3000,
  "withPain": 1500,
  "websitePercent": 53.3,
  "emailPercent": 33.3,
  "intelPercent": 20.0,
  "painPercent": 10.0
}

GET /api/process-status

Get status of all background processes with last run times

Response Example

{
  "complete_pipeline": {
    "last_run": "2025-01-15T10:00:00",
    "status": "completed",
    "items_processed": 150
  },
  "email_finder": {
    "last_run": "2025-01-15T09:30:00",
    "status": "completed"
  },
  "website_finder": {...}
}

GET /api/progress

Get comprehensive data collection progress

Response Example

{
  "email": {
    "total_entities": 15000,
    "with_emails": 5000,
    "total_emails": 12000,
    "coverage": 33.3
  },
  "intelligence": {
    "total_records": 3000,
    "companies_covered": 3000,
    "recent": 150,
    "coverage": 20.0
  },
  "pain_points": {
    "total": 8000,
    "companies": 1500,
    "today": 25,
    "coverage": 10.0
  },
  "overall_score": 65
}

GET /api/info

Get current database mode and connection info

Response Example

{
  "database_mode": "neon",
  "database_type": "PostgreSQL (Neon)",
  "environment": "Development",
  "data_source": "samgov",
  "source_name": "SAM.gov",
  "source_description": "Federal contractor database"
}

API v2 Endpoints

Requires API Key

Authenticated endpoints for external integrations

GET /api/v2/health No Auth

Health check endpoint for monitoring

Response Example

{
  "status": "healthy",
  "service": "Business Outreach Platform API v2",
  "timestamp": "2025-01-15T10:30:00",
  "database": "connected"
}

GET /api/v2/stats/overview

Get comprehensive platform statistics

cURL Example

curl -X GET "http://localhost:8080/api/v2/stats/overview" \
  -H "X-API-Key: your-api-key"

GET /api/v2/companies/{entity_id}

Get comprehensive company details

Related Endpoints

/api/v2/companies/{entity_id}/contacts - Get company contacts
/api/v2/companies/{entity_id}/pain-points - Get pain points
/api/v2/companies/{entity_id}/intelligence - Get intelligence data
/api/v2/companies/{entity_id}/industry-insights - Get industry insights

POST /api/v2/email/generate

Generate personalized email templates using AI

Request Body

{
  "entity_id": "SAMQQ1234ABC",
  "contact_id": 123,  // optional
  "style": "balanced",  // or "aggressive", "soft"
  "product_info": {
    "product_name": "Our Solution",
    "key_benefit": "Reduce costs by 40%"
  }
}

cURL Example

curl -X POST "http://localhost:8080/api/v2/email/generate" \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"entity_id": "SAMQQ1234ABC", "style": "balanced"}'

GET /api/v2/search/companies

Search companies with various filters

Query Parameters

`q`	Search term for company name
`state`	Filter by state
`naics`	Filter by NAICS code
`has_pain_points`	true/false - filter by pain points presence
`has_emails`	true/false - filter by email presence
`limit`	Max results (default: 50, max: 100)

Lead Scoring API

NEW

Score and rank leads by quality for your outreach campaigns

Lead Score Breakdown (0-100)

30 Has Email

15 Has Website

15 Has Intelligence

25 Has Pain Points

15 Data Freshness

+10 Verified Email (bonus)

A: 80-100 B: 60-79 C: 40-59 D: 20-39 F: 0-19

GET /api/leads/scored

Get leads sorted by quality score (highest first)

Query Parameters

Parameter	Type	Description
`industry`	string	Plain English: technology, healthcare, construction, etc.
`naics`	string	NAICS code prefix (e.g., 5415)
`state`	string	State code (TX, CA, NY, etc.)
`min_score`	int	Minimum score threshold (0-100)
`limit`	int	Max records (default: 100, max: 1000)
`offset`	int	Pagination offset

Response Example

{
  "success": true,
  "leads": [
    {
      "entity_id": "J3DDPT1EAKG6",
      "company_name": "Acme Tech Solutions",
      "city": "Austin",
      "state": "TX",
      "website": "https://acmetech.com",
      "naics": "541511",
      "naics_description": "Custom Computer Programming",
      "primary_email": "contact@acmetech.com",
      "email_count": 3,
      "pain_point_count": 5,
      "score": 85,
      "grade": "A",
      "score_breakdown": {
        "email": 35,
        "website": 15,
        "intelligence": 12,
        "pain_points": 13,
        "freshness": 10
      }
    }
  ],
  "meta": {
    "total_matching": 5000,
    "returned": 100,
    "min_score": 60
  }
}

cURL Example

curl "http://localhost:8080/api/leads/scored?industry=technology&min_score=60&limit=50"

GET /api/leads/score-distribution

Get distribution of lead scores by grade (analytics)

Response Example

{
  "success": true,
  "distribution": {
    "A": {"count": 1500, "avg_score": 87.5},
    "B": {"count": 5000, "avg_score": 68.2},
    "C": {"count": 12000, "avg_score": 48.1},
    "D": {"count": 8000, "avg_score": 28.4},
    "F": {"count": 3000, "avg_score": 8.2}
  },
  "total_leads": 29500
}

GET /api/leads/score/{entity_id}

Get detailed score breakdown for a single entity

cURL Example

curl "http://localhost:8080/api/leads/score/J3DDPT1EAKG6"

Batch API for External Apps

NEW

Efficient bulk data fetching for your other applications

What's Included By Default

Company Info

Name, city, state, zip, website, type

Industry

NAICS code + description + category

Emails (up to 3)

With names, titles, confidence

Pain Points (up to 3)

With severity and category

GET /api/batch/leads Recommended

Get leads with full data for industry-targeted outreach

Query Parameters

Parameter	Type	Description
`industry`	string	Recommended: technology, healthcare, construction, legal, finance, etc.
`naics`	string	NAICS code prefix (alternative to industry)
`state`	string	State code (TX, CA, NY, etc.)
`has_email`	string	Recommended: Set to "1" for leads with emails
`min_score`	int	Minimum lead score (0-100). Use 40+ for qualified leads.
`limit`	int	Max records (default: 100, max: 1000)
`offset`	int	Pagination offset
`minimal`	string	Set to "1" for faster response (excludes email/pain details)

Response Example

{
  "success": true,
  "leads": [
    {
      "entity_id": "J3DDPT1EAKG6",
      "company": {
        "name": "HAZARD CONTROL TECHNOLOGIES, INC.",
        "dba_name": "",
        "city": "FAYETTEVILLE",
        "state": "GA",
        "zip": "30214",
        "website": "http://www.hct-world.com",
        "business_type": "LLC"
      },
      "industry": {
        "naics_code": "541511",
        "naics_description": "Custom Computer Programming Services",
        "category": "technology"
      },
      "emails": [
        {
          "email": "mgreiner@hct-world.com",
          "first_name": "MICHAEL",
          "last_name": "GREINER",
          "name": "MICHAEL GREINER",
          "title": "CEO",
          "confidence": 90
        }
      ],
      "pain_points": [
        {
          "title": "Customer support response times",
          "severity": 4,
          "category": "customer_service",
          "source": "bbb"
        }
      ],
      "score": 72,
      "grade": "B"
    }
  ],
  "meta": {
    "count": 5,
    "limit": 100,
    "has_more": true,
    "filters": {
      "industry": "technology",
      "has_email": true
    },
    "tip": "Use has_email=1 for best results. Add min_score=40 for qualified leads."
  }
}

cURL Examples

# Technology companies in Texas with emails
curl "http://localhost:8080/api/batch/leads?industry=technology&state=TX&has_email=1"

# Healthcare leads with high scores
curl "http://localhost:8080/api/batch/leads?industry=healthcare&has_email=1&min_score=60"

# Construction companies - first 500
curl "http://localhost:8080/api/batch/leads?industry=construction&has_email=1&limit=500"

GET /api/batch/entity/{entity_id}

Get complete data for a single entity (all emails, all pain points, full intelligence)

cURL Example

curl "http://localhost:8080/api/batch/entity/J3DDPT1EAKG6"

Available Industry Keywords

technology software it services cybersecurity healthcare medical construction consulting legal accounting marketing finance real estate manufacturing logistics staffing education nonprofit + 30 more...

See all keywords: /api/export/keywords

Error Codes

Code	Description
`200`	Success
`400`	Bad Request - Invalid parameters
`401`	Unauthorized - Missing or invalid API key
`404`	Not Found - Resource does not exist
`500`	Internal Server Error
`503`	Service Unavailable - Database disconnected

Base URL

All API endpoints are relative to: http://localhost:8080

In production, replace with your deployed domain (e.g., https://api.yourdomain.com)