Skip to main content
POST
/
api
/
leads
/
parse-filters
Parse a natural-language query into filters
curl --request POST \
  --url https://app.puffle.ai/api/leads/parse-filters \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "query": "<string>"
}
'
{ "filters": { "seniority_level": [ "founder" ], "funding": [ "seed", "angel" ], "size": [ "1-10", "11-20", "21-50" ], "contact_city": [ "Austin" ] } }

​
Overview

Runs a single LLM call that maps the caller’s free-form query onto the structured filter vocabulary used by POST /api/leads/search. Returns synchronously. Queries are trimmed and hard-capped at 500 characters. The returned filters object is exactly the shape createLeadSearch expects — you can pass it through verbatim. The optional unsupported string surfaces any intent the LLM had to drop because the filter vocabulary does not express it (for example “actively hiring for AEs”). Always surface unsupported back to the human so they can refine their ask.

​
Example

Input: 
{ "query": "founders at seed-stage startups in Austin" }
Output: 
{
  "filters": {
    "seniority_level": ["founder"],
    "funding": ["seed", "angel"],
    "size": ["1-10", "11-20", "21-50"],
    "contact_city": ["Austin"]
  }
}
Supported filter dimensions:
DimensionValues
Job titlefree text
Seniorityfounder, owner, c_suite, partner, vp, head, director, senior, manager, entry
Functionsales, marketing, engineering, product_management, finance, hr, operations, etc.
Locationcountries, US cities/states
Company industryfree text (e.g. computer software, financial services)
Company keywordsfree text (e.g. SaaS, B2B, AI, marketplace, agency)
Company sizeheadcount bands (1-10, 11-20, 21-50, etc.)
Revenue range100K through 10B
Funding roundseed, angel, series_a, series_b, etc.
Anything outside this vocabulary (“actively hiring”, “growing fast”, “using Salesforce”) will show up under unsupported.

​
AI agent notes

This is the recommended entry point for lead discovery. Prefer parseLeadFilters → createLeadSearch over hand-building filter objects — the LLM handles synonym expansion (e.g. “startup” → size 1-10 / 11-20 / 21-50 plus seed-to-series-A funding) and catches intent the raw vocabulary misses.Downstream chain:
  1. Receive filters and unsupported from this call.
  2. Read unsupported aloud to the human — they may want to refine the query or accept the gap.
  3. Pass filters plus the original nl_query to POST /api/leads/search. Keep nl_query so the server can generate a human-friendly title.
Cost: one LLM call per invocation. Cheap, but still real — do not call it in a loop. Call it once per distinct user query.On 400 "Query must be 500 characters or less": trim the query. This is rare in practice — most natural-language asks sit comfortably under 200 chars.No side effects. Safe to call; no DB writes, no background tasks.
See also: Get ICP suggestions · Start a search · Agent Playbook.

Authorizations

​
Authorization
string
header
required

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

Body

application/json

Free-form natural-language query to be parsed.

​
query
string
required

Natural-language description of the desired audience. Example: "Founders at Series A fintech startups with 11-50 employees in New York". Trimmed server-side; hard-capped at 500 characters.

Required string length: 1 - 500

Response

Parsed filters (and optional unsupported-intent note).

LLM-parsed filters plus any unsupported intent the model had to drop.

​
filters
object
required

Structured filter object with the same field shape consumed by POST /api/leads/search. Only the fields the LLM extracted are present — all are optional. Feed directly into the search endpoint.

​
unsupported
string

Short, natural-language sentence describing any intent the LLM could not map to the structured filter vocabulary (e.g. "the query mentions 'actively hiring for engineers', which is not a supported filter"). Omitted entirely when everything mapped cleanly. Agents should surface this back to the human so they can refine the query.