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, product lists, and events that will be syndicated across Yext’s PowerListings® Network. Yext supports four types of Lists:
  • Menus,
  • Bio Lists,
  • Product Lists, and
  • Event Lists (Calendars).

Data Model Overview

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

A Location 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. Event List objects can contain only one Section (with name = "").

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 four 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 and Event Lists do not. Likewise, an Event Lists’ Item object has date fields ( starts and ends ).

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 a Location

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 Location in the Yext Knowledge Engine. Lists can be associated with (or disassociated from) a Location by sending a Location: Update request that specifies the List’s id in the corresponding List IDs field for the Location (in the case of Menus, menuIds ). So, to add the first Menu we created, you would make a request like this:

PUThttps://api.yext.com/v2/accounts/{accountId}/locations/{locationId}

{
   "menuIds": ["breakfast01"]
   "menuLabel": "Restaurant Menus"
}
If the request above is successful, you will receive a 201 response with an empty body. You can verify that the List was associated with the Location by issuing a Location: GET request. Yext will syndicate your Menu to the PowerListings® 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 PowerListings® Network and will not appear on any of your listings.

The menuLabel 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 Location, they will all appear under the same menuLabel on the publisher’s site.

To remove this Menu from the Location, you can make another Location: Update request, but this time, omit the Menu’s id from menuIds .

PUThttps://api.yext.com/v2/accounts/{accountId}/locations/{locationId}

{
   “menuIds”: []
}
As before, you will receive a 201 Success response.

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

Delete a List

It’s great that you’re able to create you own Menus, update them, and add them to Locations. 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!