Skip to main content
GET
/
api
/
leads
/
icp-suggestions
Get ICP lead-search suggestions
curl --request GET \
  --url https://app.puffle.ai/api/leads/icp-suggestions \
  --header 'Authorization: Bearer <token>'
{ "suggestions": [ "VPs of Sales at B2B SaaS companies in Austin", "Founders at seed-stage fintech startups with 1-10 employees", "Heads of Growth at marketplace companies in New York" ] }

​
Overview

Generates three short natural-language lead-search queries customised to the caller’s ICP. The LLM reads user_context, company_context, and market_context from user_profiles, emits 8 diverse suggestions spanning title / seniority / function / location / industry / size / funding, then the server randomly samples 3 — so repeated calls surface different buyer personas. Each suggestion is engineered to map cleanly onto the structured filter vocabulary — feed one directly into POST /api/leads/parse-filters to turn it into a structured filter object, then into POST /api/leads/search. Responses are never cached (Cache-Control: no-store). If the user has no populated context yet, returns { "suggestions": [] } instead of a 5xx.

​
AI agent notes

When to call: the human is brainstorming and wants starter ideas. Do not call in a tight loop — each call spends an LLM token budget.If suggestions is empty: the user has no ICP context yet. The correct fix is onboarding, not a suggestion call — route back to GET /api/onboarding/status.Why three? The endpoint shows three at a time by design — offering 8 dilutes attention. If the human rejects all three, call again to surface a new sample.Downstream chain:
  1. Pick a suggestion (or let the human pick).
  2. POST /api/leads/parse-filters with the suggestion as query — returns structured filters.
  3. POST /api/leads/search with those filters plus the original suggestion as nl_query — kicks off the background search.
See also: Parse filters · Start a search · Agent Playbook.

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Response

Three NL query strings (or an empty array if the user has no context yet).

Random sample of 3 suggestions drawn from a set of 8 generated by the LLM. Server never caches — each call produces a different set.

​
suggestions
string[]
required

Three short (~60 chars) natural-language lead search queries tailored to the user's ICP — e.g. "VP Sales at B2B SaaS companies in Boston". Feed one directly into POST /api/leads/parse-filters to convert into structured filters, then into POST /api/leads/search.