# Company Enrichment

<!-- 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-30 |
| [Use This When](#use-this-when) | Tasks and conditions that belong in this guide. | 31-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-66 |
| [Primary SDK Paths](#primary-sdk-paths) | Operating guidance and contracts for this section. | 67-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-107 |
| [Preflight](#preflight) | State, authority, inputs, and readiness to verify before execution. | 108-117 |
| [Risk And Side Effects](#risk-and-side-effects) | Effects, approvals, cost, privacy, and retry boundaries. | 118-127 |
| [Canonical Operating Pattern](#canonical-operating-pattern) | The normal end-to-end execution sequence. | 128-138 |
| [Data Contracts](#data-contracts) | Required identities, fields, evidence, handles, and durable shapes. | 139-152 |
| [Verification](#verification) | Evidence required before reporting success. | 153-160 |
| [Troubleshooting](#troubleshooting) | Failure diagnosis and corrective routes. | 161-170 |
| [Related References](#related-references) | Adjacent boundaries and when to cross them. | 171-180 |
<!-- END GENERATED: guide-map -->

## Purpose

Resolve trustworthy facts and identifiers for companies that are already known.

## Use This When

Use this guide for firmographics, domains, company profiles, funding facts, CRM
identity, or structured company research. Use `company-search.md` to discover
new companies.

## Do Not Use This For

| Need | Owning Guide |
| --- | --- |
| Discover companies that are not already in the input set | `company-search.md` |
| Find people at known companies | `contact-search.md` |
| Treat a fuzzy name match as a resolved company | Preserve it as unresolved until identity evidence exists |
| Transform or publish already-enriched rows | `row_operations.md` and `artifacts.md` |
| Stage enriched rows into outbound | `outbound-campaigns.md` and `safety.md` |

## Choose A Path

1. Preserve the input company identity and requested fields.
2. Choose the narrowest first path below. Do not run a broad company-research
   job when a typed resolver owns the requested field.
3. Run one or a small sample before scaling provider-backed work, then preserve
   per-field evidence and unresolved values.
4. Never merge two companies on name alone.

| Requested fact | First path | Boundary |
| --- | --- | --- |
| Company profile fields for known rows | `enrichment.md` company profile resolver | Pass stable domain, LinkedIn URL, CRM id, or other identity hints. |
| Domain from company identity, or company LinkedIn URL from domain | The narrow domain or LinkedIn resolver in `enrichment.md` | Do not substitute fuzzy web search for a canonical resolver. |
| Broader product, positioning, or company research for one known domain | `enrichment.md` company research | Use artifact-backed execution for large or durable outputs. |
| Supplementary funding details for one known company | `enrichment.md` known-company funding lookup | Use `funding.md` only to discover companies by a funding window. |
| Crunchbase-native facts or filters such as category, investor, round, or employee data | `crunchbase.md` with entity resolution and exact company identity | Requires managed Crunchbase Pro pool readiness. |
| Deterministic containment or region classification over existing fields | `geo.md` | This transforms known evidence; it does not discover company facts. |
| Explicit public page or a fact no typed resolver owns | `web-research.md` | Preserve the source URL and observation time; label inference. |
| CRM-owned lifecycle, ownership, association, suppression, or deal facts | `crm.md` | CRM is authoritative only for facts stored in that workspace. |

## Primary SDK Paths

<!-- BEGIN GENERATED: primary-sdk-paths -->
| Primary function | Choose it when | Required inputs | Returns | Exact contract |
| --- | --- | --- | --- | --- |
| `vf.enrichment.companies` | Use for general firmographic or company-profile fields on supplied company rows or domains. | `rows` | `resolver_rows` | [`enrichment.md`](enrichment.md) · installed SDK: `verbiflow/enrichment.py:411-435` |
| `vf.enrichment.company_domains` | Use when company names or website hints must resolve to canonical domains before downstream work. | `companies` | `company_domain_job` | [`enrichment.md`](enrichment.md) · installed SDK: `verbiflow/enrichment.py:524-553` |
| `vf.enrichment.company_linkedin_urls` | Use when known companies need canonical LinkedIn company URLs. | `domains` | `resolver_rows` | [`enrichment.md`](enrichment.md) · installed SDK: `verbiflow/enrichment.py:497-522` |
| `vf.enrichment.company_research_start` | Use for durable, evidence-backed company research that must produce an inspectable artifact or feed a Workflow Play. | `domain` | `pending_artifact_job` | [`enrichment.md`](enrichment.md) · installed SDK: `verbiflow/enrichment.py:587-617` |
| `vf.enrichment.get_funding_data` | Use when known companies need structured funding facts rather than discovery by funding membership. | `company_name` | `funding_data` | [`enrichment.md`](enrichment.md) · installed SDK: `verbiflow/enrichment.py:912-960` |
<!-- END GENERATED: primary-sdk-paths -->

## Supporting References

Open only the child that resolves the next material decision.

| Reference | Use it for | Kind |
| --- | --- | --- |
| [`enrichment.md`](enrichment.md) | Canonical company and person enrichment contracts, identity boundaries, and evidence confidence. | capability |
| [`funding.md`](funding.md) | Recent structured funding discovery and qualification. | capability |
| [`geo.md`](geo.md) | Geographic containment and classification over known rows. | capability |
| [`web.md`](web.md) | Public web search, page extraction, screenshots, Markdown, and browser evidence. | capability |
| [`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 |

## Mental Model

Enrichment attaches field-level facts to an existing company identity. It does
not redefine the input universe. Every requested field may have a different
source, observation time, confidence, and unresolved state.

| Object | Meaning |
| --- | --- |
| Input identity | The company row and stable hints supplied before enrichment. |
| Resolved identity | The canonical company identity supported by enough evidence to avoid a false merge. |
| Field observation | One requested value with its source, time, and confidence. |
| Coverage | The fraction of input companies for which each requested field was resolved. |

Absence is not a negative fact. Preserve not found, not requested, provider
failure, ambiguous identity, and genuinely empty values as different states.

## Preflight

1. Freeze the input company set and stable identity hints.
2. List only the fields the deliverable needs and assign each to the narrowest
   owning path in the choice hierarchy.
3. Define identity resolution, merge, freshness, confidence, and unresolved-value
   rules before provider work.
4. Run one row or a small diverse sample before scaling. Check field shapes,
   evidence, cost, latency, and failure behavior.

## Risk And Side Effects

| Stage | Risk | Rule |
| --- | --- | --- |
| Typed resolution or bounded sample | Read or bounded provider work | Preserve original identity hints and per-field receipts. |
| Large artifact-backed enrichment | Provider work, credits, and artifact writes | Bound rows, fields, concurrency, deadline, and retry behavior. |
| Merge provider results | False company merge or field overwrite | Resolve stable identity first and preserve source conflicts. |
| Use CRM facts | Workspace-specific authority | Treat CRM as authoritative only for fields stored in that workspace. |
| Stage, publish, or send | Customer-visible mutation | Leave for the outbound and safety owners. |

## Canonical Operating Pattern

1. Preserve the input row and requested-field contract.
2. Resolve company identity using the strongest available stable hints.
3. Choose the narrowest owner for each field and test a representative sample.
4. Run bounded enrichment, retaining per-field value, source, observation time,
   confidence, and status.
5. Merge only on resolved identity, preserve conflicts, and never replace a
   stronger verified value with weaker evidence silently.
6. Calculate field-level coverage and materialize the exact enriched artifact.

## Data Contracts

Every output row should preserve:

- the original company identity and source row key;
- resolved canonical domain, profile URL, provider ID, or CRM ID when available;
- each requested value with field-level source, observation time, confidence,
  and resolution status;
- identity ambiguity, conflicts, provider failures, and unresolved fields;
- no invented placeholder that could be mistaken for a verified fact.

Coverage should be reported per requested field, not only as a count of rows
that received at least one value.

## Verification

Verify entity resolution, per-field provenance, observation time, confidence,
and requested-field coverage. Preserve unresolved values as unresolved.

Inspect successful, unresolved, ambiguous, and conflicting rows and verify the
exact final artifact bytes.

## Troubleshooting

| Symptom | Likely Cause | Next Step |
| --- | --- | --- |
| Facts belong to the wrong company | Name-only matching or an unstable join key was used. | Re-resolve identity from domain, canonical URL, CRM ID, or provider ID. |
| Many fields are blank with no explanation | Missing values and provider failures were collapsed. | Restore field-level status and retry only the failure class that is safe to retry. |
| One provider overwrote stronger evidence | Merge precedence was implicit. | Compare source authority, observation time, and confidence; retain the conflict. |
| Cost or latency grows unexpectedly | A broad research path was used for narrow typed fields. | Return to the choice hierarchy and use the narrowest field owner. |
| Row count changed after enrichment | The enrichment step altered the input universe. | Rejoin to the frozen input key and report unmatched provider rows separately. |

## Related References

| Next Decision | Read |
| --- | --- |
| Discover new companies | `company-search.md` |
| Use canonical domain, profile, funding, or research resolvers | `enrichment.md` |
| Use paid Crunchbase-native facts | `crunchbase.md` |
| Use CRM-owned facts and associations | `crm.md` |
| Research an explicit public page | `web-research.md` |
| Transform and publish enriched rows | `row_operations.md` and `artifacts.md` |
