# Search filters and credits

> Look up supported filters, matching rules, pagination, and shared credit costs.

REST and MCP use the same directory search semantics. This reference describes the shared search contract at `https://app.vencavo.com`. Use an authorized workspace API key or MCP connection.

## Query shape

REST search accepts a JSON object at `/api/v1/directory/companies/search` or `/api/v1/directory/people/search`. MCP `search_companies` and `search_people` wrap that object in `query` alongside `operationKey`.

MCP requires `query`, `industry`, `country`, `seniority`, `companyId`, `limit`, and `cursor` inside the query object. Empty strings mean no criterion. `filters` and `sort` are optional. Read the current tool schema before calling.

`query` is a case-insensitive literal substring, not natural-language or Boolean syntax. For people, it searches names, titles, and company names together. The `title` filter searches only titles. Legacy `country` accepts a two-letter ISO code and applies to the searched entity. Legacy `seniority` accepts `c-suite`, `vp`, `director`, `manager`, or `individual`.

Positive page limits range from 1 to 50. Omitted REST limits and zero limits become 20. Start with 10. Text criteria allow at most 200 characters. Cursors allow at most 1,024 bytes.

## Structured filters

Each filter has `field`, `include`, and `exclude`. Each field appears once, with at most 14 fields and 20 values per include or exclude array. Values contain 1–200 characters. Values normalize to lowercase and deduplicate. A value cannot appear in both arrays.

| Field                           | Applies to | Matching                                                                                         |
| ------------------------------- | ---------- | ------------------------------------------------------------------------------------------------ |
| `companyName`                   | Both       | Case-insensitive company-name substring.                                                         |
| `domain`                        | Both       | Exact company domain. No URL or subdomain expansion.                                             |
| `industry`                      | Both       | Company industry from the current source vocabulary.                                             |
| `companyCountry`, `companyCity` | Both       | Company location. Country accepts source names or ISO codes. City is exact.                      |
| `employeeSize`                  | Both       | Source employee band.                                                                            |
| `title`                         | People     | Case-insensitive literal title substring.                                                        |
| `seniority`                     | People     | `c-suite`, `vp`, `director`, `manager`, or `individual`.                                         |
| `personCountry`, `personCity`   | People     | Person location. Country accepts source names or ISO codes. City is exact.                       |
| `function`                      | People     | Exact department value from the current source vocabulary.                                       |
| `emailAvailable`                | People     | String `true` or `false` for eligible historical work-email evidence.                            |
| `phoneAvailable`                | People     | String `true` or `false` for eligible historical direct or mobile evidence. Boardlines excluded. |

Employee bands are `0-1`, `2-10`, `11-50`, `51-200`, `201-500`, `501-1000`, `1001-5000`, `5001-10000`, and `10000+`. Legacy `1-10` combines the first two bands. Legacy `5001+` combines the final two. Bands never imply a precise headcount.

MCP `get_search_filters` with `kind: "company"` or `"person"` returns current vocabulary. Filters describe the configured source. Availability filters reveal no protected contact values and make no current-deliverability guarantee.

## Boolean and unsupported criteria

Included values within a field combine with OR. Different fields combine with AND. Exclusions remove matching records.

For India OR United States, use `{"field":"personCountry","include":["IN","US"]}`. Adding `{"field":"personCity","exclude":["Mumbai"]}` also excludes Mumbai.

`{"field":"title","include":["sales","director"]}` means sales OR director. A literal `sales director` phrase does not match both words in arbitrary order. Arbitrary title-word AND and Boolean text syntax are unsupported.

Technology, buying intent, revenue, funding, hiring, and current employment verification are unsupported filters. Obtain approval before relaxing a requested criterion or filtering a bounded paid page locally. An AI client's interpretation does not add a server capability.

## Pages and retries

Each intentional page needs a new operation key. REST sends `Idempotency-Key`; MCP sends `operationKey`. A UUID is suitable. REST accepts 8–128 ASCII letters, digits, dots, underscores, colons, or hyphens.

An exact retry preserves the key, credential, and complete arguments. A changed request with the same key returns `idempotency_conflict`. Lost responses do not authorize a new key.

