Step 3: Update an Entity

By design, the Yext system will only update the fields you include in the Entity object and nothing else. The benefit 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:

https://api.yextapis.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"
        },
        "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 a US 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.

Coordinate Fields

Depending on the entity type, an entity might have the following Latitude/Longitude Coordinate 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 user (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, user-provided coordinates) and are read-only. The “yext” coordinates are sent to our Listings partners where applicable.