# Funding

<!-- 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. | 26-35 |
| [Use This When](#use-this-when) | Tasks and conditions that belong in this guide. | 36-42 |
| [Do Not Use This For](#do-not-use-this-for) | Boundaries and the correct routes for excluded work. | 43-52 |
| [Mental Model](#mental-model) | Concepts and state boundaries needed for correct operation. | 53-63 |
| [Preflight](#preflight) | State, authority, inputs, and readiness to verify before execution. | 64-74 |
| [Risk And Side Effects](#risk-and-side-effects) | Effects, approvals, cost, privacy, and retry boundaries. | 75-83 |
| [Canonical Operating Pattern](#canonical-operating-pattern) | The normal end-to-end execution sequence. | 84-99 |
| [Core SDK Surfaces](#core-sdk-surfaces) | Exact source-backed callable contracts owned by this guide. | 100-108 |
| [Data Contracts](#data-contracts) | Required identities, fields, evidence, handles, and durable shapes. | 109-122 |
| [Examples](#examples) | Representative usage patterns and code. | 123-150 |
| [Verification](#verification) | Evidence required before reporting success. | 151-158 |
| [Troubleshooting](#troubleshooting) | Failure diagnosis and corrective routes. | 159-168 |
| [Related References](#related-references) | Adjacent boundaries and when to cross them. | 169-177 |
<!-- END GENERATED: guide-map -->

## Purpose

Use this reference to discover companies with recent structured funding data
through Flage's managed Crunchbase Pro pool. `vf.funding.*` provides a narrow
funding workflow over Crunchbase. It does not choose or fall
back to another provider.

The result separates complete structured matches from incomplete Crunchbase
rows. Keep that distinction when enriching, qualifying, or staging an audience.

## Use This When

- The task asks for companies that raised within a date window.
- Funding date, round type, or company geography is part of qualification.
- A funding-led audience will feed enrichment, qualification, or outreach.
- The managed Crunchbase Pro pool is ready.

## Do Not Use This For

| Need | Use Instead | Why |
| --- | --- | --- |
| Crunchbase-specific category, investor, or employee filters | `crunchbase.md` | Crunchbase owns provider-specific filters and entity resolution. |
| Single-company factual research | `enrichment.md` | Enrichment owns canonical company research. |
| Generic news or public-page research | `web.md` | Web owns public research outside structured funding discovery. |
| Row joins and qualification | `row_operations.md` | Funding discovery returns evidence. Row operations owns deterministic shaping. |
| Sequence staging or activation | `sequences.md`, `safety.md` | Discovery does not authorize outreach. |

## Mental Model

Funding discovery has one provider requirement: the Flage-managed Crunchbase
Pro pool must be ready. If it is not, the SDK returns
`funding_provider_unavailable`. Users never connect or inspect a pool account,
and there is no automatic fallback.

Crunchbase returns structured company rows. A row is `qualified` when it has a
resolved company identity and every requested funding criterion is present. An
incomplete row remains a `candidate` with explicit `unverified_criteria`.

## Preflight

1. Call `vf.funding.provider()` to confirm managed-pool readiness.
2. Define the inclusive funding date window.
3. Define requested company locations and round types. When any location name
   resolves ambiguously, call `vf.crunchbase.resolve_entities(...,
   collection="locations")`, require zero ambiguous/unmatched names, and pass
   the returned UUIDs as `location_uuids=`. Do not guess a replacement label.
4. Decide which missing facts must be verified before a candidate can qualify.
5. Keep each cursor with the exact query that produced it.

## Risk And Side Effects

| Operation | Risk | Rule |
| --- | --- | --- |
| `vf.funding.provider()` | Read-only managed-pool readiness check | Stop if managed Crunchbase access is unavailable. |
| `vf.funding.discover_companies(...)` | Crunchbase provider read | Inspect `qualification`, `unverified_criteria`, and evidence before downstream use. |
| Candidate verification | Additional provider or web reads | Verify only the missing criteria. Preserve source URLs. |
| Outreach staging | Separate platform mutation | Do not stage candidates until the required criteria are verified. |

## Canonical Operating Pattern

1. Read `vf.funding.provider()`.
2. Call `vf.funding.discover_companies(...)` with an exact date window and
   either human `locations=` or resolved `location_uuids=`, never both.
3. Preserve source and evidence on every page.
4. Use `qualified` items as structured funding matches.
5. Keep incomplete Crunchbase rows as candidates.
6. Verify each field named in `unverified_criteria` before promotion.
7. Follow `next_cursor` only with the same query. A complete-universe loop must
   retain a set of seen cursors plus explicit page/time bounds; a repeated
   cursor or a bound reached while `next_cursor` remains is a failed partial
   run, never success.
8. Restart from the first page after changing dates, locations, round types, or
   managed-pool readiness.

## Core SDK Surfaces

<!-- BEGIN GENERATED: core-sdk-surfaces -->
| Function | Use When | Inputs | Output And Handles To Preserve | Side Effect | Source |
| --- | --- | --- | --- | --- | --- |
| `vf.funding.discover_companies` | Discover structured recent funding records through the workspace's active Flage-managed Crunchbase Pro pool. Incomplete provider rows remain candidates. | <strong>Required</strong>: `funding_after` (date \| str; required): Inclusive funding start date in YYYY-MM-DD form.<br><strong>Optional</strong>: `cursor` (str \| None; optional; default `None`): Opaque cursor from the previous identical funding query.; `funding_before` (date \| str \| None; optional; default `None`): Inclusive funding end date in YYYY-MM-DD form.; `limit` (int; optional; default `25`): Maximum Crunchbase records in this page.; `location_uuids` (Sequence[str]; optional): Exact Crunchbase location UUIDs returned by crunchbase.resolve_entities. Mutually exclusive with locations.; `locations` (Sequence[str]; optional): Crunchbase company-location filters.; `round_types` (Sequence[str]; optional): Crunchbase funding-type filters. | `funding_discovery_page` payload returned by the SDK operation. Inspect the documented function reference and `raw`/dictionary fields when debugging provider-specific data.<br><strong>Common next calls</strong>: `vf.enrichment.get_company_research` | provider_call | installed SDK: `verbiflow/funding.py:87-188` |
| `vf.funding.provider` | Confirm that Flage's managed Crunchbase Pro pool is ready for structured funding discovery. | No inputs. | `funding_source_selection` payload returned by the SDK operation. Inspect the documented function reference and `raw`/dictionary fields when debugging provider-specific data.<br><strong>Common next calls</strong>: `vf.funding.discover_companies` | read | installed SDK: `verbiflow/funding.py:65-85` |
<!-- END GENERATED: core-sdk-surfaces -->

## Data Contracts

| Field | Meaning |
| --- | --- |
| `source.provider` | Always `crunchbase`. |
| `source.reason` | `flage_managed_pool` after successful preflight. |
| `qualification` | `qualified` when requested structured criteria are present, otherwise `candidate`. |
| `resolution` | Whether the company identity resolved from the Crunchbase row. |
| `company` | Structured company identity, domain, provider id, and headquarters. |
| `funding` | Announced date, round type, amount, currency, and total raised when available. |
| `unverified_criteria` | Missing facts that block qualification. |
| `evidence` | Crunchbase record provenance. Preserve it. |
| `next_cursor` | Opaque cursor bound to Crunchbase and the exact query. |

## Examples

```python
from datetime import date, timedelta

import verbiflow as vf

today = date.today()
vf.funding.provider()  # successful return is readiness; there is no `ready` field
resolved = vf.crunchbase.resolve_entities(
    ["San Francisco Bay Area", "New York City"],
    collection="locations",
)
if resolved["ambiguous"] or resolved["unmatched"]:
    raise RuntimeError(f"Unresolved funding locations: {resolved}")
page = vf.funding.discover_companies(
    funding_after=today - timedelta(days=180),
    funding_before=today,
    location_uuids=[item["uuid"] for item in resolved["matched"]],
    round_types=["seed"],
    limit=50,
)

qualified = [item for item in page["items"] if item["qualification"] == "qualified"]
candidates = [item for item in page["items"] if item["qualification"] == "candidate"]
print(page["source"], len(qualified), len(candidates))
```

## Verification

- Confirm `source.provider` is `crunchbase`.
- Confirm qualified items have a resolved company and no unverified criteria.
- Confirm incomplete rows remain candidates with explicit missing criteria.
- Preserve the evidence URL and retrieval timestamp in the final artifact.
- Report qualified and candidate counts separately.

## Troubleshooting

| Symptom | Cause | Fix |
| --- | --- | --- |
| `funding_provider_unavailable` | The managed Crunchbase Pro pool is unavailable | Retry when service readiness returns; do not ask for Crunchbase credentials. |
| `funding_cursor_mismatch` | Cursor came from another query | Restart from the first page with the current query. |
| Location resolution failed | A requested location was ambiguous or unmatched | Resolve it through `vf.crunchbase.resolve_entities([...], collection="locations")`, require no ambiguous/unmatched entries, then pass the matched UUIDs as `location_uuids=`. |
| Candidate rows remain after search | Crunchbase omitted one or more requested fields | Inspect `unverified_criteria` and verify only those facts. |
| Crunchbase capacity is exhausted | All managed provider sessions are busy | Retry the same page after capacity becomes available. |

## Related References

- `audience_discovery.md`
- `crunchbase.md`
- `enrichment.md`
- `row_operations.md`
- `web.md`
- `sequences.md`
- `safety.md`
