---
title: "Start a contacts run"
method: POST
path: "/contacts/run"
tags: ["contacts-run"]
---

# Start a contacts run

`POST /contacts/run`

## Request

- Base URL: `https://api.discolike.com` (the document declares no server; this is the origin it was published from)
- URL: `https://api.discolike.com/contacts/run`
- Auth: one of:
  - API key in header `X-API-Key`
  - HTTP bearer

Finds and validates contacts automatically, using database candidates before web fallback. Poll for live companies and validated contacts. max_companies counts companies with a validated delivery. Repeating create_key returns the same run.

## Request body

- ContactsRunRequest
  - `companies` union, required
    - PromptCompanies
      - `source` 'prompt', required
      - `icp_text` string, nullable: Plain-language description of the companies you want.
      - `filters` PromptCompanyFilters
        - `filter_industry` string[], nullable: Filter by industry category (ANY-OF; prefix + to require a category). Valid values: ACCOUNTING, ADVERTISING_AND_MARKETING, AGRICULTURE_AND_NATURAL_RESOURCES, ALCOHOL_AND_TOBACCO, AUTOMOTIVE, BIG_DATA_AND_ANALYTICS, BIOTECHNOLOGY, BLOCKCHAIN_AND_CRYPTOCURRENCY, BUSINESS_PRODUCTS_AND_SERVICES, CLOUD_COMPUTING, COMPUTER_HARDWARE_AND_SEMICONDUCTORS, CONGLOMERATES_SHELL_AND_HOLDING_COMPANIES, CONSTRUCTION, CONSUMER_PRODUCTS, CONSUMER_SERVICES, CYBERSECURITY, DEFENSE_AND_AEROSPACE, E-COMMERCE, EDUCATION, ENERGY, ENGINEERING, ENTERTAINMENT, ENVIRONMENTAL_SERVICES, FASHION_TEXTILE_AND_APPAREL, FINANCIAL_SERVICES, FOOD_AND_BEVERAGE, GAMING_AND_ESPORTS, GOVERNMENT_SERVICES, HEALTHCARE, HOSPITALITY, HUMAN_RESOURCES, INSURANCE, IT_SERVICES, LEGAL, MANUFACTURING, MEDIA, MINING_AND_METALS, NONPROFIT_AND_PHILANTHROPY, OIL_AND_GAS, PHARMACEUTICALS, PRIVATE_EQUITY_AND_VENTURE_CAPITAL, REAL_ESTATE, RENEWABLE_ENERGY, RESTAURANTS, RETAIL, SAAS, SECURITY, SOFTWARE, SPORTS_AND_RECREATION, SUPPLY_CHAIN_AND_PROCUREMENT, TELECOMMUNICATIONS, TRAVEL, WELLNESS_AND_LIFESTYLE.
        - `negate_filter_industry` string[], nullable: Exclude contacts at companies in specified industries. Valid values: ACCOUNTING, ADVERTISING_AND_MARKETING, AGRICULTURE_AND_NATURAL_RESOURCES, ALCOHOL_AND_TOBACCO, AUTOMOTIVE, BIG_DATA_AND_ANALYTICS, BIOTECHNOLOGY, BLOCKCHAIN_AND_CRYPTOCURRENCY, BUSINESS_PRODUCTS_AND_SERVICES, CLOUD_COMPUTING, COMPUTER_HARDWARE_AND_SEMICONDUCTORS, CONGLOMERATES_SHELL_AND_HOLDING_COMPANIES, CONSTRUCTION, CONSUMER_PRODUCTS, CONSUMER_SERVICES, CYBERSECURITY, DEFENSE_AND_AEROSPACE, E-COMMERCE, EDUCATION, ENERGY, ENGINEERING, ENTERTAINMENT, ENVIRONMENTAL_SERVICES, FASHION_TEXTILE_AND_APPAREL, FINANCIAL_SERVICES, FOOD_AND_BEVERAGE, GAMING_AND_ESPORTS, GOVERNMENT_SERVICES, HEALTHCARE, HOSPITALITY, HUMAN_RESOURCES, INSURANCE, IT_SERVICES, LEGAL, MANUFACTURING, MEDIA, MINING_AND_METALS, NONPROFIT_AND_PHILANTHROPY, OIL_AND_GAS, PHARMACEUTICALS, PRIVATE_EQUITY_AND_VENTURE_CAPITAL, REAL_ESTATE, RENEWABLE_ENERGY, RESTAURANTS, RETAIL, SAAS, SECURITY, SOFTWARE, SPORTS_AND_RECREATION, SUPPLY_CHAIN_AND_PROCUREMENT, TELECOMMUNICATIONS, TRAVEL, WELLNESS_AND_LIFESTYLE.
        - `filter_country` string[], nullable: Filter by company country using ISO-3166-1 alpha-2 codes (e.g., US, GB, DE). Also accepts region aliases: EU, LATAM, MENA, APAC, NORDICS, DACH, BENELUX, GCC, ASEAN, CEE, ANZ, EUROPE, ASIA, AFRICA, NORTH_AMERICA, SOUTH_AMERICA, OCEANIA, ANTARCTICA.
        - `negate_filter_country` string[], nullable: Exclude contacts at companies in specified countries. Accepts same codes and region aliases as filter_country.
        - `filter_state` string[], nullable: Filter by company state/region. Accepts ISO 3166-2 codes or names, listed at https://docs.discolike.com/states/, resolved against the selected countries; a value that resolves under none is ignored.
        - `negate_filter_state` string[], nullable: Exclude contacts at companies in specified states. Same format as filter_state.
        - `employee_range` string, nullable: Filter by employee count range. Format: 'min,max' (e.g., '51,200'). Maps to buckets: 1-10, 11-50, 51-200, 201-500, 501-1000, 1001-5000, 5001-10000, 10001+.
        - `revenue_range` string, nullable: Company revenue range as 'min,max' in raw numbers, e.g. '10000000,50000000'.
        - `sub_industry` string[], nullable: Only include companies in these sub-industries.
    - DomainCompanies
      - `source` 'domains', required
      - `domains` string[], required: Company domains to find contacts at.
      - `scores` object, nullable: Optional relevance score per domain, keyed by domain.
    - LookalikeCompanies
      - `source` 'lookalike', required
      - `persona_ids` integer[]: Personas whose companies seed the lookalike search.
      - `linkedin_urls` string[]
  - `people` ContactsPeopleFit
    - `fit` string
  - `relevance` 'max_relevance' | 'balanced' | 'max_coverage'
  - `max_companies` integer: Target companies delivering at least one validated contact.
  - `per_company` integer: Maximum validated contacts per company.
  - `email_cap_usd` union: Maximum delivery spend in USD.
    - number
    - string
  - `exclude_query_ids` string[]
  - `exclude_domains` string[]
  - `create_key` string, nullable: Idempotency key for starting a run.

