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 for the exact response.
Workspace plans
See plans and credit prices 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.