Search with advanced queries (beta)

Advanced search is in beta. It supports criteria from Clay’s field catalog as well as cross-entity filters and nested Boolean logic. Advanced queries return either people or companies. Count queries and job searches are not available through the Public API.

Get the query reference

Fetch the query reference before writing a query. It describes the available fields and grammar.

curl --request GET \
  --url https://api.clay.com/public/v0/search/query-mode/reference \
  --header "clay-api-key: $CLAY_PUBLIC_API_KEY"

Create and run a people search

This pattern returns current software engineers whose employer is in the Software Development industry.

QUERY='select from people where experiences.any('\
'is_current = true and '\
'job_title is_similar_to ("software engineer") and '\
'company.industry = "Software Development")'

SEARCH_ID=$(curl --request POST \
  --url https://api.clay.com/public/v0/search/query-mode \
  --header "Content-Type: application/json" \
  --header "clay-api-key: $CLAY_PUBLIC_API_KEY" \
  --data "$(jq -n --arg query "$QUERY" '{query: $query}')" \
  | jq -r '.search_id')

curl --request POST \
  --url "https://api.clay.com/public/v0/search/query-mode/$SEARCH_ID/run" \
  --header "Content-Type: application/json" \
  --header "clay-api-key: $CLAY_PUBLIC_API_KEY" \
  --data '{"limit": 20}'

Use cross-entity query patterns

Choose the record type you want returned, then query through its relationships.

Find people based on their employer

Use experiences.any(...) to return people whose current employer meets your criteria.

select from people
where experiences.any(
  is_current = true and
  job_title is_similar_to ("engineer") and
  company.technographics.any(vendor = "Salesforce")
)

Find companies based on their employees

Use people.exists(...) to return companies that employ people matching your criteria.

select from companies
where people.exists(
  is_current = true and
  job_title is_similar_to ("VP Sales")
)

Combine criteria with Boolean logic

Group related criteria with parentheses to express alternatives while keeping the company requirement.

select from people
where experiences.any(
  is_current = true and
  (
    job_title is_similar_to ("VP Sales") or
    job_title is_similar_to ("Head of Sales")
  ) and
  company.estimated_employee_count >= 500
)

Fetch more results

The run endpoint is a stateful iterator. Its response contains data, has_more, and source_type, and can include exhaustion_reason. If has_more is true, call POST /search/query-mode/{search_id}/run again to fetch the next page. People results include a structured location and an array of experiences that matched the query. matched_experiences is always an array; it is empty when no specific experience matched.

{
  "data": [
    {
      "clay_profile_id": 42,
      "name": "Jane Doe",
      "first_name": "Jane",
      "last_name": "Doe",
      "location": {
        "name": "New York, New York, United States",
        "city": "New York",
        "state_or_province": "New York"
      },
      "matched_experiences": [
        {
          "company": "Example Corp",
          "title": "Software Engineer",
          "location": "New York, New York, United States",
          "start_date": "2024-01-01",
          "end_date": null
        }
      ]
    }
  ],
  "has_more": true,
  "source_type": "people"
}

Company results use their own projection, including clay_company_id, name, size, type, domain, country, industry, location, description, linkedin_url, annual_revenue, and total_funding_amount_range_usd.

Next steps

Structured filters

Use the older JSON filters format.

Start here

Core primitives

Recipes

Concepts

API Reference

Search with advanced queries (beta)

Get the query reference

Create and run a people search

Use cross-entity query patterns

Find people based on their employer

Find companies based on their employees

Combine criteria with Boolean logic

Fetch more results

Next steps

Structured filters

​Get the query reference

​Create and run a people search

​Use cross-entity query patterns

​Find people based on their employer

​Find companies based on their employees

​Combine criteria with Boolean logic

​Fetch more results

​Next steps

Structured filters

Get the query reference

Create and run a people search

Use cross-entity query patterns

Find people based on their employer

Find companies based on their employees

Combine criteria with Boolean logic

Fetch more results

Next steps