Step 1: Updates in Entities API

What’s Changed?

First and foremost, calls to the Entities endpoint will have a different path than requests currently being made to the Locations endpoint. All calls made to the Entities endpoint will need to be formatted as follows:

https://api.yextapis.com/v2/accounts/{accountId}/entities

The following Entities endpoints are available, and support POST, PUT, GET, and DELETE methods:

In addition to the different URL path and new endpoints, there are some additional key differences. Here are some of the most prominent changes to be aware of:

Custom Field IDs
- Custom fields now have customer settable IDs, which will now serve as the custom field ID in the API. Unlike the Locations endpoint which requires that the immutable numeric value for the customFieldId, Entities endpoints utilize an alphanumeric string that can be set by you in your account.
- You can find the ID for a specific custom field by navigating to Content > Configuration > Fields in your account.
Custom Fields Moved Top-level
- Custom fields are now top-level fields in the Entity object, as opposed to within a customFields sub-field in the Locations API.
New Filtering Capabilities
- Filters work on almost every field, across entity types, and can be combined.
- For more information on Filters formatting and conventions, please see the Entities: List endpoint documentation, query parameters section. These filters will also work with the Entities: Geosearch and Entities: List endpoints in the Content Delivery API
Applying Templates
- Templates can now be applied via the API by providing a templateId as a query parameter. Similar to custom fields, templates have an alphanumeric ID, which will be the templateId in API requests. You can find the ID for a specific template by navigating to Content > Configuration > Templates in your account.
Entity Language Profiles: List All
- The Locations API enables the API consumer to pull all or specific language profiles for a location, but not for all locations at once. With the Entities Language Profiles: List All endpoint, the API consumer can pull language profiles for all entities in the account in one call.

The structure of Entities requests and responses has also changed from what you might be familiar with under our Locations endpoints.

New Data Structure

We’ve separated entity metadata into the “meta” object. This meta object contains information stored outside the Entity Profiles.

Example:

"meta":{
   "accountId":"00000000000000000",
   "uid":"0oavgm",
   "id":"002",
   "timestamp":"2019-02-04T19:40:01",
   "folderId":"247013",
   "language":"en",
   "countryCode":"US",
   "entityType":"location"
}

All applicable fields stored in meta:

accountId
uid
id
language
countryCode
entityType
folderId
labels
timestamp

Updates to Field Name Structure

Another exciting change comes in the form of field names and their structures. As part of this, it’s important to note that compound fields in the Yext UI will also be compound fields in the API.

Example:

{
 "address":{
      "line1":"1 Drooly Ln",
      "line2":"Apt. 1"
   }
}

This will also apply to “Custom Field Types” as well.

Omitting a sub-field of a compound field in a call does not wipe the sub-field. To wipe a field, you’ll need to pass null (no quotes). Custom fields of custom field types can be retrieved and updated using their IDs in Entities calls (This functionality is not available under the Locations endpoints, nor will it be added).

Feedback

<% elem.innerText %>