## Response `202`

The step was accepted and runs in the background.

- ContactsRunResponse
  - `progress` object
  - `applied_company_filters` PromptCompanyFilters
    - `filter_industry` string[], nullable: Filter by industry category (ANY-OF; prefix + to require a category). Valid values: ACCOUNTING, ADVERTISING_AND_MARKETING, AGRICULTURE_AND_NATURAL_RESOURCES, ALCOHOL_AND_TOBACCO, AUTOMOTIVE, BIG_DATA_AND_ANALYTICS, BIOTECHNOLOGY, BLOCKCHAIN_AND_CRYPTOCURRENCY, BUSINESS_PRODUCTS_AND_SERVICES, CLOUD_COMPUTING, COMPUTER_HARDWARE_AND_SEMICONDUCTORS, CONGLOMERATES_SHELL_AND_HOLDING_COMPANIES, CONSTRUCTION, CONSUMER_PRODUCTS, CONSUMER_SERVICES, CYBERSECURITY, DEFENSE_AND_AEROSPACE, E-COMMERCE, EDUCATION, ENERGY, ENGINEERING, ENTERTAINMENT, ENVIRONMENTAL_SERVICES, FASHION_TEXTILE_AND_APPAREL, FINANCIAL_SERVICES, FOOD_AND_BEVERAGE, GAMING_AND_ESPORTS, GOVERNMENT_SERVICES, HEALTHCARE, HOSPITALITY, HUMAN_RESOURCES, INSURANCE, IT_SERVICES, LEGAL, MANUFACTURING, MEDIA, MINING_AND_METALS, NONPROFIT_AND_PHILANTHROPY, OIL_AND_GAS, PHARMACEUTICALS, PRIVATE_EQUITY_AND_VENTURE_CAPITAL, REAL_ESTATE, RENEWABLE_ENERGY, RESTAURANTS, RETAIL, SAAS, SECURITY, SOFTWARE, SPORTS_AND_RECREATION, SUPPLY_CHAIN_AND_PROCUREMENT, TELECOMMUNICATIONS, TRAVEL, WELLNESS_AND_LIFESTYLE.
    - `negate_filter_industry` string[], nullable: Exclude contacts at companies in specified industries. Valid values: ACCOUNTING, ADVERTISING_AND_MARKETING, AGRICULTURE_AND_NATURAL_RESOURCES, ALCOHOL_AND_TOBACCO, AUTOMOTIVE, BIG_DATA_AND_ANALYTICS, BIOTECHNOLOGY, BLOCKCHAIN_AND_CRYPTOCURRENCY, BUSINESS_PRODUCTS_AND_SERVICES, CLOUD_COMPUTING, COMPUTER_HARDWARE_AND_SEMICONDUCTORS, CONGLOMERATES_SHELL_AND_HOLDING_COMPANIES, CONSTRUCTION, CONSUMER_PRODUCTS, CONSUMER_SERVICES, CYBERSECURITY, DEFENSE_AND_AEROSPACE, E-COMMERCE, EDUCATION, ENERGY, ENGINEERING, ENTERTAINMENT, ENVIRONMENTAL_SERVICES, FASHION_TEXTILE_AND_APPAREL, FINANCIAL_SERVICES, FOOD_AND_BEVERAGE, GAMING_AND_ESPORTS, GOVERNMENT_SERVICES, HEALTHCARE, HOSPITALITY, HUMAN_RESOURCES, INSURANCE, IT_SERVICES, LEGAL, MANUFACTURING, MEDIA, MINING_AND_METALS, NONPROFIT_AND_PHILANTHROPY, OIL_AND_GAS, PHARMACEUTICALS, PRIVATE_EQUITY_AND_VENTURE_CAPITAL, REAL_ESTATE, RENEWABLE_ENERGY, RESTAURANTS, RETAIL, SAAS, SECURITY, SOFTWARE, SPORTS_AND_RECREATION, SUPPLY_CHAIN_AND_PROCUREMENT, TELECOMMUNICATIONS, TRAVEL, WELLNESS_AND_LIFESTYLE.
    - `filter_country` string[], nullable: Filter by company country using ISO-3166-1 alpha-2 codes (e.g., US, GB, DE). Also accepts region aliases: EU, LATAM, MENA, APAC, NORDICS, DACH, BENELUX, GCC, ASEAN, CEE, ANZ, EUROPE, ASIA, AFRICA, NORTH_AMERICA, SOUTH_AMERICA, OCEANIA, ANTARCTICA.
    - `negate_filter_country` string[], nullable: Exclude contacts at companies in specified countries. Accepts same codes and region aliases as filter_country.
    - `filter_state` string[], nullable: Filter by company state/region. Accepts ISO 3166-2 codes or names, listed at https://docs.discolike.com/states/, resolved against the selected countries; a value that resolves under none is ignored.
    - `negate_filter_state` string[], nullable: Exclude contacts at companies in specified states. Same format as filter_state.
    - `employee_range` string, nullable: Filter by employee count range. Format: 'min,max' (e.g., '51,200'). Maps to buckets: 1-10, 11-50, 51-200, 201-500, 501-1000, 1001-5000, 5001-10000, 10001+.
    - `revenue_range` string, nullable: Company revenue range as 'min,max' in raw numbers, e.g. '10000000,50000000'.
    - `sub_industry` string[], nullable: Only include companies in these sub-industries.
  - `error` string, nullable
  - `input` object
  - `id` string, required
  - `kind` string, required
  - `status` string, required
  - `current_step` 'find_contacts' | 'find_missing' | 'find_emails' | 'discover' | 'validate'
  - `generation` integer, required
  - `steps` object
  - `total_estimate_usd` string, nullable
  - `total_charged_usd` string
  - `created_at` string, date-time, required
  - `updated_at` string, date-time, required
  - `expires_at` string, date-time, required
  - `companies` RunCompanyResponse[]
    - `company` object
    - `domain` string, required
    - `status` 'pending' | 'finding_people' | 'finding_emails' | 'validated' | 'skipped' | 'cancelled' | 'failed', required
    - `people_reviewed` integer
    - `mailboxes_checked` integer
    - `validated_contacts` integer
    - `contacts` RunRow[]
      - `row_key` string, required
      - `persona_id` integer, nullable
      - `domain` string, required
      - `name` string, nullable
      - `title` string, nullable
      - `linkedin_url` string, nullable
      - `seniority` string, nullable
      - `department` string, nullable
      - `debug_only` boolean, nullable
      - `reason` string, nullable
      - `company_score` number, nullable
      - `p_fit` number, nullable
      - `fit_label` string, nullable
      - `floor` boolean
      - `not_fit` boolean
      - `email` string, nullable
      - `email_status` string, nullable
      - `email_state` 'checking' | 'queued' | 'skipped', nullable
  - `companies_total` integer: Company domains available for pagination, including diagnostic rows in dev/local.
  - `summary` ContactsRunSummary
    - `skipped_no_mx` integer, nullable
    - `stop_reason` 'low_delivery_yield' | 'source_exhausted', nullable
    - `companies_delivered` integer, required
    - `validated_contacts` integer, required
    - `spent_usd` string, required
  - `contacts_total` integer: Visible contacts across the run. Contacts runs page by company domain, keeping each company and its contacts together.

## Other responses

- `422`: The request is invalid.

## Changes

- **2026-11-11** `ae154d624a26`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/discolike/apis/discolike-api/changes/contacts/run/post.md)

---

[API](https://skmtc.dev/discolike/apis/discolike-api.md) - [All operations](https://skmtc.dev/discolike/apis/discolike-api/llms.txt) - [OpenAPI document](https://skmtc.dev/discolike/apis/discolike-api/revisions/7f9a7b84671b?raw)
