# Sleuth prospect engine

The record, screening and suppression system behind AI Sleuth research: a business becomes a prospect only when the research behind it is recorded with its source note, and every record is screened before it is stored.

Live at read: 0 prospect(s) recorded, 0 screened, 0 suppressed, 0 suppression(s) in force. Suppressions by reason: stop 0 · bounce 0 · complaint 0 · opt_out 0.

## The source-note rule
Source-note rule: every prospect record carries a source note of at least 10 characters after trimming. The source note is mandatory — a create whose source_note is under 10 characters is refused 422 sleuth_prospect_invalid and nothing is stored. Every statement drawn from a prospect record traces to its source note.

## Screening
Screening rule: every prospect create is screened in this order, with all validation before any store — field validation (business_name 1-120 characters, trade 1-80, city 1-80, state a two-letter US state code stored uppercase, email a valid business email address stored normalized lowercase, observed_signal 1-500, pain_angle 1-500, and source_url and website, when present, http(s) URLs of at most 500 characters); then the source-note rule; then the role-risk rule, which refuses an email whose local part is postmaster, abuse, noreply, no-reply, mailer-daemon, root or webmaster with 422 sleuth_prospect_invalid; then the suppression check; then the dedupe check. A refused create stores nothing.

## Dedupe
Dedupe rule: dedupe is global across all accounts. Creating a prospect whose normalized email is already recorded, or whose normalized business name, city and state are already recorded, is refused 409 sleuth_prospect_duplicate and nothing is stored. Business name and city are normalized by trimming, lowercasing and collapsing internal whitespace; state is normalized uppercase; email is normalized by trimming and lowercasing.

## Suppression: immediate and permanent
Suppression rule: suppression is immediate and permanent. Adding an email to the suppression store (reason stop, bounce, complaint or opt_out) takes effect at once, flips every existing prospect record with that email — in any account — to status suppressed, and can never be removed: there is no delete and no un-suppress route. Creating a prospect whose normalized email is suppressed is refused 409 sleuth_prospect_suppressed. Re-adding an already suppressed email is idempotent: it returns the existing suppression record and never duplicates it. The suppression list is published as email hashes only — no raw email ever appears in the suppression list or the index document.

## Counting
Counting rule: the usage counts in this document are computed at read time from live accounts only — sandbox and other non-live accounts are excluded. prospects_total counts prospect records stored for live accounts; prospects_screened and prospects_suppressed split that total by record status; suppressions_total counts suppression records added by live accounts, split by reason in suppressions_by_reason; prospects_by_trade counts live accounts' prospect records grouped by trade. The screening checks themselves are global across all accounts, including accounts excluded from these counts: a suppression added by any account blocks every account, and dedupe compares against every recorded prospect. No email, business name or source note ever appears in this document — counts only.

## Surfaces
- GET /v1/sleuth/prospect-engine (free, no key) — this index document: the source-note, screening, suppression, dedupe and counting rules printed verbatim, the surfaces, and live usage counts computed from live accounts only
- POST /v1/sleuth/prospects (owner account key) — record one researched prospect after screening; returns the caller's own prospect view including its email
- GET /v1/sleuth/prospects (owner account key) — the caller's own prospect records only
- POST /v1/sleuth/suppressions (owner account key) — suppress one email immediately and permanently; flips every existing prospect with that email to suppressed; idempotent on re-add
- GET /v1/sleuth/suppressions (owner account key) — every suppression as email hash, reason and creation time only; no raw email is ever listed
- GET /sleuth-prospects (page) and GET /sleuth-prospects.md — the human-readable twin of this document

Machine-readable index: https://www.a2ally.com/v1/sleuth/prospect-engine · Sleuth home: https://www.a2ally.com/sleuth · Sending foundation: https://www.a2ally.com/sleuth-send