Working with Lists
On the majority of our publisher sites, Yext can add exclusive Lists to you listings that further engage users. These Lists allow you to create customizable structured data for menus, biographies, and product lists that will be syndicated across Yext’s Knowledge Network. Yext supports three types of Lists:
  • menus (available to the location and restaurant entity types)
  • bios (available to the location, restaurant, atm, healthcareProfessional, and healthcareFacility entity types)
  • productLists (available to the location, restaurant, healthcareProfessional, and healthcareFacility entity types)
Note that the event entity type does not support the above lists.

Data Model Overview

Before exploring the API, let’s review the List data model.

An Entity may have multiple Lists of a given type. Each List object has one or more Section objects, and each Section object has one or more Item objects.

For example, you may create a Menu for a restaurant’s breakfast menu. It could have sections like “Pancakes,” “Omelettes,” and “Drinks.” In “Pancakes,” you might have items called “Buttermilk Pancakes,” “Blueberry Pancakes,” and “Strawberry Pancakes.”

We highly recommend creating Lists within the dashboard to explore all the functionality.

ListStructure

The key differences between the three types is mostly at the Item level and one or two fields at the List level. For example, Menus and Product List objects have a currencyCode and their corresponding Item objects have price fields, but Bio Lists do not.).

Create a New List

Now that we’ve covered the List model, let’s try creating a List through the API. In this guide, we will walk through creating a Menu. If you want to practice creating another List, the calls below can be substituted with the corresponding endpoint for that List type and with the minor changes needed to the request body. As noted earlier, we highly recommend creating your desired List in the dashboard first and then retrieving it (see “View an Existing List’s Data” later in this guide) so that you don’t have to construct the data model from scratch. Let’s begin!

To create a Menu, you must use the Menu: Create request. The request body will contain the Menu data.

POSThttps://api.yext.com/v2/accounts/{accountId}/menus

{
  "id": "breakfast01",
  "name": "Breakfast",
  "title": "Breakfast Menu",
  "publish": true,
  "language": "en",
  "currency": "USD",
  "sections": [
    {
      "id": "breakfastSubsection01",
      "name": "Pancakes",
      "description": "Enjoy our delicious pancake offerings",
      "items": [
        {
          "id": "pancake01",
          "name": "Buttermilk Pancakes",
          "description": "Our delicious flaky, buttermilk pancakes",
          "photo": {
            "url": "https:\/\/image.shutterstock.com\/z\/stock-photo-high-stack-of-oatmeal-pancakes-the-rustic-style-with-copy-space-shallow-dof-540640885.jpg",
            "height": 150,
            "width": 150
          },
          "calories": {
            "type": "FIXED",
            "calorie": 200
          },
          "cost": {
            "type": "PRICE",
            "price": "3.00",
            "unit": "Each"
          }
        }
      ]
    }
  ]
}
If the request is successful, you will receive a 201 response, and the response field will contain the id of the created Menu:
{
  "id": "breakfast01"
}
Try creating another Menu and changing and adding some of the fields above.

Update an Existing List

Now that you’ve created a few Lists, let’s try updating the content of the first breakfast Menu you created. To update a Menu, you must use the Menu: Update request. The request body for this request will once again contain all the Menu data. In the example below, we will add an additional item to the “Pancakes” section.

PUThttps://api.yext.com/v2/accounts/{accountId}/menus/{listId}

