# LostPropertyFinder — agent guide

Free unclaimed-property lookup, and a Shoeboxed lead-gen engine. If you are an AI
agent working the calling-lead pipeline, here is how to use this app.

## Lead API (JSON, token-protected)

Auth: `Authorization: Bearer <token>`. The token is NOT public — get it with
`heroku config:get LEADS_API_TOKEN -a lostproperty` (or ask the operator).

- `GET  /api/leads/next?limit=25` — the CALL queue: highest-scoring leads that
  have a phone and are not carded yet. Returns JSON `{count, leads[]}`.
- `GET  /api/leads/to_research?limit=12&niche=accounting_tax` — the RESEARCH
  queue: good-niche uncarded leads that still need a phone. Slice by `niche` so
  parallel researchers don't overlap. Returns leads + their records.
- `GET  /api/leads/:id` — one lead plus its unclaimed-property records.
- `POST /api/leads/:id/enrich` with any of `{phone, phone_source, phone_line_type,
  phone_caller_id, email, email_source, website, person_name}` — write research
  findings back (blanks ignored). This is how a researcher records a phone/email.
- `POST /api/leads/:id/card` with `{basecamp_card_id, notes}` — mark a lead
  carded so it drops out of the queue.

Researcher loop: GET /to_research?niche=X → for each lead find a name-matched
phone (Twilio-verify it) + an email FROM THE BUSINESS'S OWN SITE ONLY → POST
/enrich → build a card (up-card skill) → POST /card. No CSV files; the DB is
the source of truth.

Example:
`curl -H "Authorization: Bearer $TOKEN" https://www.lostpropertyfinder.com/api/leads/next?limit=25`

## How the pipeline works

- A "lead" is one business (owner_name + zip). It owns many unclaimed-property records.
- The machine (Rails) builds and enriches leads: `rake leads:build`, `rake leads:enrich`
  (free phone sources: NPI for medical/therapy, FMCSA for trucking). Scoring answers
  "can we reach a human by phone?" — dollar amount is never scored.
- Your job as an agent: pull the queue, do the judgment work a machine can't
  (confirm the business is alive, check the owner isn't deceased, confirm the phone's
  CallerID matches, write the sales card with the `up-card` skill), post the card to
  Basecamp, then POST /card to mark it done.
- The database is the source of truth. Do not pass leads around as CSV files.

Full internal docs: the repo's CLAUDE.md (Shoeboxed/lostproperty/CLAUDE.md).
Public human pages: /, /states, /how_to_claim_money.