Summer ’17 API Updates

Summer17APIUpdates

As a digital knowledge management provider, one of Yext’s aims is to create opportunities for developers to integrate the Yext Knowledge Engine into their organizations’ existing systems and product offerings. We’ve designed the features and improvements in the Summer ’17 Release to streamline that process and make more of Yext’s core features available via our APIs.

New Features

We’ve released the Yext App Directory and new Knowledge API endpoints for custom fields, assets, and location searches.

Resources for App Directory developers

To help app developers create and submit apps for the Yext App Directory, we’ve added an “App Directory Developers” section to this site. This section contains guides, best practices, and reference material tailored to the needs of App Directory developers.

DevPortalNewNav

We’ve moved the guides previously in the “Docs” section and the “Get Started” page formerly linked to in the top navigation to the “Clients / Partners” section. The resources in the “Docs” and “Libraries” sections remain relevant to all users of our APIs.

If you have questions about developing apps for the App Directory, contact our App Developer Support team.

Custom Fields endpoints

If you have location-specific information that is not accommodated by our current Location model, you can create Custom Fields to store that data in the Yext Knowledge Engine. With the Custom Fields endpoints in the Knowledge API, you can:

  • add custom fields to your account, along with any validation rules that should apply when updating their values via Locations: Update and Locations: Create requests
  • retrieve a list of custom fields in your account
  • update information about a custom field
  • delete custom fields from your account

Custom fields do not appear on listings across Yext’s PowerListings® Network, but they can appear on sites you’ve created with Yext Pages.

For more information on the Custom Fields endpoints, see the Knowledge API documentation.

Assets endpoints

If your locations share several of the same attributes—like a common business description or YouTube videos—you can use Assets to share content across some or all of your locations. The Assets endpoints in the Knowledge API allow you to:

  • add assets to your account and specify which locations can use them
  • retrieve a list of assets in your account
  • edit an asset, which will update that asset’s content across the locations currently using it
  • delete an asset from your account

To learn more about the Assets endpoints, see the Knowledge API documentation.

Locations: Search endpoint

We’ve added the Locations: Search endpoint to the Knowledge API, which includes the filters parameter previously found only in the Live API’s Locations: List and Locations: GeoSearch endpoints. This parameter allows you to perform searches on Location fields by creating filters with the search criteria and logic you specify.

Logic options vary by field type and include:

  • contains
  • does not contain
  • starts with
  • is equal to
  • is greater than
  • is less than
  • is greater than or equal to
  • is less than or equal to
  • is between
  • is empty
  • is not empty

For example, you can search for locations whose featuredMessage values do not contain “sale”, whose brands fields are empty, or whose closed fields are set to “true”. Searches can be performed on native Location fields and any custom fields you’ve created for your account.

More information on the Locations: Search endpoint can be found in the Knowledge API documentation.

Improvements

In addition to adding new features, we’ve made the following improvements to our APIs and the developer experience.

Alternate brands in Listings: List response

In the Listings: List response, publishers with alternate brands previously shared their publisherId values with those brands. After a recent update, any alternate brands a publisher has are returned in an alternateBrands object in the response, with each alternate brand having its own brandName and listingUrl and the primary brand retaining its publisherId value. This change makes it easier to differentiate among the listings managed by a multi-brand publisher.

For more information on the alternateBrands object, see the Knowledge API documentation.

Simplified pagination of Locations: List response

If you’re using the Yext Knowledge Engine to store data for many locations, requests to the Locations: List endpoint may span several pages. As an alternative to specifying the limit and offset parameters in your requests, you can now use the limit and pageToken parameters to paginate your results.

When there is an additional page of data to show, the nextPageToken field will be included in your response. You can pass this field’s value as the pageToken parameter in a future request to retrieve the next page of data.

To learn more about pageToken and nextPageToken, see the Knowledge API documentation.

Refined responses to Publishers: List requests

Previously, default responses to Publishers: List requests contained information about publishers relevant to an account’s country and supported Location types, regardless of whether they were included in the account’s package. With this release, publishers that are not in the account’s package are omitted from the response. A list of all publishers can still be obtained by setting the subset parameter to “ALL”.

To learn more about the Publishers: List response, see the Knowledge API documentation.

Filtering Locations by primary language

The filters parameter in the Live API’s Locations: List and Locations: GeoSearch endpoints now allow you to search for locations based on their primary language. For example, you can search for locations whose primary language is not English or for locations whose primary language is French. This “primary_language” filter is also available in Locations: Search requests in the Knowledge API.

To learn more about “primary_language” and other filter options in the Live API, see the Live API documentation.

Account information in webhook payloads and OAuth responses

Prior to this release, App Directory developers did not have a reliable method for determining the account each webhook payload was associated with. To make this process easier, we’ve added the appSpecificAccountId field to the metadata of our webhook payloads, which is unique for every (app, linked account) pairing. This ID is distinct from accountId and cannot be used in its place when sending API requests.

The appSpecificAccountId is also included in OAuth responses, along with the accountName field containing the name of the linked account.

For more information about webhook payloads, see the Webhooks documentation.

Questions?

If you would like more information about any of these features, or if you need assistance using them, please contact our API Support team.