Search with structured filters

Use structured filters (filters mode) when you prefer a JSON filters object or already have filters-mode searches. The flow is:

List the fields accepted for the record type you want.
Create a search with source_type and filters.
Fetch result pages with the returned search_id.

Choose a source type

Set source_type to the records you want back.

Source type	Use it for
`people`	Contacts, titles, locations, and profile data
`companies`	Accounts, domains, industries, and firmographics

Discover available filters

Call the fields endpoint before you create a search. The response describes accepted filter names, types, enum values, usage guidance, and example create requests for the selected source type.

curl --request GET \
  --url "https://api.clay.com/public/v0/search/filters-mode/fields?source_type=people" \
  --header "clay-api-key: $CLAY_PUBLIC_API_KEY"

Create and run a people search

This pattern returns people whose titles include “software engineer” and whose location is New York.

SEARCH_ID=$(curl --request POST \
  --url https://api.clay.com/public/v0/search/filters-mode \
  --header "Content-Type: application/json" \
  --header "clay-api-key: $CLAY_PUBLIC_API_KEY" \
  --data '{
    "source_type": "people",
    "filters": {
      "job_title_keywords": ["software engineer"],
      "location_cities_include": ["New York"]
    }
  }' | jq -r '.search_id')

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

Fetch more results

The run endpoint is a stateful iterator. Its response contains data and has_more. If has_more is true, call POST /search/filters-mode/{search_id}/run again to fetch the next page.

{
  "data": [
    {
      "name": "Jane Doe",
      "first_name": "Jane",
      "last_name": "Doe",
      "url": "https://www.linkedin.com/in/janedoe",
      "latest_experience_title": "Software Engineer",
      "latest_experience_company": "Example Corp",
      "latest_experience_start_date": "2024-01-01",
      "matched_experience": null,
      "structured_location": {
        "city": "New York",
        "state": "New York",
        "country": "United States"
      }
    }
  ],
  "has_more": true
}

Use latest_experience_title, latest_experience_company, and latest_experience_start_date for a person’s current role. matched_experience is contextual and can be null when the search matched profile- or company-level filters instead of a specific experience.

Next steps

Advanced search

Use cross-entity criteria and nested Boolean logic.

Start here

Core primitives

Recipes

Concepts

API Reference

Search with structured filters

Choose a source type

Discover available filters

Create and run a people search

Fetch more results

Next steps

Advanced search

​Choose a source type

​Discover available filters

​Create and run a people search

​Fetch more results

​Next steps

Advanced search

Choose a source type

Discover available filters

Create and run a people search

Fetch more results

Next steps