Find Companies Actively Hiring for a Role with Clay

POST /find-hiring-companies (role, min_employees)
    ↓
build query: select from companies where jobs.exists(...) and estimated_employee_count > N
    ↓
POST /search/query-mode          (create)
    ↓
POST /search/query-mode/{id}/run (page until has_more = false)
    ↓
companies_hiring.csv

Implement a Flask service that finds companies hiring for a specific role
using Clay's query-mode Search API.

Requirements:
- Base URL: https://api.clay.com/public/v0, auth header "clay-api-key".
- Call GET /search/query-mode/reference?source_type=companies first and
  confirm the real query grammar before building any query string.
- The result entity must be "companies" -- "jobs" is NOT a valid standalone
  result entity (the live API rejects "select from jobs where..." with
  HTTP 400 "Only people and companies queries are supported"), even though
  older documentation may suggest otherwise. Express hiring criteria as a
  nested aggregate instead: jobs.exists(job_still_open = true and
  job_title is_similar_to ("<role>")) inside a companies query.
- Combine with a real companies-side filter, e.g.
  estimated_employee_count > N.
- Create the search with POST /search/query-mode, then page with
  POST /search/query-mode/{search_id}/run until has_more is false.
- Export the collected rows to companies_hiring.csv.
- Run the verification step below before finishing.

mkdir query-mode-companies-hiring && cd query-mode-companies-hiring
python -m venv venv && source venv/bin/activate
pip install flask requests

curl -s "https://api.clay.com/public/v0/search/query-mode/reference?source_type=companies" \
  -H "clay-api-key: $CLAY_API_KEY"

CLAY_API_KEY=

"""
Cross-entity company search via Clay's query-mode Search API.

Demonstrates a capability filters-mode search cannot express: a query whose
RESULT entity is companies, but whose FILTER reaches into a different
entity -- the company's own open job postings. Clay models this as a nested
aggregate, jobs.exists(...), inside a companies query.

CONFIRMED (live, negative control): "select from jobs where ..." as a
standalone top-level query is REJECTED with HTTP 400 "Only people and
companies queries are supported." jobs must be nested via jobs.exists()/
jobs.any() inside a people or companies query -- never used as the result
entity itself.
"""

import csv
import os

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"}


def build_query(role, min_employees):
    return (
        f'select from companies where jobs.exists(job_still_open = true and '
        f'job_title is_similar_to ("{role}")) and estimated_employee_count > {min_employees}'
    )


def guard_query(query):
    """Reject the known-broken pattern before sending it to the API."""
    problems = []
    if query.strip().lower().startswith("select from jobs"):
        problems.append("jobs cannot be the result entity -- nest it via jobs.exists() inside a companies query")
    return problems


def create_search(query):
    resp = requests.post(f"{BASE_URL}/search/query-mode", json={"query": query}, headers=HEADERS)
    resp.raise_for_status()
    return resp.json()["search_id"]


def collect_results(search_id, max_results=100):
    rows = []
    while len(rows) < max_results:
        resp = requests.post(
            f"{BASE_URL}/search/query-mode/{search_id}/run",
            json={"limit": min(25, max_results - len(rows))},
            headers=HEADERS,
        )
        resp.raise_for_status()
        page = resp.json()
        rows.extend(page["data"])
        if not page.get("has_more"):
            break
    return rows


def export_csv(rows, path="companies_hiring.csv"):
    if not rows:
        return path
    fieldnames = sorted({key for row in rows for key in row})
    with open(path, "w", newline="") as f:
        writer = csv.DictWriter(f, fieldnames=fieldnames)
        writer.writeheader()
        writer.writerows(rows)
    return path


@app.route("/find-hiring-companies", methods=["POST"])
def find_hiring_companies():
    payload = request.get_json(silent=True) or {}
    role = payload.get("role", "software engineer")
    min_employees = payload.get("min_employees", 200)
    query = build_query(role, min_employees)
    problems = guard_query(query)
    if problems:
        return jsonify({"error": "query rejected before sending", "problems": problems}), 422
    search_id = create_search(query)
    rows = collect_results(search_id)
    path = export_csv(rows)
    return jsonify({"query": query, "search_id": search_id, "row_count": len(rows), "csv_path": path})


if __name__ == "__main__":
    app.run(port=5004)

python app.py

curl -s -X POST http://localhost:5004/find-hiring-companies \
  -H "Content-Type: application/json" \
  -d '{"role": "software engineer", "min_employees": 200}'

{
  "query": "select from companies where jobs.exists(job_still_open = true and job_title is_similar_to (\"software engineer\")) and estimated_employee_count > 200",
  "search_id": "search_0tjzcgwnZm6bxAaTwct",
  "row_count": 100,
  "csv_path": "companies_hiring.csv"
}

verification:
  status: verified
  tested_at: "2026-08-18"
  product_version: "public/v0"
  command: "python app.py && curl -s -X POST http://localhost:5004/find-hiring-companies -d '{\"role\":\"software engineer\",\"min_employees\":200}'"
  expected_result: "HTTP 200, row_count=100, companies_hiring.csv with real companies (Google, Amazon, LinkedIn, Microsoft, Deloitte, IBM, Tata Consultancy Services, Apple, Accenture, Tesla)"