curl --request POST \
  --url https://openapi.enginy.ai/v1/ai-finder/previews \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "text": "VP Finance at Series B SaaS companies in California"
}
'

{
  "message": "<string>",
  "data": {
    "previewId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "createdAt": "2023-11-07T05:31:56Z",
    "expiresAt": "2023-11-07T05:31:56Z",
    "userInput": "<string>",
    "result": {},
    "droppedFilters": [
      "<string>"
    ],
    "previousPreviewId": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
  }
}

AI Finder

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.

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, and the resolvedProvider (useful when you passed AUTO).

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_WRITE

Rate limit: 10 requests per minute

POST

ai-finder

previews

curl --request POST \
  --url https://openapi.enginy.ai/v1/ai-finder/previews \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "text": "VP Finance at Series B SaaS companies in California"
}
'

{
  "message": "<string>",
  "data": {
    "previewId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "createdAt": "2023-11-07T05:31:56Z",
    "expiresAt": "2023-11-07T05:31:56Z",
    "userInput": "<string>",
    "result": {},
    "droppedFilters": [
      "<string>"
    ],
    "previousPreviewId": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
  }
}

Authorizations

x-api-key

string

header

required

Body

application/json

text

string

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.

Required string length: 1 - 2000

savedFilterId

integer

Optional saved filter ID to load directly into a preview instead of generating filters from raw text. Use this with a concrete provider value (or omit provider to default to LINKEDIN).

provider

enum<string>

Which 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.

Value	Target	Entity
`AUTO`	System picks based on the text query	inferred
`LINKEDIN`	LinkedIn Sales Nav	inferred from query
`CRM_CONTACTS`	Client's configured CRM (HubSpot, Salesforce, Dynamics, Zoho, TribeCRM, or Attio)	CONTACT
`CRM_COMPANIES`	Client's configured CRM	COMPANY
`STORELEADS`	StoreLeads (ecommerce, DTC, Shopify, brands)	COMPANY
`CRUNCHBASE_COMPANIES`	Crunchbase organizations, startups, funds	COMPANY
`CRUNCHBASE_CONTACTS`	Crunchbase people (founders, execs, board members)	CONTACT
`CRUNCHBASE_INVESTORS`	Crunchbase investors (VCs, angels, funds)	CONTACT
`THEIRSTACK_TECHNOLOGY`	Companies using a given tech stack	COMPANY
`THEIRSTACK_JOBS`	Companies hiring for certain roles	COMPANY
`GOOGLE_MAPS`	Local businesses, restaurants, clinics, stores	COMPANY

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.

When using savedFilterId, pass the provider that owns that saved filter. AUTO is only valid for raw text searches.

Available options:

AUTO,

LINKEDIN,

CRM_CONTACTS,

CRM_COMPANIES,

STORELEADS,

CRUNCHBASE_COMPANIES,

CRUNCHBASE_CONTACTS,

CRUNCHBASE_INVESTORS,

THEIRSTACK_TECHNOLOGY,

THEIRSTACK_JOBS,

GOOGLE_MAPS

Response

Preview generated

status

enum<string>

required

Available options:

success

message

string

required

data

object

required

Show child attributes

Update company fields Refine an AI Finder preview

Documentation Index

Authorizations

Body

Response