# Contact Search

<!-- BEGIN GENERATED: guide-map -->
## Guide map

Read only the section needed for the next decision. Line ranges are exact
for this generated runtime target.

| Section | What it covers | Lines |
| --- | --- | --- |
| [Purpose](#purpose) | Scope, ownership, and the central operating question. | 27-31 |
| [Use This When](#use-this-when) | Tasks and conditions that belong in this guide. | 32-36 |
| [Do Not Use This For](#do-not-use-this-for) | Boundaries and the correct routes for excluded work. | 37-46 |
| [Choose A Path](#choose-a-path) | Decision hierarchy for selecting the right capability or provider. | 47-67 |
| [Primary SDK Paths](#primary-sdk-paths) | Operating guidance and contracts for this section. | 68-78 |
| [Supporting References](#supporting-references) | Capability, provider, policy, and runtime guides for this outcome. | 79-91 |
| [Mental Model](#mental-model) | Concepts and state boundaries needed for correct operation. | 92-105 |
| [Preflight](#preflight) | State, authority, inputs, and readiness to verify before execution. | 106-116 |
| [Risk And Side Effects](#risk-and-side-effects) | Effects, approvals, cost, privacy, and retry boundaries. | 117-126 |
| [Canonical Operating Pattern](#canonical-operating-pattern) | The normal end-to-end execution sequence. | 127-141 |
| [Data Contracts](#data-contracts) | Required identities, fields, evidence, handles, and durable shapes. | 142-155 |
| [Verification](#verification) | Evidence required before reporting success. | 156-163 |
| [Troubleshooting](#troubleshooting) | Failure diagnosis and corrective routes. | 164-173 |
| [Related References](#related-references) | Adjacent boundaries and when to cross them. | 174-183 |
<!-- END GENERATED: guide-map -->

## Purpose

Find the right people at target companies while preserving identity, role, and
source evidence. Company discovery and contact enrichment are separate outcomes.

## Use This When

Use this guide when the requested rows are people who have not yet been
identified. Use `contact-enrichment.md` when the people are already known.

## Do Not Use This For

| Need | Owning Guide |
| --- | --- |
| Discover or qualify the target company universe | `company-search.md` |
| Add email, phone, profile, or other facts to known people | `contact-enrichment.md` |
| Inspect relationships, conversations, or perform LinkedIn actions | `linkedin-outreach.md`, then `linkedin.md` |
| Transform, join, score, or export people already acquired | `row_operations.md`, then `artifacts.md` |
| Stage or activate an outbound audience | `outbound-campaigns.md` and `safety.md` |

## Choose A Path

1. Define the person membership predicate, target company set, role or seniority
   rules, and required evidence.
2. Choose the first matching path below. Search for people only after the target
   company universe is explicit.
3. Run a bounded sample, verify current company and role evidence, then scale
   one path. Add a fallback only for a measured coverage gap.
4. Resolve ambiguous identities before enrichment or activation.

| Starting point | First path | Use another path only when |
| --- | --- | --- |
| Known companies with LinkedIn company URLs | `audience_discovery.md` people-at-company source | Required role filters or coverage are not supported. |
| Known company names or domains without canonical company identifiers | Resolve domains or LinkedIn company URLs through `company-enrichment.md`, then use people-at-company search | The resolver cannot establish company identity. |
| Broad person ICP without a fixed company list | `audience_discovery.md` targeted people search | The required filter is provider-specific and absent from the canonical source. |
| Clay-native person, role, company, or lookalike filters | `clay.md`; inspect the live people filter catalog first | Clay cannot express the membership predicate or sample quality is inadequate. |
| Current LinkedIn role, relationship, or activity evidence for candidate people | `linkedin.md` after candidate discovery | A profile database or web source is more authoritative for the requested field. |

Do not treat a request for a role, leader, employee, or decision-maker at known
companies as company search. The output entity is a person.

## Primary SDK Paths

<!-- BEGIN GENERATED: primary-sdk-paths -->
| Primary function | Choose it when | Required inputs | Returns | Exact contract |
| --- | --- | --- | --- | --- |
| `vf.clay.search_people` | Use Clay's structured people filters for a bounded result set without first supplying a canonical target-account list. | `filters` | `clay_search_results` | [`clay.md`](clay.md) · installed SDK: `verbiflow/clay.py:41-78` |
| `vf.linkedin.search_people_start` | Use LinkedIn-native people filters when LinkedIn identity and search semantics are the required source. | `url` | `pending_artifact_job` | [`linkedin.md`](linkedin.md) · installed SDK: `verbiflow/linkedin.py:340-405` |
| `vf.sources.people.find_at_companies_start` | Use when you already have target companies and need people at those accounts by title and location. | None | `pending_artifact_job` | [`audience_discovery.md`](audience_discovery.md) · installed SDK: `verbiflow/sources.py:99-205` |
| `vf.sources.people.targeted_search` | Use for a durable people-search audience that combines company, title, location, or pasted-account inputs and may need paging or reuse. | None | `pending_artifact_job` | [`audience_discovery.md`](audience_discovery.md) · installed SDK: `verbiflow/sources.py:22-97` |
<!-- END GENERATED: primary-sdk-paths -->

## Supporting References

Open only the child that resolves the next material decision.

| Reference | Use it for | Kind |
| --- | --- | --- |
| [`audience_discovery.md`](audience_discovery.md) | Provider-neutral acquisition, qualification, source quality, and audience evidence. | capability |
| [`row_operations.md`](row_operations.md) | Deterministic row transforms, joins, and reviewable LLM qualification or annotation with rationale and confidence. | capability |
| [`clay.md`](clay.md) | Clay Public API people and company search filters, bounded immediate results, durable artifacts, accounting, and workspace pacing. | provider |
| [`linkedin.md`](linkedin.md) | LinkedIn reads, search, activity, conversations, messages, connections, and posts. | provider |
| [`parallelism.md`](parallelism.md) | Bounded consolidation, concurrency, retries, deadlines, and no-progress guards. | policy |
| [`sources.md`](sources.md) | Classify ambiguous source-shaped work and choose the owning acquisition surface. | policy |

## Mental Model

Contact search proves that a specific person belongs in a target role at a
specific company now. A name or provider row is not sufficient identity. Keep
company qualification, person discovery, current-role verification, and later
contact enrichment as separate stages with separate evidence.

| Object | Meaning |
| --- | --- |
| Target account | A company already qualified for the task. |
| Candidate person | A possible role match returned by a source. |
| Qualified contact | A resolved person with current company and role evidence that satisfies the person predicate. |
| Enriched contact | A qualified person whose requested email, phone, or profile fields were added later. |

## Preflight

1. Confirm the output entity is a person and the target company universe is
   explicit and qualified.
2. Write role, function, seniority, geography, exclusions, required evidence,
   requested fields, maximum contacts per company, and total row bound.
3. Decide what proves current company membership and what makes an identity
   ambiguous.
4. Check the selected source's readiness and run a representative sample before
   scaling.

## Risk And Side Effects

| Stage | Risk | Rule |
| --- | --- | --- |
| Inspect source readiness or sample people | Read or bounded provider work | Preserve candidate and company source identity. |
| Start a large people acquisition | Provider work, credits, and artifact writes | Bound accounts, people per account, total rows, concurrency, and deadline. |
| Add a fallback source | Duplicate identities and inconsistent current-role evidence | Use it only for a measured coverage gap and reconcile identities before merging. |
| Enrich discovered people | Additional provider work and potentially sensitive contact data | Leave for `contact-enrichment.md` and preserve verification state. |
| Stage, message, or send | Customer-visible mutation | Leave for outbound, LinkedIn, inbox, and safety owners. |

## Canonical Operating Pattern

Keep company qualification and person qualification explicit. Consolidate the
proven search, identity resolution, deduplication, and output path after the
source shape is understood.

1. Freeze the target company set and person membership predicate.
2. Select one acquisition path and validate a small cross-company sample.
3. Acquire candidates with explicit company and row bounds.
4. Resolve identity, verify current company and role, apply exclusions, and
   preserve unresolved candidates separately.
5. Add one fallback only for a measured gap, then deduplicate by stable person
   and company identity.
6. Materialize the qualified contact artifact before enrichment or activation.

## Data Contracts

Every qualified contact should retain, when available:

- stable person identity such as canonical profile URL or provider person ID;
- stable company identity and the evidence joining the person to that company;
- current title, function, seniority, and the fields used by the membership rule;
- qualification decision and reason;
- source URL or provider receipt and observation time;
- ambiguity, stale-role, and missing-evidence status without invented facts.

Do not require email or phone merely to represent a qualified person. Those are
enrichment fields with their own verification states.

## Verification

Verify person identity, company membership, current role, qualification reason,
evidence URL or receipt, and coverage of the requested output fields.

Inspect multiple target companies, accepted and rejected people, duplicate
resolution, and the exact final artifact bytes before reporting completion.

## Troubleshooting

| Symptom | Likely Cause | Next Step |
| --- | --- | --- |
| People come from the wrong companies | The company universe or join identity was not fixed first. | Re-resolve company identities and rerun only affected accounts. |
| Titles match but people are irrelevant | Title text was treated as the whole person predicate. | Reapply function, seniority, exclusions, and current-role evidence. |
| Many duplicate people | Sources use different person identifiers. | Resolve canonical profile/person identity before merging rows. |
| Coverage is uneven across accounts | The selected source has an account-specific coverage gap. | Measure missing accounts, then add one bounded fallback for those accounts only. |
| Contact fields are missing | Discovery and enrichment were conflated. | Preserve the qualified people and hand requested fields to `contact-enrichment.md`. |

## Related References

| Next Decision | Read |
| --- | --- |
| Discover or qualify companies first | `company-search.md` |
| Select provider-neutral people acquisition | `audience_discovery.md` |
| Add verified contact fields to known people | `contact-enrichment.md` |
| Inspect current LinkedIn relationship or activity | `linkedin.md` |
| Transform and publish acquired rows | `row_operations.md` and `artifacts.md` |
| Stage or activate the audience | `outbound-campaigns.md` and `safety.md` |
