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

# Semantic Company Search API

> Find companies from a plain-language description. Covers the semantic request, how the query is interpreted, combining it with filters, ranking weight, pricing, limits, and the V1 mapping.

Semantic company search finds companies from a description written in plain language, such as `AI tools for hospitals`, where a filter search needs exact values. Use it when you can say what the companies do but cannot express it as an industry code or a keyword list.

In the V2 API, this is the semantic mode of [company search](https://docs.companyenrich.com/docs/company-search-api.md): send a `semantic` object to [`POST /v2/companies/search`](https://docs.companyenrich.com/api-reference/v2/post-companies-search). A semantic search costs 2 credits per company returned, and each result is a full [company record](https://docs.companyenrich.com/docs/company-schema.md).

> [card] [Filters](https://docs.companyenrich.com/docs/semantic-company-search-api-filters.md)
>
> What the API infers from a description, and what needs a filter.

> [card] [Examples](https://docs.companyenrich.com/docs/semantic-company-search-api-examples.md)
>
> Semantic searches in cURL, four SDKs, and the CLI.

## Search with a description

This request finds companies that build AI tools for hospitals. You need an API key, which you can create at [app.companyenrich.com/access-keys](https://app.companyenrich.com/access-keys).

```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 '{
    "semantic": {"query": "AI tools for hospitals"},
    "pageSize": 10
  }'
```

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

const client = new CompanyEnrich(); // reads COMPANYENRICH_API_KEY

const page = await client.companies.search({
  semantic: { query: 'AI tools for hospitals' },
  pageSize: 10,
});

for (const company of page.items) {
  console.log(company.name, company.domain);
}
```

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

client = CompanyEnrich()  # reads COMPANYENRICH_API_KEY

page = client.companies.search(
    semantic={"query": "AI tools for hospitals"},
    page_size=10,
)

for company in page["items"]:
    print(company.get("name"), company["domain"])
```

```ruby Ruby theme={null}
require "companyenrich"

client = CompanyEnrich::Client.new # reads COMPANYENRICH_API_KEY

page = client.companies.search(
  semantic: { query: "AI tools for hospitals" },
  page_size: 10
)

page["items"].each do |company|
  puts "#{company['name']} (#{company['domain']})"
end
```

```php PHP theme={null}
<?php

require 'vendor/autoload.php';

use CompanyEnrich\Client;

$client = new Client(); // reads COMPANYENRICH_API_KEY

$page = $client->companies->search(
    semantic: ['query' => 'AI tools for hospitals'],
    pageSize: 10,
);

foreach ($page['items'] as $company) {
    echo $company['name'] ?? '', ' ', $company['domain'], PHP_EOL;
}
```

```bash CLI theme={null}
companyenrich company search --semantic "AI tools for hospitals" --limit 10
```

The response holds the matching companies, a cursor for the next page, and an `interpretation` of your query when the API inferred something from it.

## When to use semantic search

| You have | Use | Credits per company |
| - | - | - |
| Exact criteria, such as a country, a size range, or a technology | [Filter search](https://docs.companyenrich.com/docs/company-search-api-filters.md) | 1 |
| A description of what the companies do | Semantic search | 2 |
| Example companies you want more of | [Lookalike search](https://docs.companyenrich.com/docs/similar-companies-api.md) | 5 |

A semantic search can be combined with filters. It cannot be combined with a lookalike search in the same request.

## Request fields

| Field | Value | Description |
| - | - | - |
| `semantic.query` | string, required | The description of the companies you want. Up to 500 characters. |
| `semantic.weight` | number from 0 to 1 | How much semantic similarity counts in ranking. Larger values count it more. |
| `semantic.autoFilter` | boolean, default `true` | Whether to infer company attributes, such as location and size, from the query. |
| `filter` | object | Any [company search filter](https://docs.companyenrich.com/docs/company-search-api-filters.md), to narrow the results. |
| `expand` | array of strings | Paid data to add to each company, at 1 extra credit each per company. |
| `pageSize` | integer from 1 to 100 | The number of companies to return. |
| `cursor` | string | The `nextCursor` from the previous response, to get the next page. |

## How your query is interpreted

By default, the API reads company attributes from your description and applies them for you. Some attributes filter the results, and others only change the ranking.

| Attribute found in the query | Effect |
| - | - |
| Location, employee range, founded year, funding | **Filters** the results. Companies that do not match are left out. |
| Categories, such as SaaS, and revenue | **Ranks** matching companies higher, without excluding the others. |
| A company name | **Ranks** that company first. |

For example, `saas companies in Turkey` returns only companies in Turkey and ranks companies categorized as SaaS higher. `Monzo digital bank` ranks Monzo first.

The response's `interpretation` field reports what was inferred:

| Field | Description |
| - | - |
| `interpretation.filter` | The filters inferred from the query, in the same format as the request `filter`. |
| `interpretation.boost.names` | Company names found in the query. A company with a matching name or domain ranks first. |
| `interpretation.boost.categories` | Categories that rank a company higher. |
| `interpretation.boost.revenue` | Revenue ranges that rank a company higher. |

Parts with nothing inferred are omitted.

## Combine a description with filters

Add a `filter` object to set exact criteria next to your description.

```json theme={null}
{
  "semantic": { "query": "vertical SaaS for dentists" },
  "filter": {
    "country": ["US", "CA"],
    "employees": ["11-50", "51-200"]
  }
}
```

* A filter you send takes precedence over an inferred value of the same kind. If your description mentions a country and you also send `filter.country`, your filter is used.
* An exclusion you send, such as `notIn`, applies together with the inferred values.

See [Semantic Company Search API filters](https://docs.companyenrich.com/docs/semantic-company-search-api-filters.md) for when a description is enough and when to add a filter.

## Turn off inference

Set `semantic.autoFilter` to `false` to use the description for semantic matching only. Nothing is inferred, the results are limited only by the filters you send, and the response has no `interpretation`.

```json theme={null}
{
  "semantic": { "query": "AI tools for hospitals", "autoFilter": false },
  "filter": { "country": "US" }
}
```

## Tune the ranking

`semantic.weight` sets how much semantic similarity counts when results are ranked. It takes a number from 0 to 1, and larger values give similarity more weight.

## Where semantic queries work

| Endpoint | What a semantic query does there | Credits |
| - | - | - |
| [`POST /v2/companies/search`](https://docs.companyenrich.com/api-reference/v2/post-companies-search) | Returns one page of matching companies. | 2 per company |
| [`POST /v2/companies/search/count`](https://docs.companyenrich.com/api-reference/v2/post-companies-search-count) | Counts the matches and reports the `interpretation`. | Free |
| [`POST /v2/companies/search/preview`](https://docs.companyenrich.com/api-reference/v2/post-companies-search-preview) | Returns up to 25 company summaries. Needs a plan that includes previews. | Free |
| [`POST /v2/companies/search/export`](https://docs.companyenrich.com/api-reference/v2/post-companies-search-export) | Exports a large semantic search in the background. | 2 per company |
| [`POST /v2/people/search`](https://docs.companyenrich.com/api-reference/v2/post-people-search) | With `company.semantic`, finds people at companies that match a description. | 2 per person |

People search has its own semantic mode for describing the people themselves. See [Describe who you want](https://docs.companyenrich.com/docs/people-search-api-examples.md#describe-who-you-want).

## What a semantic search costs

* 2 credits per company returned, plus 1 for each expansion.
* A search that returns no results costs 2 credits.
* Count and preview requests are free.

For example, 25 companies with the `technologies` expansion cost 25 × (2 + 1) = 75 credits. See [Credits](https://docs.companyenrich.com/docs/credits.md) for every price.

## Limits

| Limit | Value |
| - | - |
| Query length | 500 characters |
| Results per page (`pageSize`) | 1 to 100 |
| Cursor lifetime | 24 hours after the first page |
| Preview size | Up to 25 companies |
| Export size (`limit`) | Up to 1,000,000 results, and no more than your plan's search limit |

## Coming from the V1 API

V1 company search takes the description as a top-level field. V2 groups the semantic options in one object and adds query interpretation.

| V1 | V2 |
| - | - |
| `semanticQuery` on [`POST /companies/search`](https://docs.companyenrich.com/api-reference/v1/post-companies-search) | `semantic.query` on `POST /v2/companies/search` |
| `semanticWeight` | `semantic.weight` |
| No query interpretation | `semantic.autoFilter` and the `interpretation` response field |
| 1 credit per company | 2 credits per company |

## Common questions

### How is semantic search different from filter search?

A filter search matches exact values you choose, such as a country code or an employee range. A semantic search matches the meaning of a description, so it finds companies you could not list keywords for. You can use both in one request.

### Why did my search leave out companies in other countries?

Your description probably mentioned a place. An inferred location filters the results. Check `interpretation.filter` in the response, and set `semantic.autoFilter` to `false` if you do not want the API to infer filters.

### Can I combine semantic and lookalike search?

No. A request can contain `semantic` or `lookalike`, not both. Either one can be combined with `filter`.

### Can I search for people with a description?

Yes, in two ways. Describe the people with `semantic` on a people search, or describe their employers with `company.semantic`. See the [People Search API](https://docs.companyenrich.com/docs/people-search-api.md).

### How do I try a description without spending credits?

Send it to the [count endpoint](https://docs.companyenrich.com/api-reference/v2/post-companies-search-count.md), which is free and also returns the `interpretation`. If your plan includes previews, the [preview endpoint](https://docs.companyenrich.com/api-reference/v2/post-companies-search-preview.md) returns up to 25 company summaries for free.

## Related pages

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

> [card] [Semantic Company Search API filters](https://docs.companyenrich.com/docs/semantic-company-search-api-filters.md)
>
> What the API infers, and what needs a filter.

> [card] [Similar Companies API](https://docs.companyenrich.com/docs/similar-companies-api.md)
>
> Find companies like ones you already know.

> [card] [API reference](https://docs.companyenrich.com/api-reference/v2/post-companies-search.md)
>
> The full request and response specification, with a playground.


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