Prerequisite: To follow the steps in this guide, you must use a production account with an active Listings subscription. Otherwise, many of the requests will return empty responses.

Once you've successfully created and updated entities, you can use the Listings API to manage where those entities are published across the Yext Publisher Network. Every publisher is unique, but some common features they support include:

• Real-time updates in response to changes in the Knowledge Graph
• Display of logos, photos, menus, holiday hours, and other rich entity content
• Duplicate Suppression

Step 1: Retrieve a List of Available Publishers

Before finding out the specifics about your listings, it may be helpful to see which publishers you have access to. You can find the entity types and countries supported by each publisher in your account using the Publishers: List endpoint.

Example Request:

Example Publisher object:

{
    "id": "GOOGLEMYBUSINESS",
    "name": "Google My Business",
    "url": "google.com",
    "alternateBrands": [
        {
            "name": "Waze",
            "url": ""
        }
    ],
    "supportedCountries": [
        "AD","AE","AG","AI","AL","AM","AO","AR","AS","AT","AU","AW","AX","AZ","BA",
        "BB","BD","BE","BF","BG","BH","BI","BJ","BL","BM","BN","BO","BQ","BR","BS",
        "BT","BW","BY","BZ","CA","CF","CG","CH","CI","CL","CM","CO","CR","CV","CW",
        "CY","CZ","DE","DJ","DK","DM","DO","DZ","EC","EE","EG","ES","ET","FI","FJ",
        "FK","FM","FO","FR","GA","GB","GD","GE","GF","GG","GH","GI","GN","GP","GQ",
        "GR","GT","GU","GY","HK","HN","HR","HT","HU","ID","IE","IL","IM","IN","IQ",
        "IS","IT","JE","JM","JO","JP","KE","KH","KN","KR","KW","KY","KZ","LA","LB",
        "LC","LI","LK","LT","LU","LV","LY","MA","MC","MD","ME","MF","MG","MH","MK",
        "ML","MM","MN","MO","MP","MQ","MR","MS","MT","MU","MV","MW","MX","MY","MZ",
        "NA","NC","NE","NG","NI","NL","NO","NP","NZ","OM","PA","PE","PH","PK","PL",
        "PM","PR","PS","PT","PW","PY","QA","RE","RO","RS","RU","RW","SA","SC","SE",
        "SG","SH","SI","SK","SL","SM","SN","SR","SV","SX","TC","TD","TG","TH","TJ",
        "TL","TN","TR","TT","TW","TZ","UA","UG","US","UY","UZ","VC","VE","VG","VI",
        "VN","WF","WS","XK","YT","ZA","ZM","ZW"
    ],
    "supportedEntityTypes": [
        "LOCATION",
        "HEALTHCARE_PROFESSIONAL",
        "HEALTHCARE_FACILITY",
        "ATM",
        "RESTAURANT"
    ],
    "features": [
        "DUAL_SYNC",
        "REVIEW_MONITORING",
        "PUBLISHER_SUGGESTIONS",
        "ANALYTICS",
        "SOCIAL"
    ]
}

Things to note:

• alternateBrands — Sites that the Publisher also publishes entity data to, but Yext doesn't have a direct connection with. For example, data sent to Google will also be made available on Waze Maps.
• typicalUpdateSpeed — The expected time, in seconds, that changes to your entities will be reflected on the Publisher listing. For publishers that accept real-time updates, this will default to 120.

Step 2: Check the Status of Your Listings

Once you confirm the publishers your account contains, you can check the status of your listings using the Listings: List endpoint.

Example Request:

Example Response:

{
    "id": "187149016",
    "locationId": "{entityId}",
    "accountId": "{accountId}",
    "publisherId": "GOOGLEMYBUSINESS",
    "status": "LIVE",
    "additionalStatus": "CONNECTED",
    "listingUrl": "{URL}",
    "loginUrl": "{URL}",
    "screenshotUrl": "NO SCREENSHOT FOR PARTNER",
    "alternateBrands": [
        {
            "brandName": "Waze",
            "listingUrl": ""
        }
    ]
}

