---
title: "Start Company Search"
method: POST
path: "/api/company-search/start"
tags: ["company-search"]
---

# Start Company Search

`POST /api/company-search/start`

## Request

- Base URL: `https://platform.verbiflow.com/api/bridge`
- URL: `https://platform.verbiflow.com/api/bridge/api/company-search/start`
- Auth: one of:
  - HTTP bearer and API key in header `x-flage-org-id`
  - HTTP bearer and API key in header `x-flage-org-slug`

## Request body

- CompanySearchStartRequest
  - `contract_version` 'company-search.v2', required
  - `filters` object, required
  - `max_results` integer
  - `source` 'auto' | 'clay' | 'crunchbase'

## Response `202`

Successful Response

- CompanySearchStartResponse
  - `accepted_pricing` AcceptedJobPricing, required: Immutable rule used to rate this job; final usage determines the actual charge.
    - `basis` 'none' | 'successful_execution' | 'successful_provider_attempt' | 'requested_record' | 'delivered_record' | 'successful_record' | 'provider_unit' | 'provider_cost_usd' | 'resolver_reported', required
    - `billing_owner` 'none' | 'growth_capability' | 'source_execution' | 'enrichment_reservation', required
    - `credits_per_unit` string, required: Exact Decimal customer-credit rate per unit, encoded as a string. This is not the final charge.
    - `pricing_version` string, required: Immutable published rate-book revision captured when the job was admitted.
    - `unit` string, required: Unit counted by basis, such as a record or execution.
  - `artifact_id` string, required: Durable artifact identity when admitted.
  - `execution_contract_digest` string, required: Reviewed execution-contract digest.
  - `execution_id` string, required: Accounting execution identity.
  - `failed` boolean: Whether the terminal snapshot failed.
  - `finished` boolean: Whether this snapshot is terminal.
  - `generation_id` string, required: Immutable semantic output generation identity.
  - `job_id` string, required: Durable status and progress identity.
  - `operation_key` string, required: Stable logical call identity within the managed run.
  - `phase` string: Latest persisted execution phase.
  - `progress_current` integer: Rows committed or current work-unit progress.
  - `progress_total` integer, required: Known work-unit total when available.
  - `request_digest` string, required: Digest of the admitted request.
  - `rows` CompanySearchRow[]: Bounded committed preview; the artifact owns the complete rows.
    - `annual_revenue_range` string, nullable, required: Provider-observed annual-revenue bucket when no exact value exists.
    - `annual_revenue_usd` integer, nullable, required: Estimated annual revenue in USD.
    - `city` string, nullable, required: Headquarters city.
    - `company_domain` string, nullable, required: Normalized bare company domain when resolvable.
    - `company_linkedin_url` string, nullable, required: Canonical LinkedIn company URL when valid.
    - `company_name` string, nullable, required: Provider-observed company name.
    - `company_ref` string, required: Stable provider-neutral company identity digest.
    - `company_type` string, nullable, required: Provider-observed legal or profile company type.
    - `company_website` string, nullable, required: Provider-observed company website URL.
    - `country` string, nullable, required: Headquarters country.
    - `description` string, nullable, required: Best available provider-observed company description. The complete unmodified provider record remains in provider_fields.
    - `employee_count` integer, nullable, required: Estimated employee count.
    - `employee_range` string, nullable, required: Provider-observed employee-size range when no exact count exists.
    - `follower_count` integer, nullable, required: Provider-observed LinkedIn follower count.
    - `founded_year` integer, nullable, required: Company founding year.
    - `headquarters` string, nullable, required: Lossless provider-observed headquarters/location label.
    - `industries` string[], required: All normalized provider-observed industries.
    - `industry` string, nullable, required: Primary provider-observed industry.
    - `keywords` string[], required: Normalized provider-observed company keywords.
    - `latest_funding_amount_range` string, nullable, required: Latest funding amount bucket when no exact amount exists.
    - `latest_funding_amount_usd` integer, nullable, required: Latest disclosed funding-round amount in USD.
    - `latest_funding_date` string, nullable, required: Latest disclosed funding date as observed by the provider.
    - `latest_funding_stage` string, nullable, required: Latest disclosed funding stage.
    - `operating_status` string, nullable, required: Provider-observed operating status.
    - `provider` 'apollo' | 'clay' | 'crunchbase', required: Provider that emitted this source row.
    - `provider_company_id` string, nullable, required: Provider-native company identity when present.
    - `provider_fields` object, required: Lossless provider row. Normalized columns are conveniences; this object preserves every returned provider field without truncation.
    - `provider_search_id` string, nullable, required: Provider-native search identity when present.
    - `search_query_sha256` string, required: Digest of the canonical membership request that produced the row.
    - `source` 'company_search', required: Normalized row provenance label.
    - `source_rank` integer, required: One-based delivered-row rank after unusable provider rows are omitted.
    - `state` string, nullable, required: Headquarters state or first-level region.
    - `technologies` string[], required: Normalized currently-used technologies.
    - `total_funding_range` string, nullable, required: Total-funding bucket when no exact amount exists.
    - `total_funding_usd` integer, nullable, required: Total disclosed funding in USD.
  - `semantic_fingerprint` string, required: Semantic request fingerprint, populated by durable admission.
  - `status` 'queued' | 'running' | 'blocked' | 'completed' | 'failed': Latest persisted lifecycle status in this snapshot.
  - `summary` CompanySearchProgress, required: Lifecycle summary exposed on Job.summary. Provider coverage, termination, manifest, and completeness fields appear on terminal snapshots.
    - `accepted_pricing` AcceptedJobPricing: Immutable rule used to rate this job; final usage determines the actual charge.
      - `basis` 'none' | 'successful_execution' | 'successful_provider_attempt' | 'requested_record' | 'delivered_record' | 'successful_record' | 'provider_unit' | 'provider_cost_usd' | 'resolver_reported', required
      - `billing_owner` 'none' | 'growth_capability' | 'source_execution' | 'enrichment_reservation', required
      - `credits_per_unit` string, required: Exact Decimal customer-credit rate per unit, encoded as a string. This is not the final charge.
      - `pricing_version` string, required: Immutable published rate-book revision captured when the job was admitted.
      - `unit` string, required: Unit counted by basis, such as a record or execution.
    - `artifact_id` string: Durable artifact containing the normalized rows.
    - `capability_id` 'company.search': Canonical billed capability identity.
    - `columns` string[]: Ordered artifact column names.
    - `completeness` 'complete' | 'capped' | 'unknown': Derived terminal coverage state; typed success rejects unknown.
    - `contract_version` 'company-search.v2': Durable Company Search contract version.
    - `execution_contract_digest` string: Digest of the reviewed semantic execution contract.
    - `generation_id` string: Immutable semantic output generation identity.
    - `materialized_provider_page_count` integer: Provider page checkpoints referenced by this result generation.
    - `operation_key` string: Run-local stable logical operation identity.
    - `provider_pages_reused` integer: Provider pages adopted from committed checkpoints without repeating their read.
    - `replayed` boolean: Whether admission adopted an existing logical search.
    - `request_digest` string: Digest of the canonical request admitted by the backend.
    - `requested_units` integer: Maximum rows admitted for provider work.
    - `result_kind` 'company_search': Typed terminal result discriminator.
    - `result_manifest_digest` string: Digest of the exact terminal result manifest.
    - `row_count` integer: Number of rows committed to the artifact.
    - `semantic_fingerprint` string: Digest of the request, contract, and immutable dependencies.
    - `source_digest` string: Managed runner source-snapshot digest when available.
    - `source_page_count` integer: Provider pages fetched, including seed resolution when used.
    - `source_provider` 'apollo' | 'clay' | 'crunchbase': Provider selected by the typed filter set.
    - `source_total_entries` integer: Provider-reported matching population when available; otherwise the number of normalized rows observed before termination.
    - `termination` 'provider_exhausted' | 'max_results_reached' | 'provider_page_limit_reached' | 'provider_coverage_incomplete' | 'provider_coverage_inconsistent': Why provider paging stopped; inspect this before claiming coverage.
    - `tool_kind` 'company_search': Artifact-job implementation kind.
    - `workflow_status` 'queued' | 'running' | 'blocked' | 'completed' | 'failed': Latest public workflow status at admission.

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/verbiflow/apis/verbiflow-sdk-http-contract.md) - [All operations](https://skmtc.dev/verbiflow/apis/verbiflow-sdk-http-contract/llms.txt) - [OpenAPI document](https://skmtc.dev/verbiflow/apis/verbiflow-sdk-http-contract/revisions/c80e903ef8f3?raw)