Company Search
company-searchStart a paid job billed to the user's Desearch balance: find companies on the web that match a plain-language description, and collect each one's public contact data. Returns a task_id at once, with the task's status and reserved_cost_usd. Cost: without max_cost_usd, the call reserves count companies at the Company Search per-company price at the time of the call (reserved_cost_usd; prices at https://desearch.ai/pricing). When the task ends you pay only for the companies it delivered (final_cost_usd; a minimum of 1 when it delivers any; a task that delivers none is free) and the rest of the reservation is returned. A company left out by min_score or require is not billed. Such a search stops once it costs more than the companies it found pay for (completion_reason cost_limit, coverage_limited: true). Search budget: with max_cost_usd the whole budget is reserved, and the search goes on until it delivers count or spends the budget. Its search effort is billed where the companies delivered do not cover it, up to the budget, even when it finds few companies or none; the unused part is returned. Set max_cost_usd only when the user agreed to spend that amount, never on your own. Find more: when a search ended before count because a limit stopped it (coverage_limited, for example cost_limit), offer the user a new company-search with the same query and filters, continue_from set to its task_id, and count set to the companies still wanted, optionally with a budget the user agrees to. It leaves out every company the earlier search delivered or held for review, so it finds only new ones. To check only companies you name, give their websites in query, for example 'Restrict this search to Acme (acme.com.au) and Beta (beta.co.uk). Return only those.' Only those domains are then checked against the rest of the description, with no web search (the task shows them as only_domains and ends with completion_reason all_domains_processed). Companies named without their websites do not restrict the search (warning scope_not_applied). Each company has a fit score (0-100) and why it matched, plus fully_verified and unverified_criteria (what its own pages do and do not confirm). Data: Desearch reads public data only: each company's own website (its homepage and its contact, about, team, and imprint pages), public web search results, and public LinkedIn profiles of its leaders. Each company comes back with its location, public emails, phones, and social profiles, and its leaders (roles) with their title, LinkedIn profile, and emails. Every contact keeps the page it came from (source_url). Leader emails can be inferred from the company's address pattern (source: inferred, with a confidence), and every email is checked (verification: valid, invalid, risky, or unknown). Companies stay readable for 30 days after the task ends. The task runs in the background: poll company-search-status with the task_id to read progress and the companies delivered so far. Each company is delivered first with enrichment status partial, and the later stages (contact pages, leaders, inferred emails, email checks) fill it in until it is complete. Use company-search-pause, company-search-resume, or company-search-cancel to pause, resume, or cancel it. Do not start the same task twice; send idempotency_key so a retry returns the first task instead of charging again. To read companies you already know by domain, use company-enrich instead.
Tool call template
Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {
"query": "<query>"
},
"name": "company-search"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| count | No | How many companies to deliver (5-200, API default 25). Without max_cost_usd the task reserves this many and bills only the companies it delivers. With continue_from, the companies still wanted. | |
| query | Yes | The companies you are looking for, in plain language: what they do, where, how far along. Example: 'Series A fintech startups in Berlin building payment infrastructure'. To check only companies you name, give each one's website: 'Restrict this search to Acme (acme.com.au) and Beta (beta.co.uk). Return only those.' Only those domains are checked; companies named without a website do not restrict the search (warning scope_not_applied). | |
| roles | No | The leaders to look for: any of 'ceo', 'founder', 'cto', 'cfo', 'coo', 'cmo', 'president', 'owner', 'managing_director' (API default ['ceo', 'founder', 'cto', 'cfo']). A managing director (Geschäftsführer) counts as 'ceo' when 'ceo' is asked for. | |
| exclude | No | Companies to leave out, as domains or URLs, for example ones you already contacted (up to 1000). Each is reduced to its host without www. | |
| require | No | Only deliver companies that have all of these: 'email', 'phone', 'linkedin' (the company's LinkedIn page), 'leader' (one of roles), 'leader_email' (a leader with an email). A company is delivered once the stage that can show them has run (email, phone, linkedin: the contact pages; leader: the leaders; leader_email: the email checks); one that does not have them is not delivered and not billed. Sent as filters.require. | |
| metadata | No | Your own labels for this task, example: {"campaign": "q4-outbound"}. Up to 10 keys; keys are 1-40 characters of a-z, 0-9, '_', '.', '-'; values are strings of up to 200 characters. Returned on the task; filter company-search-tasks by it. The task does not use it. | |
| countries | No | Where the companies should be: ISO 3166-1 alpha-2 codes or country names, example: ['DE', 'Austria'] (up to 20). Scoring treats them as a location criterion. Sent as filters.countries. | |
| min_score | No | Only deliver companies with at least this fit score (0-100). | |
| infer_emails | No | Guess leaders' emails from the company's address pattern (for example first.last), learned from the addresses found on its site (API default true). Inferred emails say source: inferred and carry a confidence: high when the pattern was learned from this company's own addresses, low for a common pattern. | |
| max_cost_usd | No | Search budget in USD (more than 0, up to 100): the most this task may charge. Set it only when the user agreed to spend this amount. It must be at least what count reserves (count times the per-company price; a smaller budget is refused with HTTP 422, which gives the minimum). The whole budget is reserved (reserved_cost_usd) and the search goes on until it delivers count or spends the budget. Its search effort is billed where the companies delivered do not cover it, up to the budget, even when it finds few companies or none; the unused part is returned when the task ends. Without it, the search stops once it costs more than the companies it found pay for (cost_limit), and only the companies delivered are billed. | |
| continue_from | No | task_id of an earlier Company Search of yours that has ended, to find only new companies: this search leaves out every company that one delivered, held for review, or was told to exclude, as well as your own exclude. Send the same query and filters with count set to the companies still wanted. HTTP 409 while that task has not ended (queued, running, or paused); 404 when it is not your Company Search (a Company Enrich or People Search task_id is refused). | |
| verify_emails | No | Check every email: syntax, mail server (MX) and, for inferred ones, a web search (API default true). Each email then has a verification: valid, invalid, risky, or unknown. Set false to finish sooner without it. | |
| idempotency_key | No | Any unique string for this task, for example a UUID. Sending the same key again returns the first task and is not charged again. |