Status Types:

Things to note:

• Results are sorted first by Publisher, and then by entity.
• You can filter your results for a specific set of Publishers or entities by using the publisherIds and locationIds parameters.
• Different publishers may have unique fields returned for their status. Refer to the Listings: List documentation for more information.

Step 3: Opt In Your Entities

For listings that are opted out, you can use the Listings: Opt In endpoint to begin syncing data between the entity and the Publisher.

Example Request:

Things to note:

• You can specify a maximum of 100 [locationId, publisherId] combinations to opt in.
• If the locationIds parameter is not included, it defaults to all entities with an active Listings subscription.
• If the publisherIds parameter is not included, it defaults to all publishers available to the account.

Step 4: Opt Out Your Entities

If at any point you'd like to stop sending entity updates to a Publisher, you can use the Listings: Opt Out endpoint.

Example Request:

Things to note:

• You can specify a maximum of 100 [locationId, publisherId] combinations to opt out.
• If the locationIds parameter is not included, it defaults to all entities with an active Listings subscription.
• If the publisherIds parameter is not included, it defaults to all publishers available to the account.
• Opting out an entity does not delete its listing from the Publisher's site. When an entity is opted out, new changes made to the entity will no longer be sent to the Publisher.

Step 5: Manage Duplicate Suppression

Once a month, Yext automatically scans Publisher sites for potential duplicates of your listings. Using the Duplicate APIs, you can take action on potential duplicates and suppress them, or submit your own duplicates to be suppressed.

There are four suppression methods for resolving duplicate listings. They vary depending on the publisher, but all have the same end result of resolving duplicate listings on the publisher site.

1. Redirect: The suppressed listing URL is redirected to the correct listing.
2. Remove from Search: The suppressed listing no longer appears in search results, but navigating directly to the suppressed URL may still show the listing.
3. Search Page: The suppressed listing URL is redirected to a search for related listings.
4. Not Found: The suppressed listing URL returns a 404 error and is also removed from the publisher's search results.

Check the Status of a Duplicate

You can check the status of duplicate listings in your account using the Duplicates: List endpoint.

Example Request:

Example Response:

{
    "id": "37975024",
    "publisherId": "2FINDLOCAL",
    "locationId": "6915443573468587404",
    "url": "http://www.2findlocal.com/b/13008975/dees-doughnuts-brooklyn-ny",
    "name": "Dee's Doughnuts",
    "address": "346 Dean St.",
    "phone": "3472012419",
    "latitude": "40.683239",
    "longitude": "-73.980156",
    "status": "UNAVAILABLE",
    "suppressionType": "REDIRECT"
}

Status Types:

Note: The suppression type returned will depend on the publisher.

Suppress a Potential Duplicate Listing

To suppress a duplicate, use the Duplicates: Suppress endpoint.

Example Request:

Note: When sending requests to this endpoint, you must provide your Yext user ID in the Yext-User-Id header. This endpoint currently does not support suppression of Google duplicates.

Delete a Suppressed or Potential Duplicate Listing

If your account contains potential duplicates which are incorrect, or suppressed listings that need to be reverted, use the Duplicates: Delete endpoint.

Example Request:

Note: When sending requests to this endpoint, you must provide your Yext user ID in the Yext-User-Id header. If a duplicate has a status of SUPPRESSED when it is deleted, this will indicate to the Publisher that the suppression should be reverted.

Submit and Suppress a New Duplicate Listing

To submit a new duplicate for suppression, use the Duplicates: Create endpoint.

Example Request:

Note: When a duplicate is submitted using this method, it will automatically be assigned the status of SUPPRESSION_REQUESTED until Publisher feedback is received. This endpoint currently does not support suppression of Google duplicates.