{
  "id": "breakfast01",
  "name": "Breakfast",
  "title": "Breakfast Menu",
  "publish": true,
  "language": "en",
  "currency": "USD",
  "sections": [
    {
      "id": "breakfastSubsection01",
      "name": "Pancakes",
      "description": "Enjoy our delicious pancake offerings",
      "items": [
        {
          "id": "pancake01",
          "name": "Buttermilk Pancakes",
          "description": "Our delicious flaky, buttermilk pancakes",
          "photo": {
            "url": "https:\/\/image.shutterstock.com\/z\/stock-photo-high-stack-of-oatmeal-pancakes-the-rustic-style-with-copy-space-shallow-dof-540640885.jpg",
            "height": 150,
            "width": 150
          },
          "calories": {
            "type": "FIXED",
            "calorie": 200
          },
          "cost": {
            "type": "PRICE",
            "price": "3.00",
            "unit": "Each"
          }
        },
        {
          "id": "pancake02",
          "name": "Blueberry Pancakes",
          "description": "Our delicious flaky, blueberry pancakes",
          "calories": {
            "type": "FIXED",
            "calorie": 275
          },
          "cost": {
            "type": "PRICE",
            "price": "3.75",
            "unit": "Each"
          }
        }
      ]
    }
  ]
}
You should receive a 200 response with the following information in the response field:
{
  "id": "breakfast01",
  “accountId”: accountId from URL,
  "name": "Breakfast",
  "title": "Breakfast Menu",
  "publish": true,
  "language": "en",
  "currency": "USD",
  “size”: 2,
  "sections": [
    {
      "id": "breakfastSubsection01",
      "name": "Pancakes",
      "description": "Enjoy our delicious pancake offerings",
      "items": [
        {
          "id": "pancake01",
          "name": "Buttermilk Pancakes",
          "description": "Our delicious flaky, buttermilk pancakes",
          "photo": {
            "url": "https:\/\/image.shutterstock.com\/z\/stock-photo-high-stack-of-oatmeal-pancakes-the-rustic-style-with-copy-space-shallow-dof-540640885.jpg",
            "height": 150,
            "width": 150
          },
          "calories": {
            "type": "FIXED",
            "calorie": 200
          },
          "cost": {
            "type": "PRICE",
            "price": "3.00",
            "unit": "Each"
          }
        },
        {
          "id": "pancake02",
          "name": "Blueberry Pancakes",
          "description": "Our delicious flaky, blueberry pancakes",
          "calories": {
            "type": "FIXED",
            "calorie": 275
          },
          "cost": {
            "type": "PRICE",
            "price": "3.75",
            "unit": "Each"
          }
        }
      ]
    }
  ]
}

View an Existing List’s Data

Sometimes, you may want to view the List data you have entered in our system already. You can see your data with a GET request for the corresponding List type. Try issuing the following Menu: GET request:

GEThttps://api.yext.com/v2/accounts/{accountId}/menus/{listId}

If the Menu exists, you will receive a 200 response with the Menu’s data returned in the response body.

Associate a List with an Entity

You’ve now created a few Menus and reviewed their data, yet you haven’t made an association between the created Menus and an existing Entity in the Yext Knowledge Engine. Lists can be associated with (or disassociated from) an Entity by sending an Entities: Update request that specifies the List’s id in the corresponding List IDs field for the Entity (in the case of Menus, menus). So, to add the first Menu we created, you would make a request like this:

PUThttps://api.yext.com/v2/accounts/{accountId}/entities/{entityId}

{
  "menus": {
      "ids": ["breakfast01"],
      "label": "Restaurant Menus"
  }
}
You can verify that the List was associated with the Entity by issuing an Entities: GET request. Yext will syndicate your Menu to the Knowledge Network if its publish field is set to true. So, if you add a List with the publish field set to false, that List will not be syndicated to the the Knowledge Network and will not appear on any of your listings.

The label sub-field contains the hyperlink text that is shown on your listings. In our example, consumers will see a button with the words “Restaurant Menus” when viewing your listing on a publisher site. When they click on the button, all of the Menus that are both published and associated with the listing’s location will be displayed.
NOTE: If you have created multiple Menus and associated them with a Entity, they will all appear under the same label on the publisher’s site.

To remove this Menu from the Entity, you can make another Entities: Update request, but this time, omit the Menu’s id from menu.ids, or provide an empty menus object.

PUThttps://api.yext.com/v2/accounts/{accountId}/entities/{entityId}

{
  “menus”: {}
}


Take a moment to add and remove a few Menus from one of your example Entities.

Delete a List

It’s great that you’re able to create you own Menus, update them, and add them to Entities. Now, to come full circle, if you would like to delete a Menu completely from the Yext Knowledge Engine at any time, you can do so with a Menu: Delete request:

DELETEhttps://api.yext.com/v2/accounts/{accountId}/menus/{listId}

You should receive a 200 Success response with an empty body.

This completes the Lists guide. Take a shot at creating a few of the other kinds of Lists. The potential uses are tremendous, and the more Lists you add, the richer your listings will be!