# Company 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-32 |
| [Use This When](#use-this-when) | Tasks and conditions that belong in this guide. | 33-38 |
| [Do Not Use This For](#do-not-use-this-for) | Boundaries and the correct routes for excluded work. | 39-48 |
| [Choose A Path](#choose-a-path) | Decision hierarchy for selecting the right capability or provider. | 49-73 |
| [Primary SDK Paths](#primary-sdk-paths) | Operating guidance and contracts for this section. | 74-86 |
| [Supporting References](#supporting-references) | Capability, provider, policy, and runtime guides for this outcome. | 87-103 |
| [Mental Model](#mental-model) | Concepts and state boundaries needed for correct operation. | 104-119 |
| [Preflight](#preflight) | State, authority, inputs, and readiness to verify before execution. | 120-131 |
| [Risk And Side Effects](#risk-and-side-effects) | Effects, approvals, cost, privacy, and retry boundaries. | 132-141 |
| [Canonical Operating Pattern](#canonical-operating-pattern) | The normal end-to-end execution sequence. | 142-157 |
| [Data Contracts](#data-contracts) | Required identities, fields, evidence, handles, and durable shapes. | 158-172 |
| [Verification](#verification) | Evidence required before reporting success. | 173-180 |
| [Troubleshooting](#troubleshooting) | Failure diagnosis and corrective routes. | 181-190 |
| [Related References](#related-references) | Adjacent boundaries and when to cross them. | 191-200 |
<!-- END GENERATED: guide-map -->

## Purpose

Find and qualify companies from the user's market, ICP, geography, funding, or
local-business criteria. This guide chooses an acquisition path before it
chooses a provider.

## Use This When

Use this guide when the requested rows are companies or accounts that are not
already known. If the companies are already known and need more facts, use
`company-enrichment.md`.

## Do Not Use This For

| Need | Owning Guide |
| --- | --- |
| Add facts to a known company list | `company-enrichment.md` |
| Find people at known or newly discovered companies | `contact-search.md` |
| Find companies because they have current openings | `job-search.md` |
| Transform, join, score, or export rows already acquired | `row_operations.md`, then `artifacts.md` |
| Stage or activate an outbound audience | `outbound-campaigns.md` and `safety.md` |

## Choose A Path

1. Write the company membership predicate and required evidence fields.
2. Choose the first matching path below. Do not query several providers merely
   because they are available.
3. Inspect the selected path's readiness and run a count or bounded sample
   before scaling. Fall back only after naming the missing filter, coverage, or
   evidence that requires another source.
4. Qualify every final row against the original predicate. A large result set is
   not a substitute for a correct one.

| Requested universe | First path | Use another path only when |
| --- | --- | --- |
| A known cohort, portfolio, directory, registry, or other canonical source | `audience_discovery.md` for a typed source, otherwise `web-research.md` for the official page | The source is incomplete, stale, or cannot expose the required identity fields. |
| Local businesses, venues, practices, stores, or review-led discovery | `places.md` | The request is actually for general companies rather than place listings. |
| Companies funded inside a date window, optionally filtered by round or location | `funding.md` | Managed Crunchbase readiness is unavailable and the user accepts public-web evidence with weaker structure. |
| Structured company filters such as categories, investors, funding stage, headcount, or geography | `crunchbase.md`; resolve provider entities and count first | The managed Crunchbase pool is unavailable or the requested filter exists only in another provider. |
| Clay-native company filters or a large durable Clay result set | `clay.md`; inspect the live company filter catalog first | Clay cannot express the membership predicate or sample quality is inadequate. |
| Fuzzy concepts, launches, news, public lists, or an explicit URL | `web-research.md` | A structured provider can express the predicate more directly and with stronger provenance. |

If the input companies are already known, stop. Facts about those rows belong
to `company-enrichment.md`; people at those companies belong to
`contact-search.md`. If hiring or open roles determine company membership, the
evidence owner is `job-search.md` even when the final rows are companies.

## Primary SDK Paths

<!-- BEGIN GENERATED: primary-sdk-paths -->
| Primary function | Choose it when | Required inputs | Returns | Exact contract |
| --- | --- | --- | --- | --- |
| `vf.funding.discover_companies` | Use recent funding rounds as the company-membership predicate and retain the round as evidence. | `funding_after` | `funding_discovery_page` | [`funding.md`](funding.md) · installed SDK: `verbiflow/funding.py:87-188` |
| `vf.crunchbase.search_companies` | Use Flage's managed Crunchbase Pro pool for exact provider UUID filters, count-first discovery, and bounded pagination. | `filters` | `crunchbase_company_search` | [`crunchbase.md`](crunchbase.md) · installed SDK: `verbiflow/crunchbase.py:84-113` |
| `vf.clay.search_companies` | Use Clay's structured company filters for a bounded company result set without requiring a workspace-owned provider connection. | `filters` | `clay_search_results` | [`clay.md`](clay.md) · installed SDK: `verbiflow/clay.py:161-198` |
| `vf.linkedin.search_companies` | Use LinkedIn-native company filters or identities when LinkedIn company records are the required source. | `query` | `linkedin_companies` | [`linkedin.md`](linkedin.md) · installed SDK: `verbiflow/linkedin.py:325-338` |
| `vf.sources.incubators.batch` | Use incubator or accelerator portfolios as the source universe, optionally deriving contacts from portfolio companies. | `incubator_name` | `pending_artifact_job` | [`audience_discovery.md`](audience_discovery.md) · installed SDK: `verbiflow/sources.py:291-421` |
| `vf.sources.places.search_start` | Use place and local-business criteria such as category, city, map area, or reviews at provider-backed scale. | `queries` | `pending_artifact_job` | [`places.md`](places.md) · installed SDK: `verbiflow/sources.py:751-822` |
<!-- 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 |
| [`funding.md`](funding.md) | Recent structured funding discovery and qualification. | capability |
| [`geo.md`](geo.md) | Geographic containment and classification over known rows. | capability |
| [`places.md`](places.md) | Local-business and place discovery, reviews, and place-specific limits. | capability |
| [`row_operations.md`](row_operations.md) | Deterministic row transforms, joins, and reviewable LLM qualification or annotation with rationale and confidence. | capability |
| [`web.md`](web.md) | Public web search, page extraction, screenshots, Markdown, and browser evidence. | capability |
| [`clay.md`](clay.md) | Clay Public API people and company search filters, bounded immediate results, durable artifacts, accounting, and workspace pacing. | provider |
| [`crunchbase.md`](crunchbase.md) | Crunchbase filters, entity resolution, count-first execution, pagination, and provider limits. | 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

Company search proves set membership. The result is not "companies returned by
a provider." It is companies that satisfy the user's predicate, with enough
identity and source evidence to review that decision. Provider membership is
candidate evidence, not automatic qualification.

Keep these objects separate:

| Object | Meaning |
| --- | --- |
| Candidate universe | Rows returned by the selected source before qualification. |
| Membership predicate | The inclusion, exclusion, time, geography, and evidence rules that define the requested market. |
| Qualified company | A deduplicated company whose evidence satisfies the predicate. |
| Final artifact | The exact qualified rows, schema, provenance, and unresolved limitations delivered to the user. |

## Preflight

1. Confirm the output entity is a company, not a contact, place, job, or known
   company needing enrichment.
2. Write the inclusion and exclusion rules, freshness window, required columns,
   evidence standard, maximum rows, and deduplication identity.
3. Check the first selected source's readiness, cost or provider boundary, and
   expected coverage before starting a large pull.
4. Decide how unresolved identity, missing evidence, and partial coverage will
   appear in the deliverable. Do not silently drop them or present them as
   qualified.

## Risk And Side Effects

| Stage | Risk | Rule |
| --- | --- | --- |
| Inspect source readiness, counts, or a bounded sample | Read or bounded provider work | Safe when needed. Preserve source identity and receipts. |
| Start a large or durable acquisition | Provider work, credits, and artifact writes | Bound rows, pages, concurrency, deadline, and no-progress behavior before launch. |
| Add a second source | More cost, latency, and conflicting evidence | Add it only for a named coverage or evidence gap. |
| Transform or publish the final list | Local or durable artifact write | Preserve the qualification columns and exact final bytes. |
| Stage, publish, or send to the list | Customer-visible platform mutation | Leave this guide for the outbound and safety owners. |

## Canonical Operating Pattern

Inspect a small sample to learn the source shape. Then run one bounded,
checkpointed acquisition and qualification program with concurrent independent
I/O, explicit pagination limits, and a no-progress guard.

1. Record the membership predicate and intended row contract.
2. Select one source through the choice hierarchy and inspect its readiness.
3. Run a count or representative sample. Validate identity, predicate coverage,
   schema, and evidence before scaling.
4. Acquire the bounded universe, normalize identities, apply exclusions, and
   qualify each row against the original predicate.
5. Add a fallback source only when the first result demonstrates a measured gap.
6. Deduplicate by stable company identity, preserve conflicts, and materialize
   the exact final artifact.

## Data Contracts

Every qualified row should retain, when available:

- a stable company identity such as domain, canonical provider ID, company URL,
  or CRM ID;
- the fields that prove every inclusion and exclusion rule;
- a qualification decision and concise reason;
- source identity or URL, observation time, and provider or artifact receipt;
- unresolved identity, missing evidence, and conflict status without fabricated
  values.

The final artifact should state requested scope, source window, row count,
deduplication key, qualification coverage, and known limitations.

## Verification

Verify company identity, every requested filter, source URL or provider receipt,
observation time, deduplication, and the exact final artifact bytes.

Sample accepted and rejected rows. Confirm that each accepted row satisfies the
membership predicate and that no source-only candidate is mislabeled as final.

## Troubleshooting

| Symptom | Likely Cause | Next Step |
| --- | --- | --- |
| Many rows, weak relevance | The provider query was treated as the qualification rule. | Reapply the written predicate and inspect accepted and rejected samples. |
| Very few or zero rows | The first source cannot express the predicate, readiness is missing, or filters are too narrow. | Inspect readiness and a minimal count; name the missing coverage before choosing one fallback. |
| Duplicate or conflicting companies | Names were used as identity or sources disagree. | Resolve stable domains/IDs, keep conflicts explicit, and never merge on name alone. |
| A source stopped advancing | Pagination or retry logic lacks a no-progress boundary. | Preserve the cursor and partial artifact; resume with a deadline instead of restarting blindly. |
| The final list cannot be audited | Qualification or provenance was discarded during transforms. | Rebuild from preserved source rows and keep qualification/evidence columns in the final artifact. |

## Related References

| Next Decision | Read |
| --- | --- |
| Select a provider-neutral acquisition source | `audience_discovery.md` |
| Find people at the qualified companies | `contact-search.md` |
| Enrich known company rows | `company-enrichment.md` |
| Use funding or hiring as the membership predicate | `funding.md` or `job-search.md` |
| Research fuzzy or explicit public-web evidence | `web-research.md` |
| Transform and publish acquired rows | `row_operations.md` and `artifacts.md` |
