> ## 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.
# Build a search filter
> Describe what you want using conditions, groups, and operators — the filter object shared by every Contact Search and Company Search endpoint.
export const RBCardGroup = ({cols = 3, children}) =>
}
{tag && {tag}}
;
};
Every Contact Search and Company Search endpoint takes the same `filter` object. Write it once and send it to `count`, `preview`, `insights`, or `exports` on either surface without changes.
A filter is **plain JSON** — a nested tree of objects with a `type` field. It is not GraphQL, and there is no query language to learn or GraphQL endpoint to call. Build it with whatever your language uses for JSON.
The one difference is which columns each surface accepts: contact endpoints take person, company, and job fields, while company endpoints take company fields only. See [Search for companies](/api-reference/v2/company-search-overview) for what that rules out. Every column is documented in the [Person-Organization-Insight data dictionary](/docs/data-features/pre-joined-tables/person-organization-insight).
## Start with one condition
A filter is a `group` containing a list of `children`. The simplest one holds a single condition:
```json theme={null}
{
"filter": {
"type": "group",
"op": "AND",
"children": [
{ "type": "condition", "column": "COUNTRY_NAME_PER",
"operator": "eq", "value": "United States" }
]
}
}
```
Use `POST /v2/contact/count` to check the result before adding complexity.
## Combine conditions
Add more entries to `children`. The group's `op` decides how they combine — `AND` requires all of them, `OR` requires any.
```json theme={null}
"children": [
{ "type": "condition", "column": "COUNTRY_NAME_PER",
"operator": "eq", "value": "United States" },
{ "type": "condition", "column": "JOB_LEVEL_PER",
"operator": "in", "valueList": ["VP", "C-Level"] }
]
```
`eq` reads `value`, a single item. `in` reads `valueList`, an array. Sending the wrong one is the most common cause of a `422`.
## Nest groups for mixed logic
To express "in the United States **and** (software **or** financial services)", nest a group inside a group:
```json theme={null}
"children": [
{ "type": "condition", "column": "COUNTRY_NAME_PER",
"operator": "eq", "value": "United States" },
{ "type": "group", "op": "OR", "children": [
{ "type": "condition", "column": "INDUSTRY_LINKEDIN_ORG",
"operator": "eq", "value": "Software Development" },
{ "type": "condition", "column": "INDUSTRY_LINKEDIN_ORG",
"operator": "eq", "value": "Financial Services" }
]}
]
```
Set `"negate": true` on any group to exclude everything it matches.
## Add SmartSearch nodes
[SmartSearch](/api-reference/v2/smartsearch) nodes match on meaning rather than characters. They are ordinary children — they sit in the same `children` list as conditions, nest inside groups, and negate the same way.
**Job title** — the role a person holds, however it's worded:
```json theme={null}
{ "type": "semantic", "on": "title",
"text": "runs demand generation for a software company",
"match": "similar" }
```
**Company description** — what a company does:
```json theme={null}
{ "type": "semantic", "on": "company",
"text": "operates cold storage and refrigerated warehousing",
"match": "similar" }
```
**Company look-alike** — companies resembling one you name:
```json theme={null}
{ "type": "lookalike", "domain": "northwind.com", "match": "similar" }
```
All three take the same four `match` presets — `exact`, `similar`, `related`, `broad` — or a raw `maxDistance` if you'd rather set your own threshold. Never both.
## Node reference
Four node types, told apart by `type`. Every node also accepts `joinWithPrevious` (`AND` or `OR`) to control how it binds to the preceding sibling, and an optional `id` of your own for round-tripping state from an interface.
| `type` | Required | Optional |
| ----------- | ---------------------------------- | ------------------------------ |
| `group` | `children` | `op` (`AND` default), `negate` |
| `condition` | `column`, `operator` | `value` or `valueList` |
| `semantic` | `on` (`title` / `company`), `text` | `match` or `maxDistance` |
| `lookalike` | `domain` or `rbidOrg` | `match` or `maxDistance` |
## A filter using everything
Conditions, a nested `OR`, two SmartSearch types, and a negated exclusion — in one tree:
```json theme={null}
{
"filter": {
"type": "group",
"op": "AND",
"children": [
{ "type": "condition", "column": "COUNTRY_NAME_PER",
"operator": "eq", "value": "United States" },
{ "type": "condition", "column": "JOB_LEVEL_PER",
"operator": "in", "valueList": ["VP", "C-Level"] },
{ "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": "semantic", "on": "company",
"text": "sells software to mid-market retailers", "match": "related" },
{ "type": "group", "negate": true, "children": [
{ "type": "lookalike", "domain": "competitor.com", "match": "similar" }
]}
]
}
}
```
Read it as: in the US, **and** VP or C-Level, **and** (demand gen **or** marketing ops), **and** at a company selling software to mid-market retailers, **and not** at a company resembling `competitor.com`.
See [SmartSearch](/api-reference/v2/smartsearch) for how the presets are calibrated per target and more worked combinations.
## Operator reference
| Operator | Matches | Reads |
| ------------------------ | ------------------------------------------- | ----------- |
| `eq`, `ne` | Equal to / not equal to a value | `value` |
| `in`, `notIn` | Is / is not one of a list | `valueList` |
| `contains` | Text appears anywhere in the field | `value` |
| `startsWith`, `endsWith` | Text at the start or end of the field | `value` |
| `gt`, `gte`, `lt`, `lte` | Greater or less than, for numbers and dates | `value` |
| `isNull`, `isNotNull` | Field is empty / has a value | neither |
Every node also accepts `joinWithPrevious` (`AND` or `OR`) to control how it binds to the preceding sibling, and an optional `id` of your own for round-tripping state from an interface.
## Find available columns and values
`GET /v2/contact/columns` returns every column, what it holds, and which ones offer a fixed set of values. Add `?include=values` to receive those value lists in the same response. `GET /v2/contact/company/columns` does the same for the company surface, listing company fields only.
```bash theme={null}
curl "https://api.revenuebase.ai/v2/contact/columns?include=values" \
-H "x-key: {YOUR_API_KEY}"
```
| Field | What it means |
| ---------------- | ----------------------------------------------------------------------------------- |
| `columnName` | The name to use in a filter |
| `humanName` | Display name for an interface |
| `valueKind` | `string`, `number`, `date`, or `boolean` |
| `grain` | `person`, `org`, or `pao` — matching the column suffix |
| `multiselect` | Whether the column has a fixed set of values |
| `distinctValues` | Every value the column holds. Present with `?include=values` on multiselect columns |
| `valueLimit` | Maximum values this column will return |
Request the catalog once at startup and cache it. Building filter inputs from `distinctValues` avoids searches that silently match nothing because a value was spelled differently than stored.
`GET /v2/contact/columns/{column}/values` returns values for a single multiselect column, with an optional `search` parameter. Open-ended columns — job title, company name, email address — return `400`; filter those with `contains` instead.
## Filter limits
| Limit | Value | Exceeding it |
| ------------------------------------------------------ | -------------- | ------------ |
| Conditions per filter | 25 | `422` |
| Nesting depth | 8 | `422` |
| Values in one `in` or `notIn` list | 50,000 | `422` |
| Values across every `in` / `notIn` list in one request | 50,000 | `422` |
| Job title SmartSearch nodes | 3 | `422` |
| Company description SmartSearch nodes | 3 | `422` |
| Look-alike SmartSearch nodes | 10 | `422` |
| SmartSearch `text` length | 300 characters | `422` |
## Handle filter errors
A rejected filter returns `422`. As with every validation error across the API, `detail` is an array identifying each problem, and `code` names the rule that was broken:
```json theme={null}
{
"title": "Invalid filter",
"status": 422,
"detail": [
{
"loc": ["body", "filter", "children", 2],
"msg": "Filter has too many conditions (31; max 25).",
"type": "value_error.invalid_filter"
}
],
"code": "INVALID_FILTER",
"request_id": "01J8Z..."
}
```
`loc` points at the part of the filter that failed, and `msg` explains what's wrong. See [Rate limits and error codes](/api-reference/v2/rate-limits) for the shared error format.
| Code | Cause | Fix |
| ------------------- | ------------------------------------------------------------------------- | ---------------------------------------------------- |
| `INVALID_FILTER` | Too many conditions, nested too deep, or an invalid semantic node | Simplify the filter; `detail` names the limit |
| `UNKNOWN_COLUMN` | A `column` value isn't in the catalog | Check the spelling against `GET /v2/contact/columns` |
| `IN_LIST_TOO_LARGE` | One `in` / `notIn` list exceeds 50,000 values, or all of them together do | Split the search into several requests |
Include `request_id` when contacting [support@revenuebase.ai](mailto:support@revenuebase.ai) — it identifies the individual request in our logs.
## Next steps