Build a search filter

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 for what that rules out. Every column is documented in the Person-Organization-Insight data dictionary.

Start with one condition

A filter is a group containing a list of children. The simplest one holds a single condition:

{
  "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.

"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:

"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 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:

{ "type": "semantic", "on": "title",
  "text": "runs demand generation for a software company",
  "match": "similar" }

Company description — what a company does:

{ "type": "semantic", "on": "company",
  "text": "operates cold storage and refrigerated warehousing",
  "match": "similar" }

Company look-alike — companies resembling one you name:

{ "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:

{
  "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 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.

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:

{
  "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 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 — it identifies the individual request in our logs.

Getting Started

Contact API

Contact Endpoints

Company Endpoints

Email API

Utilities

Build a search filter

Start with one condition

Combine conditions

Nest groups for mixed logic

Add SmartSearch nodes

Node reference

A filter using everything

Operator reference

Find available columns and values

Filter limits

Handle filter errors

Next steps

​Start with one condition

​Combine conditions

​Nest groups for mixed logic

​Add SmartSearch nodes

​Node reference

​A filter using everything

​Operator reference

​Find available columns and values

​Filter limits

​Handle filter errors

​Next steps

Start with one condition

Combine conditions

Nest groups for mixed logic

Add SmartSearch nodes

Node reference

A filter using everything

Operator reference

Find available columns and values

Filter limits

Handle filter errors

Next steps