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

# Start Contact Search

`POST /api/contact-search/start`

## Request

- Base URL: `https://platform.verbiflow.com/api/bridge`
- URL: `https://platform.verbiflow.com/api/bridge/api/contact-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

- union
  - object
    - `filters` object, required: Source-specific people predicate. The source discriminator selects the exact named filter fields and their value types.
      - `current_company_identifiers_any` string[]
      - `current_titles_any` string[]
      - `current_titles_exclude` string[]
      - `hiring_signal` object, nullable
        - `include_hiring_manager` boolean
        - `job_locations_any` string[]
        - `job_search_result` object
          - `artifact_id` string, required
          - `execution_contract_digest` string, required
          - `generation_id` string, required
          - `job_id` string, required
          - `result_kind` 'job_postings' | 'job_search', required
          - `result_manifest_digest` string, required
          - `semantic_fingerprint` string, required
        - `job_titles_any` string[]
        - `max_job_pages` integer
        - `posted_within_days` integer
      - `locations_any` string[]
      - `locations_exclude` string[]
      - `past_company_identifiers_any` string[]
      - `past_titles_any` string[]
      - `profile_keywords_any` string[]
      - `seniority_floor` 'board-member' | 'c-suite' | 'director' | 'entry' | 'founder' | 'head' | 'intern' | 'manager' | 'mid-level' | 'owner' | 'partner' | 'senior' | 'unknown' | 'vp' | 'null', nullable
      - `seniority_levels_any` string[]
    - `source` 'auto'
    - `companies` object, nullable: Frozen successful Company Search generation bounding the current-employer universe.
      - `artifact_id` string, required
      - `execution_contract_digest` string, required
      - `generation_id` string, required
      - `job_id` string, required
      - `result_kind` 'company_search', required
      - `result_manifest_digest` string, required
      - `semantic_fingerprint` string, required
    - `contract_version` 'contact-search.v1', required
    - `max_per_company` integer, nullable
    - `max_results` integer
    - `validation` 'strict'
  - object
    - `filters` object, required: Source-specific people predicate. The source discriminator selects the exact named filter fields and their value types.
      - `about_keywords` string[]
      - `certification_keywords` string[]
      - `company_annual_revenues` string[]
      - `company_description_keywords` string[]
      - `company_description_keywords_exclude` string[]
      - `company_identifier` string[]
      - `company_industries_exclude` string[]
      - `company_industries_include` string[]
      - `company_sizes` string[]
      - `connection_count` integer
      - `current_role_max_months_since_start_date` integer
      - `current_role_min_months_since_start_date` integer
      - `experience_count` integer
      - `follower_count` integer
      - `headline_keywords` string[]
      - `include_past_experiences` boolean
      - `job_description_keywords` string[]
      - `job_title_exclude_keywords` string[]
      - `job_title_keywords` string[]
      - `job_title_seniority_floor_level` 'board-member' | 'c-suite' | 'director' | 'entry' | 'founder' | 'head' | 'intern' | 'manager' | 'mid-level' | 'owner' | 'partner' | 'senior' | 'unknown' | 'vp'
      - `job_title_seniority_levels_v2` string[]
      - `job_title_seniority_match_mode` 'exact' | 'floor'
      - `languages` string[]
      - `location_cities_exclude` string[]
      - `location_cities_include` string[]
      - `location_countries_exclude` string[]
      - `location_countries_include` string[]
      - `location_regions_exclude` string[]
      - `location_regions_include` string[]
      - `location_states_exclude` string[]
      - `location_states_include` string[]
      - `locations` string[]
      - `locations_exclude` string[]
      - `max_connection_count` integer
      - `max_experience_count` integer
      - `max_follower_count` integer
      - `names` string[]
      - `profile_keywords` string[]
      - `role_range_end_month` string
      - `role_range_start_month` string
      - `school_names` string[]
    - `source` 'clay', required
    - `companies` object, nullable: Frozen successful Company Search generation bounding the current-employer universe.
      - `artifact_id` string, required
      - `execution_contract_digest` string, required
      - `generation_id` string, required
      - `job_id` string, required
      - `result_kind` 'company_search', required
      - `result_manifest_digest` string, required
      - `semantic_fingerprint` string, required
    - `contract_version` 'contact-search.v1', required
    - `max_per_company` integer, nullable
    - `max_results` integer
    - `validation` 'strict'
  - object
    - `filters` object, required: Source-specific people predicate. The source discriminator selects the exact named filter fields and their value types.
      - `max_pages` integer
      - `sender_account_id` string
      - `url` string, uri, required
    - `source` 'linkedin', required
    - `companies` object, nullable: Frozen successful Company Search generation bounding the current-employer universe.
      - `artifact_id` string, required
      - `execution_contract_digest` string, required
      - `generation_id` string, required
      - `job_id` string, required
      - `result_kind` 'company_search', required
      - `result_manifest_digest` string, required
      - `semantic_fingerprint` string, required
    - `contract_version` 'contact-search.v1', required
    - `max_per_company` integer, nullable
    - `max_results` integer
    - `validation` 'strict'

## Response `202`

Successful Response

- ContactSearchStartResponse
  - `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: Immutable artifact identity containing committed result rows.
  - `execution_contract_digest` string, required: SHA-256 digest of the execution contract.
  - `execution_id` string, required: Capability-accounting execution identity for this admission.
  - `failed` boolean
  - `finished` boolean
  - `generation_id` string, required: Immutable output-generation identity.
  - `job_id` string, required: Stable durable job handle used for waiting, recovery, and diagnostics.
  - `operation_key` string, required: Stable logical operation identity.
  - `phase` string
  - `progress_current` integer
  - `progress_total` integer, required: Admitted progress target; inspect terminal summary for actual result count.
  - `request_digest` string, required: SHA-256 digest of the canonical request.
  - `result_kind` 'contact_search'
  - `rows` ContactSearchRow[]: Bounded committed-row preview; never the complete artifact.
    - `company_domain` string, nullable, required: Normalized current employer domain.
    - `company_linkedin_url` string, nullable, required: Canonical current employer LinkedIn company URL.
    - `company_name` string, nullable, required: Observed current employer name.
    - `first_name` string, nullable, required: Observed given name.
    - `full_name` string, nullable, required: Observed full person name.
    - `headline` string, nullable, required: Observed public profile headline.
    - `last_name` string, nullable, required: Observed family name.
    - `linkedin_url` string, required: Canonical public LinkedIn person URL.
    - `location` string, nullable, required: Observed current person location.
    - `membership_confidence` 'high' | 'medium' | 'low' | 'unknown', required: Confidence in the membership decision, not data-provider confidence.
    - `membership_decision` 'include', required: Final requested-predicate state for a primary result row.
    - `membership_reason` string, required: Concise evidence-grounded explanation of the decision.
    - `profile_picture_url` string, nullable, required: Observed public profile image URL.
    - `row_identifier` string, required: Stable person identity, preferring canonical LinkedIn identity.
    - `source` 'targeted_people' | 'clay_people' | 'linkedin_people' | 'hiring_signal_people', required: Concrete backend adapter that retrieved this candidate.
    - `source_evidence` ContactSearchSourceEvidence, required: Lossless provider provenance and normalized evidence for one candidate.
      - `adapter` 'targeted_people' | 'clay_people' | 'linkedin_people' | 'hiring_signal_people', required: Concrete acquisition adapter that supplied the candidate.
      - `is_hiring_manager` boolean, required: Whether posting evidence identified this person as the manager.
      - `job_posting_title` string, nullable, required: Job-posting title that selected the company, when applicable.
      - `job_posting_url` string, nullable, required: Job-posting URL that selected the company, when applicable.
      - `observed` ContactSearchObservedEvidence, required: Normalized evidence fields that were non-null in the provider record.
        - `company_domain` string: Normalized observed current-employer domain.
        - `company_linkedin_url` string: Canonical observed current-employer LinkedIn URL.
        - `company_name` string: Observed current employer name.
        - `headline` string: Observed public profile headline.
        - `location` string: Observed current person location.
        - `title` string: Observed current role title.
      - `provider_row` object, required: Complete unmodified provider record, retained as evidence. Keys depend on the provider and are not normalized Contact Search fields.
      - `provider_row_identifier` string, nullable, required: Provider-native stable row identity when available.
    - `title` string, nullable, required: Observed current role title.
  - `semantic_fingerprint` string, required: SHA-256 digest of semantic inputs and immutable dependencies.
  - `source_digest` string, nullable
  - `status` 'queued' | 'running' | 'blocked' | 'completed' | 'failed'
  - `summary` ContactSearchJobSummary, required: Known Job.summary fields plus safe admission/provider-progress extensions.
    - `accepted_count` integer: Candidates accepted into the primary artifact.
    - `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 normalized people rows.
    - `candidate_count` integer: Candidates evaluated before membership gating.
    - `capability_id` 'people.targeted_search' | 'people.find_at_companies' | 'job_posting.contacts': Canonical billed capability selected from the typed request semantics.
    - `committed_batch_count` integer: Immutable result batches committed.
    - `company_cap_excluded_count` integer: Candidates excluded by max_per_company.
    - `completeness` 'complete' | 'capped' | 'partial' | 'unknown': Derived terminal coverage state.
    - `deduplicated_count` integer: Repeated person identities removed.
    - `excluded_count` integer: Candidates explicitly excluded by evidence.
    - `execution_contract_digest` string: Digest of reviewed execution semantics.
    - `generation_id` string: Immutable semantic output-generation identity.
    - `operation_key` string: Stable logical operation identity.
    - `pages_fetched` integer, nullable: Provider pages fetched when the adapter exposes pagination.
    - `request_digest` string: Digest of the canonical request admitted by the backend.
    - `requested_units` integer: Maximum accepted people admitted for this generation.
    - `result_kind` 'contact_search': Typed terminal-result discriminator.
    - `result_manifest_digest` string: Digest of the exact terminal result manifest.
    - `semantic_fingerprint` string: Digest of semantic inputs and immutable dependencies.
    - `source_digest` string: Managed runner source-snapshot digest when available.
    - `termination` 'max_results_reached' | 'provider_exhausted' | 'page_cap_reached': Why candidate acquisition stopped.
    - `tool_kind` 'contact_search': Artifact-job implementation kind.
    - `unknown_count` integer: Candidates held because evidence was insufficient.

## 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)