BE-Lead-Hunter

Find business candidates by US city and category, collect public contacts from their websites, and export review records with evidence and missing-data flags.

Version scope: fresh-discovery instructions below apply to standalone builds 0.5 and later. Version 0.4.1 requires supplied data for its starting mode and does not support this fresh-discovery workflow. Select the intended build before starting. Dated deployment and acceptance status is recorded separately in the project release report.

Fresh research

For a validated standalone build 0.5 or later:

1. Select fresh_leads. Enter country, state, city, category and 1–25 results.
2. Enable fresh discovery and public website collection. Keep credentials out of input; Apify supplies the runtime identity privately.
3. Set run options: 512 MB, 900 seconds, restart off and a finite maximum charge. Parent and child spending limits are separate.
4. Start once. Inspect the Dataset and RUN_SUMMARY. Download fixed files FRESH_REVIEW_CSV and FRESH_REVIEW_JSON from the run's key-value store. Apify's dataset export also offers Excel formats.

Small first-run example (set the parent Console/API maximum charge to $0.25):

{
  "runMode": "fresh_leads",
  "country": "US",
  "state": "TX",
  "city": "Dallas",
  "category": "roofing contractor",
  "maxLeads": 3,
  "maxPagesPerWebsite": 2,
  "enableFreshDiscovery": true,
  "enableLiveRequests": true,
  "maxRunCostUsd": 0.75,
  "discoveryBudgetUsd": 0.5,
  "parentReserveUsd": 0.1,
  "collectionReserveUsd": 0.1,
  "exportReserveUsd": 0.05
}

The example allows at most $0.25 for the parent and $0.50 for the single Maps source run. Their sum fits $0.75. These limits do not settle future retained storage, transfer or delayed adjustments. The complete-job input policy never exceeds $54.99. Source prices can change; the pinned reviewed source profile expires and must be refreshed deliberately.

Outputs and limits

Records include business/location/source identifiers, website, available public email/phone/social evidence, observation dates and collection outcomes. Every source row retains a disposition, including duplicate, out-of-city, no-site and blocked-page records. Search results need human category and attribution review. Shared group/brokerage/domain contacts can remain uncertain.

Emails are not mailbox-verified. Social links do not establish account ownership. Missing contacts are not invented. Basic website observations are not a full SEO, advertising, buying-intent or service-needs audit. No AI, n8n workflow, email verification or sending is performed.

This standalone backend uses the current parent run's Apify storage; Supabase is not required. One coordinator/process must own the run. There is no shared account ledger, global request-key deduplication, distributed lock or exactly-once guarantee. A new parent run is a new budgeted job, even with the same request label. Unknown submission, collection or append outcomes stop without automatic retry. Do not start another paid run to bypass an uncertainty hold. Completed same-run replay verifies its files and does not append again.

Public HTML collection follows robots policy and TLS/IP safeguards within fixed page/request/byte/time limits. JavaScript-only, blocked and inaccessible sites may yield no contacts. No logged-in social scraping, CAPTCHA bypass or email guessing.

Other modes and development

snapshots handles supplied records and HTML without live discovery; its default listing is fictional. fresh_plan prepares an explicit fresh request without starting the source. Legacy planning, reuse, simulation, reviewed collection and database-review modes retain their existing narrower requirements. Shared database persistence remains a separate unfinished integration.

Offline tests: python -B -m unittest discover -s tests -v. Dependencies are locked by version/hash. Fixture tests are not live operation acceptance.

• docs/STANDALONE_RELEASE_CANDIDATE_20261027.md
• docs/PROJECT_STATUS_20261026.md
• docs/CURRENT_WORK.md
• docs/PUBLIC_ACTOR_RELEASE_20261026.md
• docs/FRESH_TAIL_COMPONENTS_20261027.md

n8n remains paused. Historical cost reconciliation is the user-deferred Dev part. Source packages exclude credentials, real lead exports and database files.