--- title: "Start Company Search Batch" method: POST path: "/api/company-search/start-batch" tags: ["company-search"] --- # Start Company Search Batch `POST /api/company-search/start-batch` ## Request - Base URL: `https://platform.verbiflow.com/api/bridge` - URL: `https://platform.verbiflow.com/api/bridge/api/company-search/start-batch` - 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 - CompanySearchBatchStartRequest - `items` CompanySearchBatchItemRequest[], required - `operation` string, required - `request` CompanySearchStartRequest, required - `contract_version` 'company-search.v2', required - `filters` object, required - `max_results` integer - `source` 'auto' | 'clay' | 'crunchbase' ## Response `202` Successful Response - CompanySearchBatchStartResponse - `batch_id` string, required - `results` CompanySearchStartResponse[], required - `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)