Common Discover Searches

Recipes for the searches teams run most. Recipes 1–5 run on both API versions; 6–10 use v3-only features: prose search, company keywords, graph expansion, every matching role, and person exclusions. Use the v2 / v3 switch on any sample, or in the sidebar, to flip the page. Filters mean the same thing on each version; only the request shape differs (see How Discover Works).

Filters are grouped by entity: workExperience, company, person, vendorgraphics. Every field takes and / or / not; ranges take min/max or gte/lte. Values use the normalized vocabularies in the API reference. The API reference’s Discover page has more worked examples, one per capability.

1. Senior engineering leaders at mid-size software companies#

The classic ICP search: function + seniority + employer profile.

Request body

{
  "workExperience": {
    "role": { "or": ["engineering"] },
    "seniority": { "or": ["vp", "cxo"] }
  },
  "company": {
    "industry": { "or": ["computer software"] },
    "employeeCountRange": { "or": ["201-500", "501-1000", "1001-5000"] }
  }
}

2. Recently changed jobs#

New-in-role contacts are the highest-converting outreach segment. Filter on currentStartDateAtCompany — when the person started their current stint at the employer:

Request body

{
  "workExperience": {
    "role": { "or": ["operations"] },
    "seniority": { "or": ["director", "vp"] },
    "currentStartDateAtCompany": { "gte": "2026-03" }
  }
}

3. People at companies that use a specific product#

Combine a vendorgraphics filter with person and company filters — e.g. everyone in data engineering or data science roles at companies using a competitor’s warehouse, excluding a known account. Product IDs come from the Product Catalog (see Vendorgraphics).

Request body

{
  "workExperience": {
    "subrole": { "or": ["data_engineering", "data_science"] }
  },
  "vendorgraphics": {
    "aggkProductId": { "or": [48211] },
    "filterByDetectionPeriod": true,
    "detectionPeriodBuffer": "SIX_MONTHS"
  },
  "company": {
    "aggkCompanyId": { "not": [65731533] }
  }
}

The detection-window filter narrows results to people whose time at the company overlaps the window in which the product was actually detected — otherwise you get today’s employees at a company that used the product years ago. It is not enforced when the product resolves to more than 100 companies; the response says so in warnings.

4. A function in a specific location#

Person location filters describe where the person is, which is not where the company is — an engineer in Berlin at a US-headquartered firm matches person.country: germany and company.country: united states. Filter on whichever one your campaign actually targets.

Request body

{
  "workExperience": {
    "role": { "or": ["finance"] },
    "seniority": { "or": ["cxo"] }
  },
  "person": {
    "personLocality": { "or": ["new york"] },
    "personRegion": { "or": ["new york"] }
  }
}

5. Current employees or recent leavers#

A union, not an intersection: people still in the role plus those who left it within the last year. Because the two arms disagree on employmentStatus, they cannot share one filter block.

v2 Advanced takes a single filter block, so this is two requests — one with personFilter: CURRENT, one with PAST_NOT_CURRENT plus an endDate floor — deduplicated by personId on your side. Switch this page to v3 to see it as one call.

Request 1 of 2 — current employees

{
  "workExperience": {
    "role": { "or": ["engineering"] },
    "personFilter": "CURRENT"
  },
  "company": {
    "employeeCountRange": { "or": ["5001-10000", "10001+"] }
  }
}

Request 2 of 2 — left within the last 12 months

{
  "workExperience": {
    "role": { "or": ["engineering"] },
    "personFilter": "PAST_NOT_CURRENT",
    "endDate": { "gte": "2025-08" }
  },
  "company": {
    "employeeCountRange": { "or": ["5001-10000", "10001+"] }
  }
}

Request body

{
  "or": [
    {
      "name": "current",
      "workExperience": {
        "role": { "or": ["engineering"] },
        "employmentStatus": "CURRENT"
      },
      "company": {
        "employeeCountRange": { "or": ["5001-10000", "10001+"] }
      }
    },
    {
      "name": "recent-leaver",
      "workExperience": {
        "role": { "or": ["engineering"] },
        "employmentStatus": "PAST_NOT_CURRENT",
        "endDate": { "gte": "2025-08" }
      },
      "company": {
        "employeeCountRange": { "or": ["5001-10000", "10001+"] }
      }
    }
  ]
}

