Documentation

Every lead moves through the same ordered flow. Each stage is a status on the lead and a column on the boards:

vet → research → outreach → agreement → claim → payment

The app is owner-only and local-first: it is the operator's private workbench, not a multi-tenant SaaS. Money is tracked in integer cents everywhere.

• Lead — one unclaimed-property record from the SCO database, tracked through its whole lifecycle.
• Property — the unclaimed asset itself (bank account, securities, uncashed check, …) with a holder, balance, county, and reported owner.
• Owner — the person, business, estate, or trust the property belongs to.
• Contact — a phone, email, or address found during research or imported, with a source citation and a verification state.
• Prospect / Candidate — a lead that has been promoted into active outreach. Tracked separately with its own touch-count stages.
• Campaign — an ordered set of leads sharing a pipeline, workflow, cadence, and guardrails.
• Pipeline — a reusable set of board stages a campaign runs on.
• Workflow— a reusable automation graph (nodes + edges) that runs against a campaign's leads.
• Automation — a rule that binds a workflow to events and enqueues agent jobs, subject to conditions and approval gates.
• Agent job — an async task handed to an AI provider (e.g. vet_lead, run_research, place_call).
• Cadence — a multi-touch outreach sequence (e.g. SMS → wait → SMS → wait → voicemail).
• Voice agent — an AI assistant on the phone (Deepgram, ElevenLabs ConvAI, or Retell) that speaks alone or assists the operator live.
• Agreement — the SCO-supplied investigator contract, signed by the claimant, gate-checked for §1582 compliance.
• Claim — the package of documents filed with the SCO to recover the property.
• §1582 gate — hard, code-enforced compliance rules (fee cap, timing bar, no upfront fees, written agreement, full disclosure). See Compliance.

Records are imported from the SCO dataset (npm run import loads unclaimed.csv). Every record is imported and tagged by claim bucket rather than filtered out, so nothing is lost: main, mid_value, and the hard_* buckets (bad addresses, business, estates, multiple claimants, pending/paid, catch-all).

• Search by owner name, property ID, or holder.
• Filter by county, property type, and owner type (person, business, estate, trust, unknown).
• Value range (min/max dollars).
• Phone status (has phone / no phone / missing) and phone type (has mobile / has landline) once PhoneValidator has run.
• Has-contact, has-address, and risk-flag tags (business, estate, multi-claimant, bad-address, pending/paid, securities, mid-value).

Stack up to three sort keys with independent directions — e.g. lead score ↓, then record age ↑, then value ↓. Sort by owner, first name, property ID, street, location, county, property type, balance, or AI score.

The lead status is the single source of truth for where a lead sits in the pipeline:

vetting → qualified → researching → contact_found → candidate → outreach → replied → agreement_sent → agreement_signed → claim_assembling → claim_filed → claim_approved → paid → closed

Two terminal states sit outside the happy path: dead (ineligible or opted out) and unreachable (no valid contact route after research). A closed lead can still be reclaimed.

Leads carry a baseline AI score from vetting and an enriched score after research, with a parts breakdown that explains the components. High-value or promising leads can be starred by the operator or an agent.

Opening a lead (/leads/[id]) gives a tabbed workspace:

• Overview — property details, owner info, flags, score.
• Research — agentic web-research results, evidence documents, and found contacts.
• Outreach — drafted messages, send history, and replies.
• Agreement — the §1582-compliant agreement form, fee terms, and signature status.
• Claim — the claim status board and the required-documents checklist.
• Activity — a chronological log of every action taken on the lead.

Contacts are extracted from research or captured via the browser extension. Each phone is classified (mobile, landline, VoIP, toll-free, invalid, unknown) and carries a verification state. SMS eligibility is checked server-side before any send, and a contact route can be reviewed and marked (verified working/owner/relative, voicemail left, disconnected, or removed as a bad/unrelated route).

new → hot → first_touch_sent → followup_1_sent → followup_2_sent → fourth_touch_sent → fifth_touch_sent → five_plus_touch_sent → cold → dead

hot marks a high-priority prospect (often reordered to the front of outreach); cold is set when a sequence finishes with no engagement; dead means opted out, unreachable, or uninterested.

Switch between a card gallery and a list. Filter by stage, county, property type, owner type, value range, and phone status, or search by name/property ID. Each card links into the same tabbed workstation as the inbox.

