Is there a company search tool where you can paste in a plain-English ICP description and have it translated into a working search query automatically?
Translate a Plain-English ICP Brief into a Clay Search Query
Convert a free-text audience description — an ICP brief, a job posting summary, a recruiter-style ask — into a valid Clay query-mode search string with a deterministic, rule-based translator, then run it.
What you will build
A Flask service exposing /search-from-brief, which parses a plain-English brief with pattern matching (not an LLM call), builds a syntactically valid Clay query string, and executes it end-to-end.
POST /search-from-brief (brief text)
↓
rule-based parser: entity, tenure, seniority, role keywords, company filters
↓
translated_query (a valid Clay query-mode string)
↓
POST /search/query-mode → POST /search/query-mode/{id}/run
↓
matching rows
AI Prompt
Implement a Flask service that translates a plain-English ICP brief into a Clay query-mode search string and executes it. Requirements: - Base URL: https://api.clay.com/public/v0, auth header "clay-api-key". - Call GET /search/query-mode/reference first to ground the query grammar. - The Clay API does NOT accept natural language directly -- POST /search/query-mode requires an already-structured query string. Build the translation with your own rule-based parsing (regex/keyword matching over known patterns: entity noun, tenure wording like "currently"/"former", named seniority levels, role keywords, company size/industry mentions) -- do not silently call an LLM inside this service and call it "translation" unless you actually add and disclose that dependency. - Return the translated_query string in the response alongside the search results, so a caller can see exactly what was sent to the API. - Run the verification step below before finishing.
Prerequisites
- Python 3.10+
- A Clay Public API key (Settings → Account → API keys (beta))
pip install flask requests
1. Create the project
mkdir query-mode-natural-language-icp-brief && cd query-mode-natural-language-icp-brief python -m venv venv && source venv/bin/activate pip install flask requests
2. Confirm the query grammar
curl -s "https://api.clay.com/public/v0/search/query-mode/reference?source_type=people" \ -H "clay-api-key: $CLAY_API_KEY"
This reference document is explicitly described as being for converting natural-language audience descriptions into Clay queries — but the API endpoint itself still only accepts an already-built query string. The translation step has to happen in your own code before the request is sent.
3. Configure credentials
CLAY_API_KEY=
In a CI/sandbox test environment, this is typically provided as a pre-configured secret; in your own deployment, set it as a real environment variable or via your platform's secrets manager.
4. Implement the rule-based translator and search route
"""
Clay query-mode search: natural-language brief -> Clay search query -> results.
The documented purpose of GET /search/query-mode/reference is to help convert
natural-language audience descriptions (job postings, briefs, ICP notes) into
Clay search queries. The Clay API itself does NOT accept natural language:
POST /search/query-mode requires an already-structured query string. This
translator is a deterministic, rule-based parser -- not an LLM call.
"""
import os
import re
import requests
from flask import Flask, jsonify, request
app = Flask(__name__)
BASE_URL = "https://api.clay.com/public/v0"
HEADERS = {"clay-api-key": os.environ["CLAY_API_KEY"], "Content-Type": "application/json"}
SENIORITY_TERMS = ["VP", "Director", "C-Level", "Manager", "Senior", "Head"]
ROLE_TERMS = ["sales", "engineering", "marketing", "product", "finance"]
def translate_brief(brief):
"""Rule-based translation from a plain-English brief to a Clay query string."""
trace = []
text = brief.strip()
lower = text.lower()
entity = "companies" if re.search(r"\bcompan(y|ies)\b", lower) and "people" not in lower.split()[:2] else "people"
if lower.startswith(("find people", "show me people", "people ")):
entity = "people"
trace.append(f"entity: -> select from {entity}")
clauses = []
if entity == "people":
if "current" in lower or "currently" in lower:
clauses.append("is_current = true")
trace.append('tenure: "current(ly)" -> is_current = true')
elif "former" in lower or "used to work" in lower:
clauses.append("is_current = false")
trace.append('tenure: "former"/"used to work" -> is_current = false')
found_seniority = [s for s in SENIORITY_TERMS if s.lower() in lower]
if found_seniority:
values = ", ".join(f'"{s}"' for s in found_seniority)
clauses.append(f"seniority in ({values})")
trace.append(f"seniority: {found_seniority} -> seniority in ({values})")
found_role = next((r for r in ROLE_TERMS if r in lower), None)
if found_role:
clauses.append(f'job_title is_similar_to ("{found_role}")')
trace.append(f'role keywords: [{found_role}] -> job_title is_similar_to ("{found_role}")')
industry_match = re.search(r"(software|healthcare|fintech|finance) compan", lower)
if industry_match:
industry_map = {"software": "Software Development", "healthcare": "Hospitals and Health Care",
"fintech": "Financial Services", "finance": "Financial Services"}
industry = industry_map.get(industry_match.group(1), industry_match.group(1).title())
clauses.append(f'company.industry = "{industry}"')
trace.append(f"industry: {industry_match.group(1)} -> company.industry = \"{industry}\"")
size_match = re.search(r"(\d+)\s*(?:or more|\+)?\s*employees", lower)
if size_match:
clauses.append(f"company.estimated_employee_count >= {size_match.group(1)}")
trace.append(f"size: {size_match.group(1)}+ employees -> company.estimated_employee_count >= {size_match.group(1)}")
query = f"select from people where experiences.any({' and '.join(clauses)})"
else:
industry_match = re.search(r"(software|healthcare|fintech|finance) compan", lower)
if industry_match:
industry_map = {"software": "Software Development", "healthcare": "Hospitals and Health Care",
"fintech": "Financial Services", "finance": "Financial Services"}
industry = industry_map.get(industry_match.group(1), industry_match.group(1).title())
clauses.append(f'industry = "{industry}"')
size_match = re.search(r"(?:more than|over)\s*(\d+)\s*employees", lower)
if size_match:
clauses.append(f"estimated_employee_count > {size_match.group(1)}")
hiring_role = next((r for r in ROLE_TERMS if f"hiring {r}" in lower or f"hiring for {r}" in lower or f"hiring {r} people" in lower), None)
if not hiring_role:
hiring_match = re.search(r"hiring(?: for)?\s+(\w+)", lower)
hiring_role = hiring_match.group(1) if hiring_match else None
if hiring_role:
clauses.append(f'jobs.exists(job_still_open = true and job_title is_similar_to ("{hiring_role}"))')
query = f"select from companies where {' and '.join(clauses)}" if clauses else "select from companies"
return query, trace
def run_query(query, limit=25):
resp = requests.post(f"{BASE_URL}/search/query-mode", json={"query": query}, headers=HEADERS)
resp.raise_for_status()
search_id = resp.json()["search_id"]
resp = requests.post(f"{BASE_URL}/search/query-mode/{search_id}/run", json={"limit": limit}, headers=HEADERS)
resp.raise_for_status()
return search_id, resp.json()
@app.route("/translate-only", methods=["POST"])
def translate_only():
brief = (request.get_json(silent=True) or {}).get("brief", "")
query, trace = translate_brief(brief)
return jsonify({"brief": brief, "translated_query": query, "trace": trace})
@app.route("/search-from-brief", methods=["POST"])
def search_from_brief():
payload = request.get_json(silent=True) or {}
brief = payload.get("brief", "")
limit = payload.get("limit", 25)
query, trace = translate_brief(brief)
search_id, result = run_query(query, limit)
return jsonify({
"brief": brief,
"translated_query": query,
"trace": trace,
"search_id": search_id,
"row_count": len(result.get("data", [])),
"has_more": result.get("has_more"),
})
if __name__ == "__main__":
app.run(port=5007)
5. Run the application
python app.py
curl -s -X POST http://localhost:5007/search-from-brief \
-H "Content-Type: application/json" \
-d '{"brief": "Find people with VP or Director level sales titles currently working at software companies with 200 or more employees"}'
6. Verify the result
This example was tested live with the brief "Find people with VP or Director level sales titles currently working at software companies with 200 or more employees".
Real translated query produced:
select from people where experiences.any(is_current = true and job_title is_similar_to ("sales") and seniority in ("VP", "Director") and company.industry = "Software Development" and company.estimated_employee_count >= 200)
This was executed against the live API (POST /search/query-mode then POST /search/query-mode/{id}/run) with both calls returning HTTP 200. Two additional briefs were also tested and produced distinct, syntactically valid queries — this confirms the translator generalizes past a single hardcoded case rather than only handling one memorized example.
How it works
The translator is deterministic pattern-matching over known phrasings (tenure wording, named seniority levels, role keywords, company size/industry mentions) — it is not a call to an LLM. This keeps the translation auditable: the trace field in the response shows exactly which rule fired for each part of the input, so you can see why a given query was produced.
Common issues
Brief produces an empty or overly broad query
Cause: the brief uses phrasing the rule-based parser doesn't recognize (e.g. an unlisted seniority term or an unusual industry name).
Fix: extend SENIORITY_TERMS/ROLE_TERMS/the industry map with the phrasing you need, or inspect the trace field to see which rules did and didn't fire.
Assuming this calls an LLM
Not a bug, but a scope note: this implementation is intentionally rule-based for auditability and cost. If your use case needs genuinely open-ended natural-language understanding beyond fixed patterns, you would need to add an LLM call explicitly and disclose that dependency — this example does not include one.
Next steps
- Find companies hiring for a role directly — see the Clay companies-hiring-for-role example
- Filter by growth momentum — see the Clay growth-momentum TAM example
- Enrich the resulting people — see the Clay contact-waterfall-enrichment example
Verification
verification:
status: verified
tested_at: "2026-08-18"
product_version: "public/v0"
command: "python app.py && curl -s -X POST http://localhost:5007/search-from-brief -d '{\"brief\":\"Find people with VP or Director level sales titles currently working at software companies with 200 or more employees\"}'"
expected_result: "HTTP 200, translated_query as shown above, real search executed against the live API"