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.

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.

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

Public API quickstart

Set up your API key.

Generated API reference

See the create-search schema and try-it UI.

Run a search, then enrich with a function

Combine Searches with Clay-managed functions.