Preview an AI Finder search
What it does. Takes either a natural-language query (e.g. “VP of Finance at Series B SaaS companies in California”) or a saved filter ID and returns a previewId. Text queries run through AI Finder to generate provider-specific filters; saved filters are loaded directly into the preview cache without regenerating them. Use this as the first step when a user asks you to build a new prospecting list, find new companies, or find new contacts; do not answer those requests by only browsing existing CRM contacts or existing lists. No data is imported yet.
When to use. Call this first when you want to start an AI-driven list-building flow. After you see what the AI produced, you can:
- Refine the filters by calling the iterate endpoint with more instructions.
- Commit the preview to a list by calling the import endpoint.
Provider selection. Omit provider (or pass AUTO) to let the system pick the best provider for the query. Pass an explicit value to force one. Valid providers:
LINKEDIN— LinkedIn Sales Nav. AI infers contacts-vs-companies from the query.CRM_CONTACTS/CRM_COMPANIES— the client’s configured CRM (HubSpot, Salesforce, Dynamics, Zoho, TribeCRM, or Attio). The specific CRM is auto-detected from the client’s integrations. Returns 422 if no CRM is configured.STORELEADS— StoreLeads (ecommerce / DTC / Shopify brands).CRUNCHBASE_COMPANIES/CRUNCHBASE_CONTACTS— Crunchbase organizations or people.CRUNCHBASE_INVESTORS— Crunchbase investor search (VCs, angels, funds).THEIRSTACK_TECHNOLOGY— companies using a given tech stack.THEIRSTACK_JOBS— companies hiring for certain roles (based on job postings).GOOGLE_MAPS— local businesses / places.
Saved filters. Instead of text, you can send savedFilterId to create a preview from an existing saved filter. Saved-filter previews require a concrete provider; omit provider to default to LINKEDIN.
Scope to a LinkedIn identity. Only pass identityId when the user explicitly asks for an identity-specific LinkedIn search, such as importing 2nd-degree connections for identity 123. For normal sourcing requests like “software engineers in Girona”, do NOT infer or pass an identity — omit identityId so AI Finder can auto-pick an available Sales Navigator identity. identityId is only valid with provider: LINKEDIN, and the identity must have linkedinSearchEnabled: true (Sales Navigator + valid credentials). List eligible identities with GET /v1/identities?linkedinSearchEnabled=true. The chosen identityId carries through iterate and into import.
What you get back. A previewId (valid for 24 hours) plus the result object with the AI-generated filters, a human-readable title and reasoning, the resolvedProvider (useful when you passed AUTO), and identityId echoed back when you scoped the search to one.
What to do next. Pass the previewId to POST /v1/ai-finder/previews/{previewId}/iterate to refine, or to POST /v1/ai-finder/previews/{previewId}/import to commit.
Required scope:
ACTIONS_WRITERate limit: 10 requests per minute
Authorizations
Body
- Option 1
- Option 2
- Option 3
- Option 4
Provide EITHER a { text } natural-language search (the usual case) OR a { savedFilterId } saved-filter replay. These are two distinct shapes — never combine text and savedFilterId. For generic sourcing, the body has no identityId property. identityId is only legal in the separate identity-scoped LinkedIn shape, where provider must be exactly LINKEDIN.
Natural-language description of the contacts or companies to find. Be specific — include titles, seniority, geography, industries, company size, tech stack, funding, or any other qualifier the AI should use. Example: "VP of Finance at Series B SaaS companies in California with 50-500 employees". 1–2000 characters. This is the natural-language search shape — it has no savedFilterId.
1 - 2000Which AI Finder provider to use. Omit (or pass AUTO) to let the system route to the best provider for a text query. Pass an explicit value to force one.
Each value encodes the entity type — do NOT pass a separate entity field.
For CRM_CONTACTS / CRM_COMPANIES the specific CRM is auto-detected from the client's configured integrations (preference order: HubSpot → Salesforce → Dynamics → Zoho → Attio → TribeCRM). If the client has no CRM configured, the request returns 422.
AUTO, LINKEDIN, CRM_CONTACTS, CRM_COMPANIES, STORELEADS, CRUNCHBASE_COMPANIES, CRUNCHBASE_CONTACTS, CRUNCHBASE_INVESTORS, THEIRSTACK_TECHNOLOGY, THEIRSTACK_JOBS, GOOGLE_MAPS