> ## Documentation Index
> Fetch the complete documentation index at: https://docs.companyenrich.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Similar Companies API examples

> Ready-to-run lookalike company searches: one seed, several seeds with filters, a minimum similarity score, excluding existing customers, free counts, and CSV exports, in cURL, four SDKs, and the CLI.

Each example on this page is one [Similar Companies API](https://docs.companyenrich.com/docs/similar-companies-api.md) request, shown in cURL, the four official SDKs, and the CLI. Every version sends the same request.

## Before you start

Create an API key at [app.companyenrich.com/access-keys](https://app.companyenrich.com/access-keys). The SDK examples assume a `client` created like this, with the key in the `COMPANYENRICH_API_KEY` environment variable:

```javascript JavaScript theme={null}
// npm install @companyenrich/sdk
import { CompanyEnrich } from '@companyenrich/sdk';

const client = new CompanyEnrich();
```

```python Python theme={null}
# pip install companyenrich
from companyenrich import CompanyEnrich

client = CompanyEnrich()
```

```ruby Ruby theme={null}
# gem install companyenrich
require "companyenrich"

client = CompanyEnrich::Client.new
```

```php PHP theme={null}
<?php
// composer require companyenrich/sdk
require 'vendor/autoload.php';

use CompanyEnrich\Client;

$client = new Client();
```

```bash CLI theme={null}
npm install -g @companyenrich/cli
companyenrich auth login
```

In the cURL examples, replace `YOUR_API_TOKEN` with your key.

> [!NOTE]
>
> A lookalike search costs 5 credits for every company returned. To check a query for free first, see [Count lookalikes for free](#count-lookalikes-for-free).

## Find companies similar to one company

Send one seed domain. The response lists similar companies in ranked order, with a score for each.

```bash cURL theme={null}
curl -X POST https://api.companyenrich.com/v2/companies/search \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "lookalike": {"domains": ["stripe.com"]},
    "pageSize": 25
  }'
```

```javascript JavaScript theme={null}
const similar = await client.companies.search({
  lookalike: { domains: ['stripe.com'] },
  pageSize: 25,
});

for (const company of similar.items) {
  console.log(company.domain, similar.scores?.[company.id]);
}
```

```python Python theme={null}
similar = client.companies.search(
    lookalike={"domains": ["stripe.com"]},
    page_size=25,
)

scores = similar.get("scores") or {}
for company in similar["items"]:
    print(company["domain"], scores.get(company["id"]))
```

```ruby Ruby theme={null}
similar = client.companies.search(
  lookalike: { domains: ["stripe.com"] },
  page_size: 25
)

scores = similar["scores"] || {}
similar["items"].each do |company|
  puts "#{company['domain']} #{scores[company['id']]}"
end
```

```php PHP theme={null}
$similar = $client->companies->search(
    lookalike: ['domains' => ['stripe.com']],
    pageSize: 25,
);

foreach ($similar['items'] as $company) {
    echo $company['domain'], ' ', $similar['scores'][$company['id']] ?? '', PHP_EOL;
}
```

```bash CLI theme={null}
companyenrich company similar stripe.com --limit 25
```

Scores are not probabilities. Keep the companies in the order returned.

## Use several seeds and filter by market

Send up to 10 seeds to describe the kind of company you want, then narrow the lookalikes with filters. This search finds companies like Stripe and Adyen in the United States and Canada with 51 to 200 employees.

```bash cURL theme={null}
curl -X POST https://api.companyenrich.com/v2/companies/search \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "lookalike": {"domains": ["stripe.com", "adyen.com"]},
    "filter": {"country": ["US", "CA"], "employees": "51-200"},
    "pageSize": 25
  }'
```

```javascript JavaScript theme={null}
const similar = await client.companies.search({
  lookalike: { domains: ['stripe.com', 'adyen.com'] },
  filter: { country: ['US', 'CA'], employees: '51-200' },
  pageSize: 25,
});

for (const company of similar.items) {
  console.log(company.domain, similar.scores?.[company.id]);
}
```

```python Python theme={null}
similar = client.companies.search(
    lookalike={"domains": ["stripe.com", "adyen.com"]},
    filter={"country": ["US", "CA"], "employees": "51-200"},
    page_size=25,
)

scores = similar.get("scores") or {}
for company in similar["items"]:
    print(company["domain"], scores.get(company["id"]))
```

```ruby Ruby theme={null}
similar = client.companies.search(
  lookalike: { domains: ["stripe.com", "adyen.com"] },
  filter: { country: ["US", "CA"], employees: "51-200" },
  page_size: 25
)

scores = similar["scores"] || {}
similar["items"].each do |company|
  puts "#{company['domain']} #{scores[company['id']]}"
end
```

```php PHP theme={null}
$similar = $client->companies->search(
    lookalike: ['domains' => ['stripe.com', 'adyen.com']],
    filter: ['country' => ['US', 'CA'], 'employees' => '51-200'],
    pageSize: 25,
);

foreach ($similar['items'] as $company) {
    echo $company['domain'], ' ', $similar['scores'][$company['id']] ?? '', PHP_EOL;
}
```

```bash CLI theme={null}
companyenrich company similar stripe.com adyen.com --country US,CA --employees 51-200 --limit 25
```

Every [company search filter](https://docs.companyenrich.com/docs/company-search-api-filters.md) works with a lookalike search.

## Require a minimum similarity

Set `minScore`, from 0 to 1, to drop weaker matches.

```bash cURL theme={null}
curl -X POST https://api.companyenrich.com/v2/companies/search \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "lookalike": {"domains": ["notion.so"], "minScore": 0.7},
    "pageSize": 25
  }'
```

```javascript JavaScript theme={null}
const similar = await client.companies.search({
  lookalike: { domains: ['notion.so'], minScore: 0.7 },
  pageSize: 25,
});

for (const company of similar.items) {
  console.log(company.domain, similar.scores?.[company.id]);
}
```

```python Python theme={null}
similar = client.companies.search(
    lookalike={"domains": ["notion.so"], "minScore": 0.7},
    page_size=25,
)

scores = similar.get("scores") or {}
for company in similar["items"]:
    print(company["domain"], scores.get(company["id"]))
```

```ruby Ruby theme={null}
similar = client.companies.search(
  lookalike: { domains: ["notion.so"], minScore: 0.7 },
  page_size: 25
)

scores = similar["scores"] || {}
similar["items"].each do |company|
  puts "#{company['domain']} #{scores[company['id']]}"
end
```

```php PHP theme={null}
$similar = $client->companies->search(
    lookalike: ['domains' => ['notion.so'], 'minScore' => 0.7],
    pageSize: 25,
);

foreach ($similar['items'] as $company) {
    echo $company['domain'], ' ', $similar['scores'][$company['id']] ?? '', PHP_EOL;
}
```

```bash CLI theme={null}
companyenrich company similar notion.so --min-score 0.7 --limit 25
```

## Exclude companies you already have

Use the `domain` filter with `notIn` to leave out companies you already work with.

```bash cURL theme={null}
curl -X POST https://api.companyenrich.com/v2/companies/search \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "lookalike": {"domains": ["stripe.com", "adyen.com"]},
    "filter": {"domain": {"notIn": ["checkout.com", "mollie.com"]}},
    "pageSize": 25
  }'
```

```javascript JavaScript theme={null}
const similar = await client.companies.search({
  lookalike: { domains: ['stripe.com', 'adyen.com'] },
  filter: { domain: { notIn: ['checkout.com', 'mollie.com'] } },
  pageSize: 25,
});

for (const company of similar.items) {
  console.log(company.domain, similar.scores?.[company.id]);
}
```

```python Python theme={null}
similar = client.companies.search(
    lookalike={"domains": ["stripe.com", "adyen.com"]},
    filter={"domain": {"notIn": ["checkout.com", "mollie.com"]}},
    page_size=25,
)

scores = similar.get("scores") or {}
for company in similar["items"]:
    print(company["domain"], scores.get(company["id"]))
```

```ruby Ruby theme={null}
similar = client.companies.search(
  lookalike: { domains: ["stripe.com", "adyen.com"] },
  filter: { domain: { notIn: ["checkout.com", "mollie.com"] } },
  page_size: 25
)

scores = similar["scores"] || {}
similar["items"].each do |company|
  puts "#{company['domain']} #{scores[company['id']]}"
end
```

```php PHP theme={null}
$similar = $client->companies->search(
    lookalike: ['domains' => ['stripe.com', 'adyen.com']],
    filter: ['domain' => ['notIn' => ['checkout.com', 'mollie.com']]],
    pageSize: 25,
);

foreach ($similar['items'] as $company) {
    echo $company['domain'], ' ', $similar['scores'][$company['id']] ?? '', PHP_EOL;
}
```

```bash CLI theme={null}
companyenrich company similar stripe.com adyen.com --exclude-domain checkout.com,mollie.com --limit 25
```

## Count lookalikes for free

The count endpoint takes the same `lookalike` and `filter` fields as a search and costs nothing.

```bash cURL theme={null}
curl -X POST https://api.companyenrich.com/v2/companies/search/count \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "lookalike": {"domains": ["stripe.com"]},
    "filter": {"country": "US"}
  }'
```

```javascript JavaScript theme={null}
const { count, total } = await client.companies.count({
  lookalike: { domains: ['stripe.com'] },
  filter: { country: 'US' },
});
console.log(count, total);
```

```python Python theme={null}
result = client.companies.count(
    lookalike={"domains": ["stripe.com"]},
    filter={"country": "US"},
)
print(result["count"], result["total"])
```

```ruby Ruby theme={null}
result = client.companies.count(
  lookalike: { domains: ["stripe.com"] },
  filter: { country: "US" }
)
puts result["count"], result["total"]
```

```php PHP theme={null}
$result = $client->companies->count(
    lookalike: ['domains' => ['stripe.com']],
    filter: ['country' => 'US'],
);
echo $result['count'], ' ', $result['total'], PHP_EOL;
```

```bash CLI theme={null}
companyenrich company count --similar-to stripe.com --country US
```

`count` is the number of companies your plan can access. For a lookalike query, `total` describes the pool of candidates the similarity search draws from.

## Export lookalikes to CSV

An export runs the lookalike search in the background and stores the results as one file. It costs the same per company as the search itself. The CSV has a `score` column next to the company columns.

```bash cURL theme={null}
# 1. Start the export. The response includes the batch "id".
curl -X POST https://api.companyenrich.com/v2/companies/search/export \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "limit": 1000,
    "lookalike": {"domains": ["stripe.com"]},
    "filter": {"country": "US"}
  }'

# 2. Check the batch until "status" is "completed".
curl https://api.companyenrich.com/v2/batches/BATCH_ID \
  -H "Authorization: Bearer YOUR_API_TOKEN"

# 3. Download the results as CSV.
curl "https://api.companyenrich.com/v2/companies/search/export/BATCH_ID/results?format=csv" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -o lookalikes.csv
```

```javascript JavaScript theme={null}
import { writeFile } from 'node:fs/promises';

const job = await client.companies.searchExport.create({
  limit: 1000,
  lookalike: { domains: ['stripe.com'] },
  filter: { country: 'US' },
});

await client.batches.waitForCompletion(job.id);

const response = await client.companies.searchExport.csv(job.id);
await writeFile('lookalikes.csv', await response.text());
```

```python Python theme={null}
job = client.companies.search_export.create(
    1000,
    lookalike={"domains": ["stripe.com"]},
    filter={"country": "US"},
)

client.batches.wait_for_completion(job["id"])

with open("lookalikes.csv", "w", encoding="utf-8") as file:
    file.write(client.companies.search_export.csv(job["id"]))
```

```ruby Ruby theme={null}
job = client.companies.search_export.create(
  1000,
  lookalike: { domains: ["stripe.com"] },
  filter: { country: "US" }
)

client.batches.wait_for_completion(job["id"])

File.write("lookalikes.csv", client.companies.search_export.csv(job["id"]))
```

```php PHP theme={null}
$job = $client->companies->searchExport->create(
    1000,
    lookalike: ['domains' => ['stripe.com']],
    filter: ['country' => 'US'],
);

$client->batches->waitForCompletion($job['id']);

file_put_contents('lookalikes.csv', $client->companies->searchExport->csv($job['id']));
```

```bash CLI theme={null}
companyenrich company export --similar-to stripe.com --country US --limit 1000 --wait -o lookalikes.csv
```

## Find people at lookalike companies

To get people instead of companies, send the same seeds in `company.lookalike` on a people search. See [Find people at companies like your customers](https://docs.companyenrich.com/docs/people-search-api-examples.md#find-people-at-companies-like-your-customers).

## Related pages

> [card] [Similar Companies API](https://docs.companyenrich.com/docs/similar-companies-api.md)
>
> Ranking, scores, pricing, limits, and V1 mapping.

> [card] [Company Search API filters](https://docs.companyenrich.com/docs/company-search-api-filters.md)
>
> Every filter you can add to a lookalike search.

> [card] [Company Search API examples](https://docs.companyenrich.com/docs/company-search-api-examples.md)
>
> Filter and semantic searches.

> [card] [Credits](https://docs.companyenrich.com/docs/credits.md)
>
> What each search and expansion costs.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.