How filters work

Describe positions and locations in query or search_requirements. Pearch interprets the intent and maps the names for you.

InputHow Pearch interprets it
PositionsMaps equivalent names for the same role, including different job titles. Include seniority and specialization when they matter.
LocationsInterprets different names for the same geography and the intended geographic scope.

Custom filters

  • When to use custom_filters: custom_filters require Scale with Us and are not included in Free Trial or Self-Service. They can sharply reduce the number of matching candidates and exclude relevant people. Prefer search_requirements or query, which are available on all plans. In search_requirements, mark mandatory criteria with must_have: true. Contact [email protected] so we can help configure custom_filters for your search.
  • AND and OR: In custom_filters, different fields combine with AND: every field must match. Alternative values in lists such as titles or locations combine with OR: any listed value can match.
  • Exclusions with not_*: Use supported exclusion fields such as not_titles, not_locations, and not_companies to exclude matching candidates. A candidate matching any value in an exclusion list is excluded. The not_* prefix is supported only for the fields listed in the API reference.
  • Location mistakes: Each location in custom_filters must be complete. For London OR Berlin, use two entries: “London, United Kingdom” and “Berlin, Germany.” Separate “London” and “United Kingdom” entries mean London OR anywhere in the UK. Choosing the wrong geographic level can also narrow the pool.

Search within a radius

For a Fast search, include the latitude, longitude, radius, and distance unit in a search requirement. Mark it as must_have when the location is mandatory. For example, use “Located within 10 miles of latitude 37.7749, longitude -122.4194”. See search by coordinates and radius for a full request and the corresponding structured filter.

For Scale with Us integrations that use custom filters, languages and not_languages accept a canonical language name or a language object with an optional proficiency. See custom filters for the current schema.


Did this page help you?