AI Lead Intelligence System

Evidence-backed lead discovery and qualification with n8n, OpenAI, Google Places, PageSpeed, Hunter, and Google Sheets.

Executive summary

AI Lead Intelligence is a configurable three-workflow n8n system that discovers businesses, consolidates duplicate records, ranks candidates, collects public evidence, verifies contact data, identifies service opportunities, and routes each candidate to Qualified, Needs Review, or Rejected.

The core design choice is deliberate: AI is used for search and conservative evidence extraction, while deterministic JavaScript controls scoring and final qualification. A candidate cannot pass merely because a model produced a persuasive description or a numeric score. Required contacts, market fit, company-size fit, evidence strength, source conflicts, and the campaign threshold are evaluated as separate gates.

The system ends at research and qualification. It does not send outreach, message prospects, or book meetings.

The problem

Traditional lead lists often fail at the point where they become operational:

• sources disagree about the business, decision-maker, or contact information;
• the first search result is accepted before better candidates are compared;
• generated emails are mistaken for verified public contacts;
• weak observations such as missing JSON-LD are presented as urgent sales problems;
• AI-written summaries are allowed to make the final qualification decision;
• partial failures are hidden, making the output difficult to audit;
• large batches create rate-limit, duplication, and retry problems.

The engineering problem was therefore not simply “find leads.” It was to build a repeatable evidence pipeline whose decisions remain explainable after the workflow finishes.

What the system does

• Defines campaigns through a 34-field Google Sheets control row.
• Discovers candidates through Google Places and OpenAI web search.
• Oversamples before ranking, rather than researching the first result returned.
• Merges duplicate businesses using Place ID, normalized domain, phone, and name/location signals.
• Normalizes equivalent industries such as Real Estate Agent, Real Estate Agency, Brokerage, and Realtor.
• Audits websites, supporting pages, robots.txt, sitemap.xml, mobile PageSpeed, metadata, and sampled broken pages.
• Extracts complete 7–15 digit international phone numbers and rejects partial fragments.
• Prioritizes official-site contacts and detects conflicts with third-party sources.
• Uses Hunter Domain Search and Email Verifier for public email evidence.
• Supports an optional approved LinkedIn enrichment adapter without embedding cookies or bypass logic.
• Uses strict JSON Schema for OpenAI discovery and evidence extraction.
• Applies a transparent 100-point score and independent hard gates.
• Upserts research, qualified leads, and run summaries into Google Sheets.
• Keeps provider diagnostics visible without erasing successful evidence from other providers.
• Processes 1, 5, or 10 candidates sequentially with configurable spacing and retries.

Architecture

flowchart TD
    A["Google Sheets Control"] --> B["Master Orchestrator"]
    B --> C["Candidate Discovery"]
    C --> D["Oversampled candidate pool"]
    D --> E["Deduplicate and rank"]
    E --> F["Research & Qualification"]
    F --> G{"Deterministic decision"}
    G -->|Pass all gates| H["Qualified Leads"]
    G -->|Incomplete or conflicting| I["Needs Review"]
    G -->|Fails target or opportunity| J["Rejected"]
    B --> K["Run Log"]
    F --> L["Research Queue"]

Loading

Component	Responsibility	Size
Master Orchestrator	Campaign validation, sub-workflow execution, sequential processing, caps, persistence, and run accounting	29 nodes
Candidate Discovery	Google Places and OpenAI discovery, cross-source merge, target-fit ranking, and final candidate cap	13 nodes
Research & Qualification	Website/contact research, evidence extraction, scoring, hard gates, and output shaping	40 nodes
Google Sheets	Campaign control, evidence registry, qualified output, run log, and controlled lists	5 tabs

See Architecture and execution flow for the node-stage maps and data contracts.

End-to-end flow

1. An operator fills a campaign row in Control while Active remains FALSE.
2. After review, the operator sets exactly one row to TRUE.
3. The Master is executed manually.
4. Campaign values are parsed, normalized, bounded, and validated.
5. Discovery builds an oversampled pool from enabled providers.
6. Duplicate businesses are merged and ranked for target fit and evidence quality.
7. The best Maximum Candidates records enter a sequential research loop.
8. The registry prevents unnecessary re-research before Recheck After Days.
9. Research collects website, performance, contact, and optional enrichment evidence.
10. gpt-4o-mini structures only the supplied research evidence.
11. Deterministic code validates sources, calculates the score, and applies hard gates.
12. Every researched record is upserted to Research Queue.
13. Passing records are capped and upserted to Qualified Leads.
14. The Master writes aggregate counts and execution status to Run Log.

