Entities API Endpoints Now Available

EntitiesAPI_Blog

With the launch of Yext for Events in Summer ’18, the Yext platform has expanded beyond the Location object to other entities that reflect the structured knowledge about your businesses. As the Yext platform continues to expand, it follows that our APIs must evolve with it.

We are excited to launch our Entities API endpoints, which will support all entity types in the Yext platform, including Locations, Events, Healthcare Professional, Healthcare Facility, and ATMs. This new set of endpoints has a brand-new design that offers a variety of developer-friendly features to enable rich and robust integrations with Yext.

The new Entities API endpoints will be included in the Knowledge API as well as the Live API.

Key Features

Our Entities data model and endpoints offer the following improvements upon those currently used to store and manage Location data.

Updated Data Model and Response Structure

  • Metadata (id, entityType, folderId, etc.) is now separated from entity profile field content, offering a clear separation of data for easier consumption by developers. The following fields are included in the metadata for an entity (under the meta sub-field):
    • accountId
    • id
    • uid
    • language
    • countryCode
    • entityType
    • folderId
    • schemaTypes
    • labels
    • timestamp
  • Custom Fields are no longer in a nested customFields object. They are now top-level objects and can be referenced by their API name in the API. Customers have the opportunity to set custom fields’ API names during the field creation process.
  • The response format for data more closely matches our internal format and UI.

New Filtering Syntax

To support a more consistent developer experience, we have consolidated our API filters across data types and added the flexibility to support filtering on all fields of an entity. The new filter scheme allows us to support many more matching and filtering operations, such as and, or, greater than, less than, among others.

Improved Multi-Language API Support

The Entities endpoints make it possible to fetch multi-language profiles in bulk by all entities, as opposed to retrieving profiles for one entity at a time. We support the following methods for multi-language profiles:

  • Entity Language Profiles: Get — fetch a language profile for an entity in a specific language
  • Entity Language Profiles: List — fetch all language profiles for an entity.
  • Entity Language Profiles: Upsert — update a specific language profile for an entity
  • Entity Language Profiles: List All — fetch all language profiles for all entities (grouped by entity)

Webhook Deltas: Know What’s Changed

Webhooks are available for Create, Update and Delete events for all entity types. In addition, the webhook payload contains a changedFields attribute that conveys which fields have been changed, allowing for efficient processing on the developer side.

FAQs

I already have a Locations API integration. Do I need to rebuild it?

You are not required to rebuild any current integrations. However, we recommend to start planning to update your integration to use the new Entities endpoints. Doing so will allow you to take advantage of the new features described above, such as the ability to manage different entity types and our new filtering syntax.

Though we will continue to support the Locations endpoints for the foreseeable future, please be advised that moving forward, new features added to the Yext Knowledge Manager will be reflected only in the new Entities endpoints.

Is there an additional cost associated with the Entities API endpoints?

Absolutely not! If you were able to use the Locations endpoints before, you will be able to use the Entities endpoints. However, individual entity types available to your account will depend on your Yext subscription.