> ## Documentation Index
> Fetch the complete documentation index at: https://developers.clay.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Search with structured filters

> Find Clay companies or people with a JSON filters object.

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

1. List the fields accepted for the record type you want.
2. Create a search with `source_type` and `filters`.
3. 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.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
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.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
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.

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "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

<Card title="Advanced search" href="/searches/advanced">
  Use cross-entity criteria and nested Boolean logic.
</Card>