6. People who wrote about a topic#

Taxonomy finds the role; keywords finds what the person wrote about it. This search looks for data leaders whose bio or role description mentions data management or enrichment, in a role held within the last two years.

Prose search is v3-only. Switch this page to v3 to see it.

Request body

{
  "or": [
    {
      "workExperience": {
        "seniority": { "or": ["vp", "cxo", "owner"] },
        "activeWithin": "2y"
      },
      "keywords": {
        "all": [
          { "term": "data", "fields": ["description", "bio"] },
          {
            "any": [
              { "term": "management", "fields": ["description", "bio"] },
              { "term": "enrichment", "fields": ["description", "bio"] }
            ]
          }
        ]
      }
    }
  ]
}

Every hit says why it matched. Mark up the words in matches on word boundaries, and escape text first: it is plain text.

Response excerpt — one result

{
  "id": "590654273",
  "firstName": "dan",
  "lastName": "entrup",
  "matchedSnippets": [
    {
      "field": "bio",
      "matches": ["data", "management", "enrichment"],
      "text": "Co-founder of AggKnowledge, a data management and enrichment business purpose-built for knowledge networks."
    }
  ]
}

7. People at a kind of company#

When the target is defined by what the company does, not by the person’s title, use company.keywords. It matches each company’s own description and tags, then returns people there. Here: sales leaders at large dental distributors.

company.keywords is v3-only. On v2, resolve the companies first (Company Match or a category search) and pass their IDs in company.aggkCompanyId.

Request body

{
  "or": [
    {
      "company": {
        "keywords": {
          "and": ["dental"],
          "or": ["distributor", "distribution", "supplies"],
          "not": ["clinic"]
        },
        "employeeCountRange": { "or": ["1001-5000", "5001-10000", "10001+"] }
      },
      "workExperience": {
        "role": { "or": ["sales"] },
        "seniority": { "or": ["director", "vp"] },
        "employmentStatus": "CURRENT"
      }
    }
  ]
}

Only the 10,000 most relevant companies are searched. When more matched, warnings says so. Add an and keyword or a firmographic filter rather than trusting a short result list.

8. An account and everything around it#

Account-based lists rarely stop at one legal entity. company.expansion grows the aggkCompanyId seeds before the search runs. The corporate tree keeps the seeds, and firmographic filters in the same block apply after expansion.

company.expansion is v3-only. Switch this page to v3 to see it.

Request body — Salesforce, its subsidiaries, and its parents

{
  "or": [
    {
      "company": {
        "aggkCompanyId": { "or": ["44002816"] },
        "expansion": { "includeSubsidiaries": true, "includeParents": true }
      },
      "workExperience": {
        "role": { "or": ["marketing"] },
        "seniority": { "or": ["director", "vp", "cxo"] },
        "employmentStatus": "CURRENT"
      }
    }
  ],
  "grouping": { "maxResultsPerCompany": 10 }
}

Swap the corporate tree for a commercial one with relationships.type. VENDOR means the seeds sell, so the search runs over their customers; CUSTOMER runs over their vendors; PARTNER runs over partners in both directions. The seeds drop out: this search does not return Snowflake’s own staff.

Watch out: only a seed’s 1,000 most recently seen relationships are read, and nothing in warnings says when there were more. For a large vendor, slice by firmographics and treat the list as recent customers, not all of them.

Request body — data leaders at Snowflake’s customers

{
  "or": [
    {
      "company": {
        "aggkCompanyId": { "or": ["61230"] },
        "expansion": { "relationships": { "type": "VENDOR" } }
      },
      "workExperience": {
        "subrole": { "or": ["data_engineering", "data_science"] },
        "seniority": { "or": ["director", "vp"] },
        "employmentStatus": "CURRENT"
      }
    }
  ]
}

9. Everyone at a list of accounts, with every role they hold there#

