> ## 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.

# Searches

> Create structured-filter searches over Clay's proprietary GTM database and fetch structured records.

Searches let you access Clay's company and people data with structured filters.

When called through the Public API, Searches are three steps:

1. List the available filter fields for a source type.
2. Create a search from `source_type` and `filters`.
3. Use the returned `search_id` to fetch results.

## Create and fetch a page

This example discovers people filter fields, creates a people search, and fetches the first page.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl --request GET \
  --url "https://api.clay.com/public/v0/searches/fields?source_type=people" \
  --header "clay-api-key: $CLAY_API_KEY"

SEARCH_ID=$(curl --request POST \
  --url https://api.clay.com/public/v0/searches \
  --header "Content-Type: application/json" \
  --header "clay-api-key: $CLAY_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/searches/$SEARCH_ID/next" \
  --header "Content-Type: application/json" \
  --header "clay-api-key: $CLAY_API_KEY" \
  --data '{"limit": 20}'
```

## Choose a source type

Set `source_type` based on the records you want back.

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

Call `GET /searches/fields?source_type=people` or `GET /searches/fields?source_type=companies` before creating a search. The fields catalog returns accepted filter names, types, enum values, usage guidance, and example create requests.

## Response shape

The page endpoint returns records and `has_more`.

```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 may be `null` when the search matched profile- or company-level filters instead of a specific experience.

If `has_more` is `true`, call `POST /searches/{search_id}/next` again.

## Related guides

<Card title="Public API quickstart" href="/public-api/quickstart">
  Set up your API key.
</Card>

<Card title="Generated API reference" href="/api-reference/searches/create-a-search-from-structured-filters">
  See the create-search schema and try-it UI.
</Card>

<Card title="Run a search, then enrich with a function" href="/recipes/search-and-enrich">
  Combine Searches with Clay-managed functions.
</Card>