Active = TRUE selects the campaign; it does not launch the current version automatically. The Master uses a Manual Trigger. Sheet-only launch automation requires a future request/claim/lock mechanism to prevent duplicate executions.

Evidence model

Evidence is evaluated by source and by claim:

Tier	Typical sources	Use
1	Official business website, public registry	Identity, decision-maker, contacts, services
2	Google Places, measured PageSpeed output	Business status, location, public phone, technical measurements
3	Hunter public sources, approved LinkedIn adapter	Contact and role enrichment
4	OpenAI web discovery with public source URLs	Complementary candidate discovery
5	Inference	Review support only; never a substitute for required evidence

Important claims carry their own source URLs. A URL being on the correct domain is insufficient: the exact supplied URL must be part of the known evidence set.

Qualification model

The score has five bounded components:

Component	Maximum	What contributes
Problem evidence	30	Weighted strong, moderate, and weak opportunity signals
Contact quality	30	Decision-maker, email quality, phone, and sourced contact combination
Service fit	20	A defensible issue mapped to an allowed campaign service
Market fit	10	Geography and normalized industry match
Evidence	10	Distinct source coverage minus conflict penalties
Total	100	Used together with hard gates

A high score is necessary but not sufficient. Auto-qualification also requires:

• operating business evidence;
• target industry and geography;
• at least one defensible issue mapped to an offered service;
• a strong signal or two independent moderate signals when enabled;
• acceptable company-size evidence when a target is configured;
• required decision-maker, email, and/or phone evidence;
• no unresolved source conflict;
• the configured minimum score.

Missing JSON-LD, robots.txt, sitemap.xml, or one optional metadata field is weak evidence by itself and cannot satisfy the strong-opportunity gate.

See Qualification and scoring for exact rules.

Technology stack

Layer	Technology
Orchestration	n8n
Workflow logic	JavaScript Code nodes
Campaign and operations layer	Google Sheets
Business discovery	Google Places API, OpenAI web search
Evidence extraction	OpenAI gpt-4o-mini with strict JSON Schema
Website research	n8n HTTP Request nodes and deterministic HTML parsing
Performance	Google PageSpeed Insights
Email enrichment	Hunter Domain Search and Email Verifier
Optional enrichment	Approved LinkedIn adapter

The exported templates use /v1/chat/completions for their tested OpenAI contracts. Review provider model availability and pricing before deployment.

Project status

Status: controlled production testing.

The production-hardening regression suite passed 234 checks covering:

• JSON structure, node names, and graph connections;
• embedded JavaScript syntax;
• retry and delay configuration;
• Google Sheets schema alignment;
• HTTPS redirect handling;
• complete US and international phone parsing;
• partial-phone rejection;
• industry equivalence;
• ranking before candidate capping;
• strong-opportunity gating;
• source-conflict review routing;
• workbook formula and layout validation.

A controlled five-candidate test discovered 22 raw candidates, merged six duplicates, researched the five highest-ranked records, encountered zero technical errors, and routed all five to human review because required decision-maker or company-size evidence was incomplete. This is a validation snapshot, not a benchmark or guarantee of future lead quality.

An earlier single-candidate test exposed two defects—incorrect HTTPS status after redirects and a partial (917) phone match. Both defects were corrected and added to regression tests. That learning loop is documented in Testing and validation.

Repository structure

n8n-ai-lead-intelligence/
├── README.md
├── LICENSE
├── CHANGELOG.md
├── CITATION.cff
├── workflows/
│   ├── 01-master-orchestrator.json
│   ├── 02-candidate-discovery.json
│   └── 03-research-and-qualification.json
├── templates/
│   └── AI_Lead_Intelligence_Template.xlsx
├── examples/
│   ├── sample-campaign.tsv
│   └── sample-results-anonymized.csv
├── docs/
│   ├── architecture.md
│   ├── setup-guide.md
│   ├── configuration-reference.md
│   ├── qualification-and-scoring.md
│   ├── spreadsheet-data-dictionary.md
│   ├── api-and-model-contracts.md
│   ├── testing-and-validation.md
│   ├── troubleshooting.md
│   ├── security-and-privacy.md
│   └── limitations-and-roadmap.md
├── assets/
└── validation/