A person can match through more than one role, such as a founder who also holds a VP seat elsewhere. The result is still one person.

v2 returns one matching position per person. Switch this page to v3 to see every role that matched.

matchingPositions lists every role that satisfies the search, up to 10. The ranked one comes first, then the rest, most recent first.

Request body

{
  "or": [
    {
      "name": "target-accounts",
      "company": { "aggkCompanyId": { "or": ["44002816", "15017574"] } },
      "workExperience": { "employmentStatus": "CURRENT" }
    }
  ]
}

Response excerpt — one result

{
  "id": "590654273",
  "firstName": "dan",
  "lastName": "entrup",
  "matchedFilterGroups": ["target-accounts"],
  "matchingPositions": [
    {
      "aggkCompanyId": "44002816",
      "name": "Salesforce",
      "jobTitle": "vice president, engineering",
      "role": "engineering",
      "subrole": "data_engineering",
      "seniority": "vp",
      "startDate": "2023-02",
      "endDate": null,
      "currentStartDateAtCompany": "2022-01",
      "originalStartDateAtCompany": "2020-06",
      "totalStintsAtCompany": 2
    },
    {
      "aggkCompanyId": "15017574",
      "name": "aggknowledge",
      "jobTitle": "co-founder",
      "role": null,
      "subrole": null,
      "seniority": "owner",
      "startDate": "2023-11",
      "endDate": null,
      "currentStartDateAtCompany": "2023-11",
      "originalStartDateAtCompany": "2023-11",
      "totalStintsAtCompany": 1
    }
  ]
}

10. Leave out people you already have#

Re-running a segment should not return the contacts already in your CRM. Exclude them by person ID, up to 1,000 per group.

person.aggkPersonId exclusion is v3-only. On v2, drop known personIds from the results on your side.

Request body

{
  "or": [
    {
      "workExperience": {
        "role": { "or": ["finance"] },
        "seniority": { "or": ["cxo", "vp"] },
        "employmentStatus": "CURRENT"
      },
      "vendorgraphics": { "aggkProductId": { "or": ["48211"] } },
      "person": { "aggkPersonId": { "not": ["590654273", "731209846"] } }
    }
  ]
}

Watch out: aggkPersonId takes only not; or and and are rejected. Filters do not carry across groups, so a multi-group search repeats the exclusion in every group.

11. Alumni of a school#

A school is a company in AggKnowledge, so it is filtered by the same aggkCompanyId person enrichment returns on each education entry. School filters look at a person’s whole education history, not one role, so not removes the person outright.

School filters are v3-only. Switch this page to v3 to see the request.

Request body

{
  "or": [
    {
      "workExperience": {
        "role": { "or": ["engineering"] },
        "employmentStatus": "CURRENT"
      },
      "person": { "schoolAggkCompanyId": { "or": ["27401835"] } }
    }
  ]
}

Some schools carry no ID, only a name. schoolName reaches them: an exact match on the school’s canonical name, ignoring case, such as massachusetts institute of technology.

12. Leave out everyone who has worked at a company#

Exclude by employer history, not by the matching role. This search finds people whose bio mentions Salesforce, minus everyone who works there now or ever did. person.employerAggkCompanyId holds every company the person has worked at, so not removes the person outright.

Employer filters are v3-only. Switch this page to v3 to see the request.

Request body

{
  "or": [
    {
      "keywords": { "term": "salesforce", "fields": ["bio"] },
      "person": { "employerAggkCompanyId": { "not": ["44002816"] } }
    }
  ]
}

Watch out: company.aggkCompanyId with not drops only roles at that company. A former employee still comes back through their other roles, so use it for “not in this role at this company” and person.employerAggkCompanyId for “never worked there”.

Use or for “has worked at”. Pair it with the group’s own role filters to find people who hold one role now and worked somewhere else before. Some employers carry no ID, only a name; employerName excludes them with an exact match, ignoring case. It takes not only, because a name can belong to unrelated companies.

Tip: Always run Count results with the same body first — it’s free on both versions, and the cheapest way to sanity-check a filter before paging. See How Discover Works.