Verticals | Yext Hitchhikers Platform

A vertical is a class of results that are grouped together for a search. It is often synonymous with an entity type, though you can choose to have multiple entity types in a given vertical if you’d like those results to be combined. When users run a vertical search, they are only running a search on that one vertical.

Search Configuration Schema

Within the Search configuration, verticals is a top-level object that defines the configuration settings for each vertical. Within verticals, each vertical is defined as a separate object that uses the vertical key as the key and has the following available top-level fields.

View where verticals fits into the configuration in the Search Config Properties - Top Level reference doc. Find more detail about these properties below.

This table only displays properties for the source is YEXT, i.e. when the vertical uses content from the Yext platform. If you are using a third-party vertical, refer to the Search Config - Third Party Verticals reference doc for the schema.

Property Type Shown in Config UI Description
verticalKey string Yes The internal key for each individual vertical object within the verticals object, used to uniquely identify the vertical and connect the vertical to the frontend
name string Yes Display name of the vertical
source string No The data source for the backend. Options include:
  • YEXT
  • verticalIntents (deprecated) object No Configuration to boost relevance of a vertical. Deprecated in favor of the query rule actions to boost and bury verticals.
    baseScore (deprecated) number No Base ranking of the vertical. Deprecated in favor of semanticVerticalBias.
    entityTypes array of strings Yes API names of the entity types allowed in this vertical
    savedSearchId string Yes Saved filter to restrict results to
    dynamicRerank object Yes Controls dynamic reranking of results based on user engagement. Only available for verticals with FAQ entity type.
    sortBys array of objects Yes Specification for how results should be ordered. Each sorting rule is contained within an object with the below properties.
    facets object No Specification for numerical facets.
    searchableFields object Yes Map of field API names to field configurations. Within the object for each field, set to true any searchable field type you want to enable for that field. Options are:
  • textSearch
  • semanticTextSearch
  • phraseMatch
  • documentSearch
  • facet
  • staticFilter
  • nlpFilter
  • sortable
  • facetOrder array of strings No Ordering for facets
    nlpFilterOrder array of strings No Priority ordering of fields for NLP Filtering
    minLocationRadius number No A minimum location radius override in meters.
    directAnswers object Yes Configuration for various types of direct answers.
    displayFields array of strings No Fields on the profile that are returned to the frontend. If omitted or empty, all fields will be returned. Use dot notation to specify substructures.
    authorization object No Indicates choice of authorization scheme.
    semanticVerticalBias number Yes A value that will always be added to the semantic vertical relevance score.
    semanticVerticalThreshold number Yes Verticals with semantic relevance scores less than the threshold will not show.
    semanticVerticalIntents array of strings Yes An array of strings that will contribute to semantic vertical ranking.
    semanticVerticalRankingPriorityFields array of strings No An array of field IDs, used as a tiebreaker for ranking verticals when multiple have the same score. Verticals with semantic values associated with these fields will be prioritized.
    verticalType string No Specifies the search tier. Only valid when source is YEXT. Options are either “BASIC” or “ADVANCED”.

    Top-Level JSON

    The JSON below is for demonstrative purposes only to show the structure of the verticals object through the top-level properties of an individual vertical. Find more detail about each object below.

      "verticals": {
        "restaurants": {
          "authorization": {},
          "directAnswers": {},
          "displayFields": [],
          "dynamicRerank": {},
          "entityTypes": [],
          "facets": {},
          "facetOrder": [],
          "minLocationRadius": 5000,
          "name": "Restaurants",
          "nlpFilterOrder": [],
          "savedSearchId": "112002255",
          "searchableFields": {},
          "semanticVerticalBias": 0.2,
          "semanticVerticalIntents": [],
          "semanticVerticalRankingPriorityFields": [],
          "semanticVerticalThreshold": 0.2,
          "sortBys": [],
          "source": "YEXT"


    Set up Authorized Search to authenticate users so that only the information the user has access to view will appear in search results. You can authenticate users using either Yext Auth or any existing authentication system you may have already configured.

    To learn how to set up authorized search using Yext Auth, check out the Set up a Yext Authenticated Site and an Authorized Search Experience guide.

    To learn how to set up authorized search using external authentication, check out the Set up Search with External Authorization guide.

    In the authorization object, set the type based on what authorization you’re using.

    Property Type Shown in Config UI Description
    type string No Set to either:
  • yext if using Yext authorization
  • external if using external authorization
  • Direct Answers

    light bulb
    Advanced Search Tier Feature
    Direct answers are only available on the Advanced Search tier. Check out the Search Tiers reference doc to learn more about the features that are available in each tier.

    Direct answers are meant to directly answer a user’s question by extracting information from results. There are two types of direct answers: Field Value Direct Answers come from structured data and Featured Snippet Direct Answers come from unstructured data. Check out the Direct Answers unit for more details.

    Within directAnswers, the configuration needed to set up each type of direct answer is below.

    Property Type Shown in Config UI Description
    featuredSnippet object Yes Configuration for featured snippets from any field with document search enabled.
    predictionMode string Yes Whether featured snippets require explicit approval from experience training. Options include “APPROVE_ONLY” and “ALLOW_ALL”.
    fieldValue object Yes Configuration for field value direct answers
    eligibleFields array of strings Yes Array of API names for fields that are eligible for field value direct answers.
    predictionMode string Yes Determines when a field value direct answer is extracted. Options include “CLASSIFIER”, “FIELD_NAME”, and “ONE_ENTITY”.

    Featured snippets extract answers to users’ questions from any unstructured fields for which the searchable field type document search is activated (learn more in the Searchable and Display Fields unit). Since these types of fields tend to contain long form content, featured snippets will extract out the snippet that best responds to the query.

    For example, this Help Articles vertical has the prediction mode for featured snippets set to APPROVE_ONLY, so only featured snippets approved in Experience Training will surface.

        "help_articles": {
          "directAnswers": {
            "featuredSnippets": {
              "predictionMode": "APPROVE_ONLY"

    Field Value Direct Answer

    Field value direct answers respond to user questions directly using structured Content fields you designate as eligible. The entire value of the eligible field is returned as the direct answer.

    For example, this Restaurants vertical would return mainPhone as a direct answer with the prediction mode CLASSIFIER.

        "restaurants": {
          "directAnswers": {
            "fieldValues": {
              "eligibleFields": [
              "predictionMode": "CLASSIFIER"

    Display Fields

    For each vertical, you can use the displayFields property to specify the entity profile fields that are returned as part of the Search API response. If you don’t include the displayFields property (default), the Search API response returns all fields on the result entity, but not any fields of related entities. If you do include the displayFields property, Search will only return the fields that you provide in this property, even if they are on the result entity.

    You can only display fields on the frontend if they are passed to the frontend by the backend via the Search API response, so display fields are required if you want to display a field value from a related entity of a result in the frontend.

    For example, given that in a doctors vertical, each doctor is related to a specialty entity that has the name of that specialty and a list of related conditions and treatments. Here is an example of a displayFields property that you might set up to display all of those attributes:

    "displayFields": [

    Check out the Searchable and Display Fields unit for more details.

    Dynamic Rerank

    light bulb
    Advanced Search Tier Feature
    Dynamic reranking is only available on the Advanced Search tier. Check out the Search Tiers reference doc to learn more about the features that are available in each tier.

    Dynamic reranking uses machine learning to rerank results and answers based on user engagement data. If you turn on dynamic reranking for a vertical, the algorithm gradually learns to optimize the order of results based on the number of clicks. Check out the Sorting (Backend) unit for more details.

    The dynamicRerank object just takes one property.

    Property Type Shown in Config UI Description
    target string No Which user action to optimize for. Options include “CLICKS”. If you enable dynamic reranking in the UI, the target will automatically be set.

    If you turn on dynamic reranking for the FAQs vertical, here is what the JSON configuration would look like:

        "faqs": {
          "dynamicRerank": {
            "target": "CLICKS"

    Entity Types

    Specify the entity types to map to each vertical in the entityTypes array.

    For example, in the JSON configuration below, the Events vertical uses the events entity type and the Locations vertical uses both the locations and ATMs entity types.

      "verticals": {
        "events": {
          "entityTypes": [
        "locations": {
          "entityTypes": [


    Facets allow the end user to refine the search results using various attributes of your content. They are viewable “post-search”, since they’re dependent on the search query. There are three types of facets: standard facets, numerical facets, and hierarchical facets. For standard and hierarchical facets, the only setup you have to do in the Search configuration is setting the field as a facet in searchable fields.

    In addition to this configuration, numerical facets require additional setup using the facets object to define the numerical ranges to use. The available fields are listed below. There are three options for setting ranges.

    Property Type Shown in Config UI Description
    fields array of objects No An array of facets for specific fields
    fieldId string No The field being used for the facet
    sortCriteria string No Which way to order. Either ‘ASC’ or ‘DESC’
    ranges object No oneOf: An object describing generated ranges
    algorithm string No The algorithm to use. Either ‘DYNAMIC’ or ‘STATIC’
    bucketCount number No The number of buckets to generate. Only valid for DYNAMIC algorithms.
    bucketLength number No The length of buckets to generate. Only valid for STATIC algorithms.
    ranges array No oneOf: An array of ranges to explicitly set ranges
    start number No The start of the range
    end number No The end of the range
    displayName string No The name of the range

    Check out the Set up Standard Facets guide for details on the setup you would use for each of the three setup options.

    Facet Order

    You can set the order in which facets appear on the frontend for each vertical. The facets at the top of the list will get the most attention. Consider placing the most general, high-level filter categories at the top of the list and the more specific ones at the bottom. If you don’t specify an order, the algorithm will determine this for you. Check out the Facets and Filters (Backend) unit for more detail.

    Use the facetOrder array to specify the order you want facets to appear in. Any facets that appear on a given vertical that are not included in the facetOrder property will be shown in an arbitrary but consistent order, chosen by the algorithm.

    For example, the below designates the facet order as restaurant type, then restaurant features for the Restaurants vertical.

        "restaurants": {
          "facetOrder": [

    Minimum Location Radius

    Minimum location radius can be used to set a minimum on the radius of geolocation filters applied. By default, if a user searches for a place, Search will automatically pick a radius based on the size of that place. You may want to set a higher minimum radius if your business has wide service areas, for example. Learn more in the How Geolocation Filters Work reference doc.

    As with all distance filters, minLocationRadius is set in meters. The following sets a minimum radius for the Locations vertical to 400 miles or 643738 meters.

        "locations": {
          "minLocationRadius": 643738.0,


    This is the display name of the vertical, which is shown in vertical header and vertical navigation below the search bar, unless overridden on the frontend.

    NLP Filter Order

    NLP filters create a black and white filter with the best exact match (see the Searchable Fields section for more detail). In some cases, however, the same filter value exists in two different fields that have NLP filter turned on. In a scenario like this, the actual filter that is selected and applied is arbitrary. With the nlpFilterOrder array, you can specify the order in which you’d like NLP filters to be selected when conflicts happen.

    Validation code dictates that any field name put in the nlpFilterOrder array must be a searchable field with NLP filter enabled.

    As an example, a healthcare client has Cardiology as a value in their specialties field and their builtinFile.medicalConditions field. Before nlpFilterOrder, a search for “cardiology near me” would trigger one of these filters arbitrarily. Below is what a config might look like to specify specialties showing up first in the Facilities vertical, which means it will be given priority in the case of a tie.

        "facilities": {
          "entityTypes": [
          "name": "Facilities",
          "nlpFilterOrder": [
          "searchableFields": {
            "builtinFile.medicalConditions": {
              "nlpFilter": true
            "specialties": {
              "nlpFilter": true
          "source": "YEXT"

    Saved Search ID

    Use a Content saved filter to specify the entities that are allowed to be returned in a given vertical. Each vertical may only have one saved filter. You’ll want to include this if you need to limit the entities returned for a vertical in some way, for example only those locations that are open, FAQs that have the Answer field filled out, or events that are in the future. To obtain the ID for a saved filter, follow the View Saved Filters help article.

    If no saved filter is specified, all entities of the entity types enabled for the vertical could be returned.

    Check out the Overview of Verticals unit for more details.

    Below is an example of an Events vertical using savedSearchId:

        "events": {
          "entityTypes": [
          "name": "Events",
          "savedSearchId": "125019244"

    Searchable Fields

    light bulb
    Advanced Search Tier Features
    Semantic search, NLP filter (except builtin.location), and document search are only available on the Advanced Search tier. Check out the Search Tiers reference doc to learn more about the features that are available in each tier.

    Searchable fields tell the algorithm which fields on each vertical to index and how. These searchable fields then affect which results are returned to the user.

    Within the searchableFields object, list each field you want to make searchable as an object, and then within that object, list each searchable field type you want to enable as true. The only searchable field type not available in the UI is static filter. For more information on common use cases, check out the Searchable Fields Best Practices reference doc.

    The possible searchable field types are listed below:

    Property in UI Property in JSON Description Common Use Cases (Fields)
    Phrase Match phraseMatch Phrase Match allows an entity to be surfaced only when there is an exact phrase match contained in the query. Keywords, First Name, Last Name
    Text Search textSearch Text Search allows each token of the query to be searched within the fields you specify. This is best for short text fields that might contain unstructured or varied data. Name, Keywords
    Semantic Text Search semanticTextSearch This turns on our Semantic Text Search algorithm, which will match a user’s query to an entity name that is semantically similar (not available for Location entities). Name, especially FAQ Name and Help Article Name
    NLP Filter nlpFilter NLP Filter enables each term in the search query to be parsed with Natural Language Processing (NLP) and used as a filter. This is best for structured enum/option fields where there are a finite number of variations across entities. builtin.location, builtin.entityType,, Department, Category, Vertical, Industry
    Document Search documentSearch This turns on our Document Search algorithm, which searches long, unstructured content from an entity and returns featured snippets. Description and Body fields from Help Articles, Blogs, Product Descriptions, Files, and much more. Check out the File Search reference doc for limitations.
    Facet facet Facets allow a field to be used as a type of dynamic filter that a user can interact with in the search experience to narrow their search. This is best for structured enum/option fields where there are a finite number of variations across entities. Department, Category, Vertical, Industry, Department, Insurance, Services, Payment Methods
    Sortable sortable Sortable allows a field to be used as a sorting method that is controlled by the algorithm or by the user. Name, Date, Popularity, Accepting New Patients
    Static Filter staticFilter Static filters are viewable “pre-search” and are not dependent on the search query. They are defined on the client-side so whenever a user queries an experience, any enabled static filter is submitted as an additional filter with the query, restricting the results that are returned. Time ranges for Created Date, State/Region filter for Locations

    Special NLP Filter Uses

    There are special NLP filters that leverage a “built-in” entity value. We will go through the three most common built-in NLP filters below (all are available through both the UI and JSON):

    NLP Filter Description Use Case
    builtin.location Enables location searching, such as “near me”, zip code, address, city, state, and more Use to enable location searching for all entity types with an address (i.e., locations, jobs, healthcare professionals)
    builtin.entityType Enables searching on the entity type name Use for each vertical to allow a user to search by entity type names
    builtin.hours Enables searching an entity’s hours of operation Use for each vertical to allow a user to search for entities that are “open now”


    Using this searchable field will enable address search features, like searching a zip code (10011), address line 1 (61 Ninth Ave), city (New York), state (NY), and “near me”. The address searching is possible because of our built-in address field for entities and its associated information, like latitude/longitude.

    Note, it is NOT searching through the address field values. A search for “New York” may return locations outside of that state if they are nearby. To search by a field, set an NLP filter for that specific field, e.g. address.region.


    As a standard practice, use the builtin.entityType NLP filter for each of your vertical search configurations. This returns the relevant vertical for searches for an entity type. Additionally, for verticals with more than one entity type, enabling this filter will return the respective entity types within that vertical search.


    Using this searchable field will enable searching an entity’s hours of operations. Today, this NLP filter only supports “open now” intents, so a user could search “restaurants open now” and get a list of restaurants that are open with consideration of a user’s time zone and the entity’s holiday hours.

    Here is an example of a Restaurants vertical that includes the following configuration:

    • Special NLP filter uses for both builtin.entityType and builtin.location
    • An entity relationship using the name field from the related Event entities through the c_promotingEvents field
    • A field (c_restaurantFeatures) with multiple searchable field types enabled

      "restaurants": {
        "searchableFields": {
          "builtin.entityType": {
            "nlpFilter": true
          "builtin.location": {
            "nlpFilter": true
          "": {
            "nlpFilter": true
          "c_restaurantFeatures": {
            "facet": true,
            "nlpFilter": true
          "c_restaurantType": {
            "facet": true
          "name": {
            "textSearch": true

    Semantic Vertical Bias

    Biases are adjustments you can make to the final score of each vertical, which determine the rank in which they appear. Biases are limited from -1 to 1 (inclusive) and can only include a single decimal point.

    Check out the Vertical Ranking unit for more details.

    In the example below, the Help Articles vertical has a semanticVerticalBias of 0.2, boosting the vertical by 0.2 for all searches:

        "help_articles": {
          "semanticVerticalBias": 0.2

    Semantic Vertical Intents

    Vertical intents are phrases that you want to associate with that vertical as a whole, like a synonym for the vertical. A good way to think about vertical intents is to ask yourself: if this intent was placed as a search query, would I want this vertical to always return first?

    Check out the Vertical Ranking unit for more details.

    In the example below, the Help Articles vertical uses semanticVerticalIntents to assign some synonyms to the vertical:

        "help_articles": {
          "semanticVerticalIntents": [
            "how to"

    Semantic Vertical Threshold

    Thresholds are minimum score requirements that a vertical must meet in order to be returned at all in the universal search results. A vertical will always be returned in vertical search. Thresholds are limited from 0 to 1 (inclusive) and can only include a single decimal point.

    Check out the Vertical Ranking unit for more details.

    In the example below, the Help Articles vertical has a semanticVerticalThreshold value of 0.4, meaning the vertical must have a score of 0.4 to appear in universal search.

        "help_articles": {
          "semanticVerticalThreshold": 0.4

    Semantic Vertical Ranking Priority Fields

    Priority fields are a select list of the searchable fields that you want the algorithm to prioritize for a vertical when evaluating vertical ranking. If two verticals are tied and have the same vertical score, the Search algorithm will use priority fields as a tiebreaker: looking at the top entities returned on each vertical, matches on priority fields are ranked above other matches.

    Check out the Vertical Ranking unit for more details.

    In the example below, the Help Articles vertical ranks fields in the semanticVerticalRankingPriorityFields property:

        "help_articles": {
          "semanticVerticalRankingPriorityFields": [

    Sort Bys

    The default sort order is the order in which entity results are returned for a specific vertical. If you don’t set a default sort order for a vertical, the Search algorithm will determine it for you, based on relevance, which includes location bias to the user (when applicable).

    You also have the ability to customize the default sorting for each vertical, should you want to adjust the order beyond relevance.

    In the sortBys array, specify each sorting rule as a separate object with the following properties:

    Property Type Shown in Config UI Description
    type string Yes The type of sort. Options are:
  • field string Yes If the type is FIELD, the field to sort on
    direction string Yes If the type is FIELD, set sorting direction. Options are ASC (ascending) or DESC (descending)
    buckets array of numbers Yes If the type is ENTITY_DISTANCE and buckets are being used, the buckets to use
    relevanceAlgorithm string No If the type is RELEVANCE, there is an option to set this property to MATCH_QUERY_TOKENS. This form of RELEVANCE sorting criteria counts the number of matching tokens from the query in the result to determine the relevance score. Results that are approximately equally relevant to each other will resort to the subsequent sorting criteria to act as a tie breaker.

    Sorting Types

    The available options for sort type are:

    Property in UI Property in JSON Description
    Relevance RELEVANCE Relevance is our standard sorting
    Random RANDOM This will sort entities randomly.
    Distance ENTITY_DISTANCE This is the distance from the users location or the users intended location.
    Field FIELD Any field can be used to sort results. We support number, date, and boolean fields. Text fields are supported for A-Z or Z-A sorting. As part of the configuration, you also need to specify the field and as well as the order it should be sorted: either ascending (triggered by “ASC) or descending (triggered by “DESC”).

    In the example below, the Events vertical uses all four types of sort, with the sorting rules as follows:

    • Relevance, with relevance algorithm set to match query tokens of the results. Any results with an equal amount of tokens matched will use the next sorting criteria (in this case, distance) to determine their sort order.
    • Distance, with buckets for 8046.72 meters (5 miles), 80467.2 meters (50 miles), and 160934.0 meters (100 miles)
    • Field, using the Start Time field sorted in ascending order
    • Random

      "events": {
        "sortBys": [
            "relevanceAlgorithm": "MATCH_QUERY_TOKENS",
            "type": "RELEVANCE"
            "buckets": [
              8046.72, // 5 miles
              80467.2, // 50 miles
              160934.0 // 100 miles
            "type": "ENTITY_DISTANCE"
            "direction": "ASC",
            "field": "time.start",
            "type": "FIELD"
            "type": "RANDOM"


    The source is the data source used for the vertical. Any vertical created in the platform UI will set the source as YEXT, which means the vertical pulls data from the Content.

    In the JSON editor, you can also add third-party backends (see the Search Config - Third Party Verticals reference doc for more details).

    In the example below, the Help Articles vertical uses content from the platform, so the source is YEXT.

        "help_articles": {
          "source": "YEXT"

    Vertical Key

    The vertical ID uniquely identifies the vertical within the experience. This is set when you create the vertical. While it is possible to change the vertical key here, it is discouraged due to potential downstream consequences. If you do change it, make sure to update any references to the same vertical key, particularly in the frontend.

    Vertical Type

    The vertical type specifies the search tier used by the vertical. This only applies when the source is Yext. Currently options are “BASIC” or “ADVANCED”.

    If vertical type is not specified and your account only has one of the two subscriptions, all verticals will default to that search tier. However, if your account has both the Basic Search subscription and the Advanced Search subscription, any vertical without a search tier specified will default to the Advanced Search tier.

    Check out the Search Tiers reference doc to learn more about search tiers and the features that are available in each tier.