For a new continuation page, use `nextCursor` as `cursor` with the same criteria, limit, and order, and a new operation key. An empty `nextCursor` in the response means there is no further page. Changed criteria or order starts a new search with an empty cursor. Cursors bind to the source release. Stop at the approved page budget.

### Return to a page in the app

The app retains up to 20 confirmed page intents while that scoped view remains in memory. **Previous page** and a previously visited **Next page** send the original key and complete input to the server. They do not create another paid operation or display a cached historical row set. Current access, source release, and visibility checks still apply. A new continuation page costs its normal page credit.

A temporary return failure keeps the current completed page visible and can retry the same receipt. Access, source, or replay-conflict denials clear the results and history. An expired receipt blocks that return and never becomes a new search automatically. Choose a new intentional search and its normal credit cost if you need a fresh result. The oldest retained page has no earlier-page action once older intents leave the 20-page window.

Editing draft criteria disables page navigation until you restore or apply them. Applying a successful fresh search resets the history. Opening saved or recent criteria clears the old result without running a search. Reloading discards completed page history; an uncertain operation can still be recovered explicitly through the existing pending-search recovery.

## Credit costs

| Operation                                                    | Workspace credits          |
| ------------------------------------------------------------ | -------------------------- |
| Nonempty search page                                         | 1, including a small page. |
| Empty or failed search                                       | 0.                         |
| Company or person profile                                    | 0.                         |
| Availability quote, saved references, lists, and usage reads | 0.                         |
| Work-email unlock                                            | 1 for new evidence.        |
| Direct or mobile phone unlock                                | 5 for new evidence.        |
| Same-evidence unlock already held by the workspace           | 0.                         |

Unlocks require `channels:write`, a current availability quote, explicit approval of the evidence version and maximum cost, and an operation key. A source update requires new approval. Credits are shared across REST, MCP, and workspace users.

Receipt bodies expire after 30 days. An expired receipt cannot be replayed. Source changes can also prevent replay. Obtain approval for a new intentional paid operation rather than replacing its key automatically. Read [error recovery](/developers/errors/) for the exact response.

## Workspace plans

See [plans and credit prices](/pricing/) for monthly workspace subscriptions and credit packs. Monthly credits expire at the end of the billing period. A credit pack is valid for 12 months. When account links are enabled, choose a plan or credit pack on the pricing page to continue to workspace billing. Otherwise, use the contact path to discuss access. Only a verified payment grants paid credits.

## Find people across selected companies

People search accepts a structured `companyId` filter with 1–50 exact company IDs in `include` and an empty `exclude`. This is a snapshot from current results. Leave the legacy top-level `companyId` empty when using it. The selected company IDs combine with OR; job titles, company geography and other criteria combine with AND. A selection is not live saved-list membership, and selecting one list page does not select the entire list.

For example, select available companies in a company list, choose **Find people**, then add a title filter for **Product Manager**. To search the broader market directly, combine `companyCountry` including `IN` with chosen industries and a title filter. “Tech-first” is not a source classification; review which industries match your market. Title includes are literal substring alternatives.

The company selection survives saved searches, pagination and exact-request recovery. Older clients reject the unfamiliar filter field instead of discarding it; reconnect or reload an older client before using the selection. Changing it requires a new search and operation key. Nonempty pages retain the normal one-credit cost. Opening the search with company filters does not spend credits. The ClickHouse deployment requires its configured people index for this criterion; if unavailable, it fails without charging instead of dropping the selection or scanning broadly.

Save matching people into a people list. Company and people lists retain their own record types. Email-sequence delivery is outside this service. Contact access requires a separate explicit quote and unlock; an available email is not consent to send outreach.

## Country and filter choices

Country pickers use supported countries and territories from Unicode CLDR 48.2. New choices use a lowercase country code and the existing search aliases. This is a choice list, not a claim of records in every location. Saved literal names keep their existing exact meaning.

Company country and city describe company context; person country and city describe the person. Company industry and job function are exact recorded values. Job-title and company-name filters match contained text. City and domain filters match exact recorded values, ignoring case. An available channel means retained eligible evidence, not verified current deliverability.

Industry and job-function suggestions are capped independently at 1,000 values each. The catalog reports additional values through `truncated`; exact text entry is available for these fields. Unsupported country strings and source placeholders do not appear as ordinary country choices.