Fall ’18 API Updates

NewFall18APIUpdatesImage

As part of our commitment to improving usability and value for our customers — and giving developers access to the same functionality available in the Yext dashboard — we’ve added the following features and enhancements to our APIs in the Fall ’18 Release.

New Features

We added several sets of endpoints to our APIs, along with a new webhook.

Entities endpoints and webhook

To reflect the expanded capabilities of our platform, we recently released our Entities API endpoints and an Entities webhook. As mentioned in a previous blog post, we encourage you to upgrade your integration with these endpoints, as the Location (Legacy) endpoints will not be updated to include our latest features moving forward.

For more information about managing Entities via API, refer to the Knowledge API documentation, Live API documentation, or Webhook documentation.

Google Location Verification

With this release, it is now possible to use the Knowledge API to initiate the Google My Business (GMB) verification process for locations that you have synced with Yext. The new Verification endpoints listed below allow you to manage the verification process without logging into the Yext platform.

  • Verification Methods: List
  • Verification: Initiate
  • Verification Statuses: List
  • Verification: Complete

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

Google Admin Management

In addition to initiating the GMB verification process, you can also use new endpoints in the Knowledge API to manage which users have administrative access to your GMB location information. Specifically, if you don’t see the user you’re looking for in your Listing Admins: List response, you can use the Listing Admin: Invite endpoint to send an email to that user inviting them to be an admin of the listing.

More details about the Listing Admins: List and Listing Admin: Invite endpoints can be found in the Knowledge API documentation.

Improvements

In addition to the endpoints and webhook described above, the Fall ’18 Release includes the following enhancements to our APIs.

Ability to apply profile templates via API

When creating or updating Entities via the Knowledge API, you can now use the templateId and templateFields parameters to apply profile templates to your Entities. The templateId value for a template is its “API Name,” which can be found on the Basic Info tab of its page in the Yext platform (Account Settings > Entity Templates > [Template Name]). If you want to apply only certain fields from the template specified in templateId, you can list those fields as the value of the templateFields parameter in your Entities: Create or Entities: Update request. For example, if you only wanted your Entity to have the business description and logo stored in a template, the value of your templateFields parameter would be “description,logo”. If you include a templateId value and omit templateFields, all fields from the specified template will be applied to your Entity.

More information about the templateId and templateFields parameters can be found in the Knowledge API documentation.

Enhancements to the Assets data model

To make the Assets data model more flexible, we’ve expanded the valid values of type to include the names of Custom Field Types in your account, with the sub-fields of the Asset’s value depending on the type specified. We’ve also changed the name of forLocations to forEntities and added locale and owner fields.

For more details about the Assets data model and our Assets API endpoints, see the Knowledge API documentation.

Addition of Facebook Event RSVP data to Analytics

With the addition of the “FACEBOOK_EVENT_NEW_RSVPS” metric value in the Create Reports endpoint, it is now possible to retrieve RSVP data for the events you create on Facebook. To separate the data by RSVP type (e.g., “ATTENDING”), include “FACEBOOK_RSVP_TYPE” in dimensions. You can also use the facebookRsvpType filter to retrieve data about Facebook RSVPs of a particular type.

To learn more about these and other options available to you in the Create Reports endpoint, see the Knowledge API documentation.

Ability to retrieve Entity profiles in a particular language

If you would like to retrieve Entity profiles in a particular language, you can set the new languages parameter in your Entities: List request to the two-letter code of the language you’re interested in. For example, to retrieve French Entity profiles, set the languages parameter to “fr”. The languages parameter allows you to specify multiple language codes (e.g., “fr,de” to retrieve French and German profiles). If an Entity has a profile in the one of the specified languages, the first available matching profile will be included in the response. You can also add the “primary” keyword to retrieve the primary profiles of Entities who do not have profiles in the language or languages you specify.

More information about the Entities: List endpoint can be found in the Knowledge API documentation.

Reviews and Review Invitations enhancements

We’ve made the following additions to the data model and endpoints for Reviews, as well as the Review Invitations data model:

Reviews:

  • reviewType field and parameter — The reviewType field for Facebook reviews indicates whether the review is a rating or a recommendation. (You can learn more about Facebook’s move to Recommendations on our Help site.) With the reviewType parameter, you can filter your Reviews: List responses to include only ratings or only recommendations submitted on Facebook.

  • recommendation field and parameter — Another Facebook-only field, recommendation can have a value of either “Recommended” or “Not Recommended”. The recommendation parameter in Reviews: List queries lets you retrieve Facebook reviews that either recommend or do not recommend the location being reviewed.

Review Invitations:

  • titleName field — The titleName field lets you provide a title for the invitation recipient (e.g., “Mr.”, “Mrs.”, “Miss”, etc.).

Reviews and Review Invitations:

  • transactionId field — The addition of transactionId allows you to associate a review invitation or review with the transaction being reviewed.

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.