> ## Documentation Index
> Fetch the complete documentation index at: https://docs.revenuebase.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Search by meaning with SmartSearch
> Match job titles, company descriptions, and look-alike companies on meaning rather than exact text, using four named presets.
export const RBCardGroup = ({cols = 3, children}) =>
}
{tag && {tag}}
;
};
SmartSearch matches on **meaning** rather than characters. You describe what you're looking for in plain language, and we find it however it happens to be worded.
There are three, and the important part is that you can combine them.
## Why not keywords and booleans?
Keyword and boolean filters match characters. That works when your target has one spelling, and fails the moment it doesn't — which is most of the time in B2B data.
Say you want people who run demand generation:
| Approach | What happens |
| --------------------------------------------- | -------------------------------------------------------- |
| `JOB_TITLE_PER contains "demand generation"` | Misses Head of Growth, VP Marketing, Directeur Marketing |
| `JOB_TITLE_PER in [20 titles you thought of]` | Misses the 40 you didn't |
| `JOB_TITLE_PER contains "marketing"` | Catches Marketing Interns and Marketing Assistants |
| **Job Title SmartSearch** | Catches the role, skips the intern |
The same failure repeats on the company side. `Financial Services` covers a retail bank and a crypto exchange. A keyword search for "logistics" misses a freight forwarder that calls itself a supply chain partner.
Booleans aren't wrong — they're exact, fast, and you should keep using them for things that genuinely are exact, like country, headcount band, or seniority. SmartSearch is for the parts of a query that are fuzzy by nature: **what a person does** and **what a company does**.
Use both. A good filter is usually SmartSearch for role and business, plus ordinary conditions for geography, size, and seniority. See [Search Filters](/api-reference/v2/search-filters).
## Each one on its own
Every SmartSearch is a single node in a filter. Here is each one doing its own job, before any combining.
### Company Description
Find companies by what they actually do, however they word it:
```json theme={null}
{ "type": "semantic", "on": "company",
"text": "third-party logistics and freight forwarding", "match": "similar" }
```
Catches a freight forwarder that calls itself a supply chain partner. Detail: [Company Description](/api-reference/v2/smartsearch-company-description).
### Job Title
Find people by the role they actually hold, whatever it happens to be called:
```json theme={null}
{ "type": "semantic", "on": "title",
"text": "runs demand generation", "match": "similar" }
```
Catches Head of Growth and VP Marketing, and skips the Marketing Intern. Detail: [Job Title](/api-reference/v2/smartsearch-job-title).
### Company Look-alike
Find companies resembling one you name, by domain:
```json theme={null}
{ "type": "lookalike", "domain": "ourbestcustomer.com", "match": "similar" }
```
No industry code and no keyword list. Detail: [Company Look-alike](/api-reference/v2/smartsearch-lookalike).
Each of these is a complete filter on its own — send any one of them to `/count` or `/preview` and it works. The rest of this page is about what happens when you put them together.
## Combining them is the point
Any one semantic search is useful. Combining several in a single query is what nothing else in this market does.
You can put up to **three** job title searches, **three** company description searches, and **ten** look-alikes in one filter, nest them in `AND` / `OR` groups, and negate any of them — alongside ordinary conditions. Every combination below is one request.
### Two descriptions, OR'd
A market that doesn't reduce to one sentence:
```json theme={null}
{ "type": "group", "op": "OR", "children": [
{ "type": "semantic", "on": "company",
"text": "third-party logistics and freight forwarding", "match": "similar" },
{ "type": "semantic", "on": "company",
"text": "customs brokerage and trade compliance services", "match": "similar" }
]}
```
### A look-alike plus a job title
"People who run security at companies like our best customer" — no industry code, no title list:
```json theme={null}
"children": [
{ "type": "lookalike", "domain": "ourbestcustomer.com", "match": "similar" },
{ "type": "semantic", "on": "title",
"text": "owns information security", "match": "similar" }
]
```
### Descriptions and titles together
"Ops leaders at cold chain companies":
```json theme={null}
"children": [
{ "type": "semantic", "on": "company",
"text": "operates cold storage and refrigerated warehousing", "match": "similar" },
{ "type": "group", "op": "OR", "children": [
{ "type": "semantic", "on": "title",
"text": "runs warehouse operations", "match": "similar" },
{ "type": "semantic", "on": "title",
"text": "leads supply chain", "match": "similar" }
]}
]
```
## Worked use cases
You closed ten great deals and want more like them. You don't have to work out what they have in common.
```json theme={null}
{ "type": "group", "op": "OR", "children": [
{ "type": "lookalike", "domain": "customer-one.com", "match": "similar" },
{ "type": "lookalike", "domain": "customer-two.com", "match": "similar" },
{ "type": "lookalike", "domain": "customer-three.com", "match": "similar" }
]}
```
Send it to `POST /v2/contact/company/count` for the account list, or add a job title node and send it to `POST /v2/contact/count` for the people to call.
The industry taxonomy has no code for what you sell into. Describe it instead, at `related` to see the shape of the market:
```json theme={null}
{ "type": "semantic", "on": "company",
"text": "manages clinical trials for pharmaceutical sponsors",
"match": "related" }
```
Preview with `"includeScores": true`, see where the results stop being right, then tighten to `similar` or `exact` before you export.
Three roles that all touch the same purchase, each its own node:
```json theme={null}
{ "type": "group", "op": "OR", "children": [
{ "type": "semantic", "on": "title", "text": "owns information security", "match": "similar" },
{ "type": "semantic", "on": "title", "text": "runs IT infrastructure", "match": "similar" },
{ "type": "semantic", "on": "title", "text": "manages vendor risk", "match": "similar" }
]}
```
Everyone like our customers, minus anyone resembling the incumbent we never beat:
```json theme={null}
"children": [
{ "type": "lookalike", "domain": "ourbestcustomer.com", "match": "similar" },
{ "type": "group", "negate": true, "children": [
{ "type": "lookalike", "domain": "incumbent.com", "match": "similar" }
]}
]
```
## The full combination
Everything at once: US-based, senior demand gen and marketing ops people, at companies resembling any of five accounts, excluding anyone at a company like a competitor.
```json theme={null}
{
"filter": {
"type": "group",
"op": "AND",
"children": [
{ "type": "condition", "column": "COUNTRY_NAME_PER",
"operator": "eq", "value": "United States" },
{ "type": "group", "op": "OR", "children": [
{ "type": "semantic", "on": "title",
"text": "runs demand generation", "match": "similar" },
{ "type": "semantic", "on": "title",
"text": "leads marketing operations", "match": "similar" }
]},
{ "type": "group", "op": "OR", "children": [
{ "type": "lookalike", "domain": "northwind.com", "match": "similar" },
{ "type": "lookalike", "domain": "acmecorp.com", "match": "similar" },
{ "type": "lookalike", "domain": "globex.io", "match": "similar" },
{ "type": "lookalike", "domain": "initech.com", "match": "similar" },
{ "type": "lookalike", "domain": "umbrella-hq.com", "match": "similar" }
]},
{ "type": "group", "negate": true, "children": [
{ "type": "lookalike", "domain": "competitor.com", "match": "similar" }
]}
]
}
}
```
Three things are doing the work:
* **The `OR` group of five look-alikes** is an "any of these". Put look-alikes in an `AND` group and a company must resemble all five at once, which almost nothing does.
* **The negated group** is how you exclude. There is no "not in" look-alike node.
* **Two title nodes joined by `OR`.** One node holding several roles collapses to a single role internally and silently matches only that one.
Drop the title group and send the rest to `POST /v2/contact/company/count` for the same targeting at company grain.
## One vocabulary for all three
Every SmartSearch takes the same four presets. Send `match` and the server owns the number, so "Similar" means the same measured thing in your app, in ours, and in a partner's.
| `match` | Label | What you get |
| --------- | ------- | ------------------------------------------------------------------------------ |
| `exact` | Exact | Essentially the same thing. Different wording and other languages still match. |
| `similar` | Similar | The same underlying thing, with some variation. **Recommended default.** |
| `related` | Related | Adjacent — same family, looser fit. |
| `broad` | Broad | Explore the neighbourhood. Expect to review results. |
Presets are **cumulative**: each is a similarity floor, so `broad` returns everything `related` would plus a looser band beneath it. Widening never drops a result you already had.
### Calibrated per target
RevenueBase calibrates these floors against judged benchmarks. They differ per target because the three vector spaces are not comparable — **read down a column, never across**.
| `match` | Job title | Company description | Look-alike |
| --------- | ------------- | ------------------- | ------------- |
| `exact` | 95–100% · 99% | 60–100% · 86% | 85–100% · 85% |
| `similar` | 85–95% · 91% | 50–60% · 56% | 70–85% · 78% |
| `related` | 75–85% · 82% | 45–50% · 42% | 65–70% · 50% |
| `broad` | 70–75% · 73% | 40–45% · 24% | 60–65% · 34% |
Each cell is *similarity band · on-target rate*. On target is the measured share of matches at that stop that genuinely fit.
Job title holds up well all the way to `broad`. Company description and look-alike fall off sharply past `similar` — company description at `broad` is **24% on target**, meaning roughly three in four results need review. Treat `related` and `broad` on those two as discovery tools, not list-building settings.
### Or set your own thresholds
The presets are a good starting point, not a ceiling. They're the settings we'd pick, calibrated on our benchmarks — but what counts as a good match depends on your market, and you're welcome to find your own.
Send a raw `maxDistance` instead of `match`:
```text theme={null}
maxDistance = 1 − similarity
```
A 78% similarity floor is `"maxDistance": 0.22`. A raw `maxDistance` means exactly what it says and skips the preset calibration entirely.
To find your own numbers, preview with `"includeScores": true`, see where results stop being useful, and set `maxDistance` just below that point:
```json theme={null}
{ "filter": { ... }, "limit": 200, "includeScores": true }
```
Rows come back with `_titleSimilarity` and `_companySimilarity` between 0 and 1, best-match first. Scroll to where quality drops off and you have your threshold.
Send `match` **or** `maxDistance`, never both — sending both is a `422`.
### If you send neither
**Every SmartSearch node defaults to `similar`.** One rule, all three targets — the floor differs because the vector spaces differ, but the promise is the same.
| Target | Default floor | On target |
| ------------------- | -------------- | --------- |
| Job title | 85% similarity | 91% |
| Company description | 50% similarity | 56% |
| Look-alike | 70% similarity | 78% |
Omitting `match` is **exactly** the same search as sending `"match": "similar"` — the same threshold and the same query handling, so the two return the same rows. Send it explicitly when the intent matters to a future reader, and send `exact` or `broad` when you want to move off the recommendation.
### Read the presets at runtime
Fetch the table rather than hardcoding it, so your app picks up any recalibration automatically:
```bash theme={null}
curl https://api.revenuebase.ai/v2/contact/match-presets \
-H "x-key: {YOUR_API_KEY}"
```
## Limits
| Limit | Value |
| ------------------------------------ | -------------- |
| Job title nodes per filter | 3 |
| Company description nodes per filter | 3 |
| Look-alike nodes per filter | 10 |
| `text` length | 300 characters |
Title and company caps are counted separately, so three of each in one filter is fine. Each look-alike node is a full scan of the company vector index, which is why that cap sits where it does.
## Next steps