Quick start

1. Import the workbook

Upload AI_Lead_Intelligence_Template.xlsx to Google Drive and open it as a native Google Sheet. Keep these tab names unchanged:

1. Control
2. Qualified Leads
3. Research Queue
4. Run Log
5. Lists

The workbook contains one inactive fictional campaign and no live leads.

2. Import workflows

Import in this order:

1. workflows/02-candidate-discovery.json
2. workflows/03-research-and-qualification.json
3. workflows/01-master-orchestrator.json

The public exports intentionally contain no credential IDs, Google Sheet ID, tab GIDs, n8n instance ID, or sub-workflow IDs.

3. Configure credentials

Create and select:

• Google Sheets OAuth2;
• Google Places header authentication;
• Google PageSpeed query authentication;
• Hunter header authentication;
• OpenAI API;
• optional approved LinkedIn adapter configuration.

Store secrets in n8n credentials. Do not paste API keys into Code, Set, or Sticky Note nodes.

4. Bind resources

• Point every Master Google Sheets node to the imported workbook.
• Confirm each node uses the correct tab shown in the setup guide.
• In Execute Discovery Workflow, select the imported Discovery workflow.
• In Execute Research Workflow, select the imported Research workflow.

5. Run a controlled test

• Keep the example campaign inactive while editing.
• Configure one city and one industry.
• Start with Maximum Candidates = 1.
• Set Active = TRUE only after validation.
• Execute the Master manually.
• Audit every saved source, contact, and score.
• Increase to 5, then 10 only after the prior stage passes.

Full instructions: Setup guide.

Campaign example

The repository includes a tab-separated 34-column example:

Demo — Bengaluru dental clinics
India → Bengaluru
Dentist; Dental Clinic
Independent / SMB
Local SEO; Website Redesign; Performance Optimization; Google Ads
Balanced, score 70, review 55, research 5, qualified cap 3

Use sample-campaign.tsv for a direct spreadsheet paste.

Security and publication safety

• No API key is embedded.
• Credential bindings are removed.
• Google Sheet document IDs and tab GIDs are removed.
• n8n workflow and instance identifiers are removed.
• The workbook contains no real research rows.
• Examples use reserved .example domains and fictional contacts.
• Outreach is intentionally excluded.

Read Security and privacy before using public business data.

Known limitations

• The current Master requires manual execution.
• Public sources can be stale, incomplete, blocked, or contradictory.
• Static HTTP parsing cannot fully inspect every JavaScript-rendered website.
• Company-size evidence is often unavailable.
• Hunter verification indicates deliverability status, not guaranteed current identity ownership.
• Provider pricing and rate limits bound throughput.
• Optional LinkedIn enrichment requires an approved external adapter.
• Human review remains necessary before outreach.
• The workflow has not been benchmarked as a universal lead-quality system.

Roadmap

• Sheet-only run requests with atomic campaign claiming and duplicate-run protection.
• Scheduled execution with run locks and idempotent recovery.
• Resumable long-running batches.
• Adaptive provider budgets and backoff.
• JavaScript-rendered website inspection.
• Stronger company-size enrichment.
• Review/approval interface.
• Evidence freshness and historical score comparison.
• CRM export adapters.
• Automated parser and scoring fixtures in CI.

Detailed trade-offs and roadmap: Limitations and roadmap.

Documentation

Guide	Purpose
Architecture	System topology, workflow stages, and data movement
Setup	Import order, credentials, resource binding, and first run
Configuration reference	Control fields, defaults, bounds, and strictness modes
Qualification and scoring	Score components, evidence strength, and hard gates
Spreadsheet data dictionary	All 176 workbook fields across five tabs
API and model contracts	Provider roles, request contracts, and failure handling
Testing and validation	Regression coverage and controlled rollout plan
Troubleshooting	Common import, API, parsing, and data-quality failures
Security and privacy	Secret handling, publication safety, and responsible use
Limitations and roadmap	Boundaries, trade-offs, and next engineering phases

Responsible use

Use only public business information for a legitimate, documented purpose. Respect applicable privacy, marketing, anti-spam, platform, and data-retention requirements. Verify every candidate before contacting them and honor suppression or opt-out status.

License

MIT — see LICENSE.