Manage Entities

Congratulations on creating a Yext app and getting started with the API. You’re about to take your first step toward creating rich and exciting applications using Yext data. So, let’s get started!

Note: If you are working with our Legacy Locations API, you can find the relevant article here.

Create an Entity

To create an Entity, you will need to make a POST request to the following URL:

POSThttps://api.yext.com/v2/accounts/me/entities?entityType=ENTITY_TYPE&api_key=API_KEY&v=YYYYMMDD

and send the Entity object as a payload. The entityType query parameter can take one of the values mentioned below:

  • atm
  • event
  • location
  • healthcareProfessional
  • healthcareFacility
  • restaurant

or the “API name” of a custom entity type in your account, e.g. “ce_myCustomEntity”. Note that not all entity types may be available for your account.

When creating an Entity, you must always provide values for the required fields for the entity type. The required fields for various entity types available in the Yext platform are given below. For custom entity types, the required fields will depend on the way they are set up in your account.

For entity types location, atm, restaurant, healthcareProfessional, and healthcareFacility:

  • name
  • address

For entity type event:

  • name
  • One of: venueName + address, linkedLocation, timeZone
  • time(start / end time)

Let’s try it out. Here’s how you create an entity of type location:

POSThttps://api.yext.com/v2/accounts/me/entities?entityType=location&api_key=API_KEY&v=YYYYMMDD

Request Body:

{
   "meta":{
      "id":"yourTestLocation"
   },
   "name":"Your Test Location",
   "address":{
      "line1":"205 Main St",
      "line2":"Suite 451",
      "city":"New York",
      "region":"NY",
      "postalCode":"10001",
      "countryCode":"US"
   },
   "mainPhone":"2125555765",
   "categoryIds":[
      "3",
      "886"
   ]
}

You should see a success message and the data of the entity returned in the response. Note that id is not required during creation and is auto-generated, but if you wish to set your own id it can be provided in the meta sub-field of the entity body (not to be confused with the meta sub-field of the response). Similarly, folderId can be provided in the meta subfield as well.

Response Body:

{
   "meta":{
      "uuid":"5718e8f2-93e8-44c0-8876-e4d51c317c46",
      "errors":[
      ]
   },
   "response":{
      "address":{
         "line1":"205 Main St",
         "line2":"Suite 451",
         "city":"New York",
         "region":"NY",
         "postalCode":"10001",
         "countryCode":"US"
      },
      "name":"Your Test Location",
      "mainPhone":"+12125555765",
      "meta":{
         "accountId":"1384669",
         "uid":"WoLjwq",
         "id":"yourTestLocation",
         "timestamp":"2019-06-25T17:15:52",
         "folderId":"0",
         "language":"en",
         "countryCode":"US",
         "entityType":"location"
      },
      "categoryIds":[
         "3",
         "886"
      ]
   }
}

Retrieve an Entity

You can also confirm the Entity was successfully created by sending this GET request with the id in the path.

GEThttps://api.yext.com/v2/accounts/me/entities/<id>?api_key=API_KEY&v=YYYYMMDD

Entity ids must be unique for each Entity within an account. An attempt to create an entity with the same id as an existing one will result in an error.

API Errors

Yext will validate all your requests and may throw errors or warnings which will be present in the meta sub-field of the response. You should ingest all errors and make changes as needed.

Update an Entity

By design, the Yext system will only update the fields you include in the Entity object and nothing else. The beauty of this approach is you only need to send fields that have changed.

Let’s try updating just the name for the first test Location you created:

PUThttps://api.yext.com/v2/accounts/me/entities/<id>?api_key=API_KEY&v=YYYYMMDD

Request Body:

{
    "name": "My Real Location"
}

You should see a success message and the body of the entity returned in the response, similar to creation of the entity:

{
    "meta": {
        "uuid": "ec630450-972a-4164-8f29-9897b731c914",
        "errors": []
    },
    "response": {
        "address": {
            "line1": "205 Main St",
            "line2": "Suite 451",
            "city": "New York",
            "region": "NY",
            "postalCode": "10001",
            "countryCode": "US"
        },
        "name": "My Real Location",
        "isoRegionCode": "NY",
        "mainPhone": "+12125555765",
        "timezone": "America/New_York",
        "yextDisplayCoordinate": {
            "latitude": 40.5102198,
            "longitude": -74.2475608
        },
        "yextRoutableCoordinate": {
            "latitude": 40.75666,
            "longitude": -73.955783
        },
        "meta": {
            "accountId": "1384669",
            "uid": "WoLjwq",
            "id": "yourTestLocation",
            "timestamp": "2019-06-25T17:43:59",
            "folderId": "0",
            "language": "en",
            "countryCode": "US",
            "entityType": "location"
        },
        "categoryIds": [
            "3",
            "886"
        ],
        "timeZoneUtcOffset": "-04:00"
    }
}

Take a moment to make a few more API calls and update more fields, and take a moment to appreciate how much you’ve managed to do using a few API calls!

Special Tips About Certain Fields

Phone Number Fields (e.g. mainPhone)

For phone number fields, if country code is not provided, the phone number is validated against the country associated with the entity. If you intend to provide a phone number that doesn’t match the entity’s country, make sure to include a country code.

Example:

If the entity’s country is US and mainPhone is provided as “2125555765”, it will be validated as a US phone number. If you wish to provide an American phone number to a non-US location, you must provide the phone number with country code, e.g. “+12125555765”.

Note that the API will always return phone numbers with country code included

Geo Fields

Depending on the entity type, an entity might have the following geo fields:

  • displayCoordinate – coordinates where the map pin for the entity should be displayed.
  • routableCoordinate – destination coordinates for driving directions to the entity
  • walkableCoordinate – destination coordinates for walking directions to the entity.
  • pickupCoordinate – coordinates for the pickup area for the entity.
  • dropoffCoordinate – coordinates for the drop-off area for the entity.

The fields above are meant to be provided by the API consumer (you). All of the above fields have “yext” counterparts, for example: yextDisplayCoordinate, yextRoutableCoordinate, yextWalkableCoordinate, yextPickupCoordinate, yextDropoffCoordinate. These are the coordinates as calculated by Yext based on various data sources (e.g. address of the entity, consumer provided coordinates) and are read-only. The “yext” coordinates are sent to our Listings partners where applicable.

Time Zone

The timeZone field is inferred from the entity’s geolocation and should not be set by the API consumer for non-custom entity types (except for the event entity type in the case where an Event does not have a location).