API Guides

    Company Search API: Find Companies by Description

    By Desearch Editorial Team8 min read
    Request panel with a plain-language company description next to three status chips and three company cards showing fit scores and source page links.

    The Company Search API takes a plain-language description of the companies you want and returns a task_id at once. You poll the task and read the companies it delivers, each with a fit score and the pages it came from. Companies, not pages.

    This guide shows what to send, what comes back, how to read and check it, how to export it, and what it costs.

    What the Company Search API returns

    Web Search returns pages. Company Search returns companies, like a company search engine you call from code. You describe the kind of company you want, and each result is one company, read from its own site and the web.

    Each company comes with these fields:

    FieldWhat it holds
    domainThe company's website domain
    nameThe company name
    descriptionWhat the company says it does
    industryThe industry it works in
    locationCity, address and country when found
    socialsPublic social profiles linked from the site
    pagesThe pages the company was read from
    scoreThe fit score, with reasons and per-criterion checks

    You choose how many companies to ask for with count: 5 to 200, default 25. The Console playground accepts 5 to 50.

    If you work with a company data API today, the difference is the starting point. You don't need a list of names or domains. You start from a description.

    Start a company search task

    Create an API key in Desearch Console, then send the search:

    BASH
    curl --request POST 'https://api.desearch.ai/desearch/companies/search' \
      --header "Authorization: $DESEARCH_API_KEY" \
      --header 'Content-Type: application/json' \
      --header "Idempotency-Key: $(uuidgen)" \
      --data '{
        "query": "Construction companies based in Queensland, Australia",
        "count": 5
      }'

    The fields:

    • query: what you are looking for, in plain words, 3 to 1000 characters.
    • count: how many companies to find, 5 to 200.
    • filters.countries (optional): country codes to keep, up to 20.

    The Idempotency-Key header protects you from a double send. If you send the same key again, you get the first task back with HTTP 200 and you are not charged again.

    The response is HTTP 202 with status set to queued, a task_id and reserved_cost_usd. It holds no companies yet. Those come from the task.

    Poll the task until it ends

    Call GET /desearch/companies/tasks/{task_id} every few seconds. The task has ended when its status is completed, partial, failed, cancelled or expired. Check the task, not a results page, to know when it is done.

    When it ends, read two fields:

    FieldWhat it tells you
    completion_reasonWhy the search stopped, for example count_reached, rounds_exhausted, no_candidates, zero_qualified, cost_limit or time_limit
    coverage_limitedWhether a limit stopped the search before it reached count

    A task can end as completed with no companies at all. In that case completion_reason is zero_qualified, result_count is 0 and billed_units is 0: the search found candidates, none of them matched your description, and the reserved cost was refunded.

    If the task delivered fewer companies than count, describe the companies more broadly, or start a new search and put the domains you already have in exclude.

    You can also pause, resume or cancel a task with POST /desearch/companies/tasks/{task_id}/pause, /resume and /cancel.

    Read the results with a cursor

    Read companies with GET /desearch/companies/tasks/{task_id}/results. Set limit from 1 to 500 (default 100). Leave out cursor on the first call, then pass next_cursor back on the next one. has_more tells you if there is more to read.

    A company is published before every stage has run on it. Its enrichment.status is partial first, then complete. A cursor returns only new companies, so it does not bring back the newer version of a company you already read. To get the latest version of every company, read again without a cursor, or wait for the task to end and read once.

    Results are kept for 30 days after the task ends (results_expire_at).

    The same flow in Python

    This version uses plain requests. We ran it with a real key on 2026-11-16 and it printed 5 companies:

    PYTHON
    import os, time, uuid, requests
    
    BASE = "https://api.desearch.ai"
    HEADERS = {"Authorization": os.environ["DESEARCH_API_KEY"]}
    
    task = requests.post(
        f"{BASE}/desearch/companies/search",
        headers={**HEADERS, "Idempotency-Key": str(uuid.uuid4())},
        json={"query": "Construction companies based in Queensland, Australia",
              "count": 5},
    ).json()
    task_id = task["task_id"]
    
    while True:
        state = requests.get(f"{BASE}/desearch/companies/tasks/{task_id}", headers=HEADERS).json()
        if state["status"] in ("completed", "partial", "failed", "cancelled", "expired"):
            break
        time.sleep(5)
    
    # task has ended: read every company in its latest version (no cursor)
    page = requests.get(f"{BASE}/desearch/companies/tasks/{task_id}/results",
                        headers=HEADERS, params={"limit": 100}).json()
    if not page["results"]:
        print("No companies:", state.get("completion_reason"))
    for company in page["results"]:
        print(company["domain"], company["score"]["value"], company["score"]["summary"])

    If the task has more companies than limit, keep calling /results with next_cursor while has_more is true.

    What a result looks like

    This is a trimmed real response from the same search as the examples above, "Construction companies based in Queensland, Australia" with count 5, run on 2026-11-02. It shows 2 of the 5 companies and keeps only domain, name, industry, location, score.value and score.summary. Every other field is left out.

    JSON
    {
      "results": [
        {
          "domain": "gcecontractors.com.au",
          "name": "GCE Contractors",
          "industry": "Civil construction",
          "location": {"city": "Windsor, QLD 4030", "address": "55 McDonald Road", "country": "AU"},
          "score": {
            "value": 98,
            "summary": "GCE Contractors is a Brisbane-based civil construction company delivering pipeline, earthworks, roadworks, demolition and related construction services across Queensland."
          }
        },
        {
          "domain": "pembc.com.au",
          "name": "Pembroke Construction",
          "industry": "Civil construction and property development",
          "location": {"city": "Brisbane", "address": "2/1 Wyuna Ct Hemmant Brisbane QLD", "country": "AU"},
          "score": {
            "value": 98,
            "summary": "Pembroke Construction is a Brisbane-based building and civil construction company serving South East Queensland."
          }
        }
      ]
    }

    The full list of result fields is in the Company Search API reference.

    Check each fit score and its source pages

    A fit score is only useful if you can check it. Each company's score holds:

    FieldWhat it holds
    score.valueThe fit score, 0 to 100
    score.summaryOne line on why the company fits
    score.reasonsThe reasons it matched
    score.concernsAnything that weakens the match
    score.criteria_checksOne check per part of your description, each with criterion, verdict, quote and source_url
    score.fully_verifiedWhether every criterion was checked against the pages

    Each verdict is met, not_met or unknown. unknown means nothing found shows it either way. Treat a missing value as unknown, not as absent. The quote and source_url let you open the page and read the line yourself.

    Three fields shape the list:

    FieldWhat it does
    min_scoreKeep only companies at or above this fit score (0 to 100)
    excludeDomains or URLs to leave out, up to 1,000. Use it for companies you already have
    filters.countriesCountry codes to keep, up to 20

    Leaders are optional, not guaranteed

    Leaders are included when they are found. Some companies have none, so people can be empty for a company. Check people on each company. If you only want companies that have a leader, set filters.require: ["leader"]. A company left out by that filter is not billed.

    Export the list as CSV

    When you want the list in a spreadsheet, export the task:

    BASH
    curl 'https://api.desearch.ai/desearch/companies/tasks/TASK_ID/export?format=csv' \
      --header "Authorization: $DESEARCH_API_KEY" \
      --output companies.csv

    You get one row per company. Use format=jsonl for JSON Lines, one company per line. See the Company Search guide for the full column list.

    Use Company Enrich when you already have the domains

    If you already know which companies you want, start from their domains instead of a description. POST /desearch/companies/enrich takes 1 to 200 domains or URLs and returns one company per domain. It uses the same task routes to poll, read and export. As a company enrichment API it fills in the company record, but there is no description to score against, so score is null. See the Company Enrich API reference.

    Company Search API pricing

    ProductPrice
    Company Search$45.00 / 1000 companies

    Billed per company delivered, with a minimum of 1 company. Rates as of 28 Oct 2026. All prices in USD. Confirm current rates in Console.

    How billing works:

    • When a task starts, Company Search reserves the number of companies you ask for in count.
    • When the task ends, you pay for the companies it delivered. The rest of the reservation is returned.
    • A task that delivers no companies is not billed.
    • Polling, results, exports, pause, resume and cancel are not billed.

    See the pricing page for details.

    FAQ

    What does the Company Search API return?

    Companies, not pages. Each company comes with a fit score and the pages it was read from. Leaders are included in people when they are found.

    How do I read results while the task is running?

    Poll the task, and read /results with next_cursor. A cursor returns only new companies, so read again without a cursor to get the latest version of every company.

    How many companies can I ask for?

    count is 5 to 200 through the API. The Console playground accepts 5 to 50.

    Do I pay for companies I did not receive?

    No. You pay for the companies delivered, with a minimum of 1 company. A task that delivers no companies is not billed.

    What if I send the same request twice?

    Send an Idempotency-Key header. The same key returns the first task and is not charged again.

    How do I get the list into a spreadsheet?

    Export the task with GET /desearch/companies/tasks/{task_id}/export?format=csv. You get one row per company.

    What is the difference between Company Search and Company Enrich?

    Company Search takes a description and returns companies with a fit score. Company Enrich takes domains and returns one company per domain, with no fit score.

    Does every company come with leaders?

    No. Leaders appear when they are found. Check people on each company.

    Get started

    1. Create an API key in Console.
    2. Run the cURL request above with your own description.
    3. Follow the Company Search guide for the full task flow and result fields. Looking for people instead of companies? See how to find people by description with the People Search API.

    Get an API key in Console and describe your first set of companies. New accounts get $5 in API credits after attaching a card in Console, then pay as they go.

    Open Console

    Put your next idea to work.

    Try a query in the playground, then use the docs to bring Desearch into your application.

    Browse more articles