• AI-assisted builder— describe the goal in plain language (e.g. “target personal owners between $10k–$100k, automate SMS, no voice agents, don't mark anything dead without approval”). The builder asks clarifying questions, then generates a campaign configuration for review.
• Manual builder — set name, description, and priority; select leads with the same filters as the inbox; choose a workflow, sequence, pipeline, and cadence preset; and configure guardrails.

Where /campaigns/new

• Priority — controls execution order when several campaigns are active.
• Status — active or paused (per-lead run state can be active, paused, needs_review, done, or dead).
• Members & active runs — how many leads are in the campaign and how many are in progress.
• Total value — the summed property balance of the cohort.
• Linked pipeline & workflow — the board it runs on and the automation graph it executes (each can be shared or campaign-specific).
• Cadence preset — the multi-touch sequence the campaign uses.

AI-built campaigns are generated, then compiled, and stay inactive until you explicitly activate them — so you always review the plan and guardrails before any lead is contacted.

A workflow is JSON: nodes (agent jobs) connected by edges (order and branching). For example: vet_lead → if qualified → run_research → place_call → if no answer → drop_voicemail → send SMS. A workflow must be compiled before it can run.

The handlers a node can invoke:

• vet_lead — score a lead on eligibility (the one fully-live handler).
• plan_research / run_research — generate a research plan, then run agentic web research (via the Codex provider).
• find_contact / verify_contact — extract and validate contact details from research.
• triage_reply — classify an inbound reply (interested / uninterested / needs review).
• place_call / drop_voicemail — place a voice-agent call and branch on the outcome, or leave a templated voicemail.
• run_outreach_sequence — execute a multi-touch cadence.
• process_inbound_contact — handle inbound leads/callbacks.
• assess_claim_requirements — review documents for claim filing.
• critique_call / review_hot_retell_call — post-call analysis and coaching.
• suggest_followups — propose next steps; orchestrate — a planned master job that runs sub-tasks.

• Trigger events — e.g. a lead promoted to candidate, moved to outreach, or a reply received.
• Conditions— optional guards (value > $50k, owner type is person, not yet contacted, …).
• Actions — enqueue an agent job with its config.
• Approval gates — sensitive actions (marking dead, major status changes) wait for operator review before running.
• Scoping— automations can target one campaign's leads or the whole workspace.

• SMS — via Google Voice or Lob.
• Voice — via Retell, ElevenLabs ConvAI, or Deepgram (see Call Center).
• Direct mail — via Lob.
• Email — drafted by AI, sent manually after review.

Templates are reusable across campaigns and prospects, keyed by kind (SMS / email / call_script), channel, and category (cold / followup / reply), with variables like {{contact_first_name}} and {{holder_name}}.

Pre-built touch sequences mix SMS, calls, and voicemails over time (e.g. SMS → 3 days → SMS → 7 days → voicemail + SMS), executed by the run_outreach_sequence job.

• Rate cap — maximum SMS per calendar day.
• Per-lead spacing — minimum gap between touches to the same lead.
• Max touches per lead — a hard ceiling on total outreach.
• Verified-contact-only — SMS only to numbers classified as mobile.
• Do-not-contact (DNC) — blocks all automated sends to a flagged lead.
• Quiet hours — respects the configured send window.

Automated sends obey all of the above; a human operator can override individual sends.

• Live calls (/call-center/live) — outbound to a prospect, in either Live mode (operator on the call, agent assists) or Agent mode (the voice agent speaks alone). Recording requires explicit consent.
• Outbound agent (/call-center/outbound-agent) — agent-driven dialing through a campaign.
• Inbound — a Retell-provisioned receptionist answers callbacks and can warm-transfer to the operator.
• Training (/call-center/training) — role-play where the AI plays the prospect; records, transcribes, and gives coaching feedback.

• Deepgram — real-time speech-to-text + text-to-speech via a local audio bridge (runs in the browser; no cloud telephony).
• ElevenLabs ConvAI — cloud voice agent with calls routed through a signed-in Google Voice session.
• Retell AI — cloud-native telephony; places outbound calls and runs the inbound agent via its API and webhooks.

Call and voicemail scripts are rendered per lead from templates and include the mandatory §1582 disclosures (10% fee cap, no upfront cost, the free option to file directly with the SCO, and that a written agreement follows). Calls are transcribed live with confidence scores; outcomes flow through the call-session states (dialing → recording → transcribing → critiquing → done) and a disposition is recorded. A critique_call job can analyze the transcript afterward and suggest improvements.

• Standard — Abandoned Property: for regular unclaimed property; fee capped at 10% of recovery (enforced in code).
• Estates: for probate estates; fee uncapped by statute but flagged for review when above 10%, and requires the probate court case number and county.

Before an agreement can be sent, blockers must clear: the property must be timing-eligible (SCO-held ≥ 12 months or notice published), the fee must be within cap, disclosure must be complete (owner name + amount), the investigator's identity must be set, and the lead must not be marked do-not-contact. Warnings (e.g. an estates fee over 10%, or a missing holder) are surfaced but don't block.

Generate the form → review and adjust the fee → clear the gate → send for signature → track signature status. A signed agreement is what unlocks claim filing.

assembling → docs_collected → filed → in_review → additional_info_requested → approved → paid → denied

Cards show owner name, balance, and age; stale claims (≈90+ days) are flagged.

• Work a per-claim document checklist (different docs for abandoned property vs. estates) and mark items as collected.
• File the assembled package with the SCO and track the submission and approval.
• On payment, reconcile against the agreement: the fee is a percentage of recovery (capped at 10% for the standard form), paid only after the SCO pays — no upfront fee.

• Look up a target by property ID or lead number with auto-suggest.
• Parse the current page for names, phones, emails, addresses, and documents — add any item (with its source) to the lead, individually or in bulk.
• Send an SMS or place a call from the panel via Google Voice, with §1582 guardrails checked server-side.

A reference view: lead summary (owner, address, property ID, balance, holder), stored contacts with copy buttons, and auto-built research links (people-search sites, Google, obituaries, CA Secretary of State for businesses, county probate for estates, and the SCO record).

Generate a per-user extension API key, set CLAIMDESK_EXTENSION_API_KEY and CLAIMDESK_EXTENSION_ORIGIN in the app environment, paste the key and app URL into the extension options, and sign into voice.google.com in the same Chrome profile.