Action - Return Pinned Result

What You’ll Learn

In this section, you will learn:

How to structure the Return Pinned Result action
Example of the Return Pinned Result action

Action Structure

There are two top level properties of this action - directAnswer and verticals.

Top Level Properties

Key	Type	Example
directAnswer	Optional, Direct Answer Object	See below
verticals	Array of Vertical Object with length of at least 1	See below

Vertical Object

The vertical object defines the behavior of each vertical included in the pinned results. For a Knowledge Graph vertical, entityIds or savedFilterId is required. For a vertical that is not powered by the Knowledge Graph, it will show the normal results from that backend wherever that vertical is referenced - you cannot control the order of the results.

Key	Type	Example
verticalKey	String	“specialties”
entityIds	Array of strings	[“2323”, “2342”]
savedFilterId	String	“21466424”

Direct Answer Object

You can also specify the direct answer that should show alongside the entity results. entityId, fieldId, and verticalKey are required. Note that the fieldId you specify must also be set in your verticals Search Configuration object as "directAnswer": "true".

Key	Type	Example
entityId	String	“230s”
fieldId	String - Field API Name	“name”
verticalKey	String	doctors

Config Structure

{
  "actionType": "RETURN_PINNED_RESULT",
  "directAnswer": {
    "entityId": "230s",
    "fieldId": "name",
    "verticalKey": "doctors"
  },
  "verticals": [
    {
      "verticalKey": "specialties",
      "savedFilterId": "21466424"
    },
    {
      "verticalKey": "faqs",
      "entityIds": [
        "FAQ-1",
        "FAQ-2"
      ]
    },
    {
      "verticalKey": "links"
    }
  ]
}

If you’re using the UI, you can paste this in to the input:

{"actionType":"RETURN_PINNED_RESULT","directAnswer":{"entityId":"230s","fieldId":"name","verticalKey":"doctors"},"verticals":[{"verticalKey":"specialties","savedFilterId":"21466424"},{"verticalKey":"faqs","entityIds":["FAQ-1","FAQ-2"]},{"verticalKey":"links"}]}

The following example will reference the JSON editor, but you can use either.

Pinned Results Example

For a query like “turtlehead tacos headquarters”, we might want to push users to apply for a job.

We’ll do the following:

Look for any search terms that contain turtlehead tacos headquarters
Set the directAnswer object to return the address field for entity hq-1 in the restaurants vertical

Return the FAQs vertical filtered to the savedFilterId of 146669234.

{
	 "criteria": {
    "searchTermContains": [
      "turtlehead tacos headquarters"
    ]
  },
  "actions": [
    {
      "actionType": "RETURN_PINNED_RESULT",
      "directAnswer": {
        "entityId": "hq-1",
        "fieldId": "address",
        "verticalKey": "restaurants"
      },
      "verticals": [
        {
          "savedFilterId": "146669234",
          "verticalKey": "faqs"
        }
      ]
    }
  ]
}

Pinned HQ Query

Note

Use pinned results sparingly. By pinning results, you are completely overriding the algorithm behavior for the queries that match your criteria, which could have unintended consequences and be difficult to maintain.

Action - Return Pinned Result | Yext Hitchhikers Platform

What You’ll Learn

Action Structure

Top Level Properties

Vertical Object

Direct Answer Object

Config Structure

Pinned Results Example

What are the top level properties used in the Return Pinned Result action? Select all that apply.

What are the components in the Vertical Object for the Return Pinned Result action? Select all that apply.

What are the components in the Direct Answer Object for the Return Pinned Result action? Select all that apply.

Wahoo - you did it! 🙌