Manage Locations
Congratulations on creating a Yext app and getting started with the API. You’re about to take your first step toward helping people go places by providing accurate location data to key sites. So, let’s get started!

Create a Location

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

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

and send the Location object as a payload. When creating a Location, you must always provide values for the idnameaddresscitystatezipphone, and categoryIds fields. All other fields are optional. Remember, the id field must be unique to all Locations under your account.

Let’s try it out:

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

Request Body:
{
    "id": "TestLocation1",
    "locationName": "Your first test location",
    "address": "205 Main St",
    "city": "New York",
    "state": "NY",
    "zip": "10001",
    "countryCode": "US",
    "language": "en",
    "phone": "2125555765",
    "categoryIds": [
      "3",
      "886"
    ]
 }
You should see a success message and the id of the Location returned in the response:
{
 "meta": {
   "uuid": "3f924dc9-b3ba-4561-aa70-93add5c2c0e3",
   "errors": []
 },
 "response": {
   "id": "TestLocation1"
 }
}

Retrieve a Location

You can also confirm the Location was successfully created by sending this GET request:

GEThttps://api.yext.com/v2/accounts/me/locations/TestLocation1?api_key=API_KEY&v=YYYYMMDD

You should receive a response similar to the one below.
{
 "meta": {
   "uuid": "664ad06d-51d3-46d6-aaef-dd0c41a383ee",
   "errors": []
 },
 "response": {
   "id": "TestLocation1",
   "timestamp": 1476299272562,
   "accountId": "469411",
   "locationName": "Your first test location",
   "address": "205 Main St",
   "city": "New York",
   "state": "NY",
   "zip": "10001",
   "countryCode": "US",
   "language": "en",
   "suppressAddress": false,
   "phone": "2125555765",
   "isPhoneTracked": false,
   "categoryIds": [
     "3",
     "886"
   ],
   "featuredMessage": "Call Today",
   "folderId": "0",
   "locationType": "LOCATION"
 }
}

Try creating a second Location using the same id. You should receive this error:
{
 "meta": {
   "uuid": "34ad7bfd-ecc2-4e8c-8ecb-23f7e743cced",
   "errors": [
     {
       "code": 2017,
       "type": "FATAL_ERROR",
       "message": "Location with id TestLocation1 already exists"
     }
   ]
 },
 "response": {}
}
Location ids must be unique for each Location. The code above shows an example of a FATAL_ERROR.

API Errors

Yext will validate all your requests and may throw one of three types of errors: FATAL_ERROR, NON_FATAL_ERROR, and WARNING errors. You should ingest all errors and make changes as needed.

FATAL_ERRORs will prevent any part of the API request from being processed. Using a duplicate Location id is an example of a FATAL_ERROR. All FATAL_ERRORs must be resolved before the request can be processed. To fix the FATAL_ERROR in the example, change the id in you request and try sending it again.

NON_FATAL_ERRORs are errors that cause us to reject an object in a list or a field in an object. Whether or not we reject the entire request as a result depends on whether the request’s validation is strict or lenient.

Because the default validation mode is strict, NON_FATAL_ERRORs and FATAL_ERRORs will cause an API request to fail if no validation value is set. You can change the validation mode to lenient by adding validation=lenient as a parameter to the API request URL. In this mode, FATAL_ERRORs will prevent an API request from being processed but NON_FATAL_ERRORs will not. For example, you can send us a list of Menus for some Locations. If the validation mode is set to lenient, and there is a NON_FATAL_ERROR in one Menu, we will not store that Menu, but we will store the others. If the validation mode is set to strict, the entire request will be rejected, and no Menus will be stored. We recommend using validation=lenient for production and validation=strict for testing and R&D efforts.

The last error type is WARNING. WARNINGs are thrown when a field passes Yext’s validation, but the content is flagged as potential bad data that our publishers will not accept. WARNINGs will not prevent an API request from being processed.

In lenient mode, WARNINGs and NON_FATAL_ERRORs will be indicated in the errors list in the meta section, but we will still complete as much of the request as possible.

Update a Location

You’ve managed to successfully create a Location, but now you may want to update existing fields you’ve previously set or add content for new fields. To do so, you will need to make the following PUT request:

PUThttps://api.yext.com/v2/accounts/me/locations/TestLocation1?api_key=API_KEY&v=YYYYMMDD

and send the Location object as a payload.

By design, the Yext system will only update the fields you include in the Location 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 Featured Message for the first test Location you created:

PUThttps://api.yext.com/v2/accounts/me/locations/TestLocation1?api_key=API_KEY&v=YYYYMMDD

Request Body:
{
    "featuredMessage": "Come in for some great deals!"
}
You should see a success message and the id of the location returned in the response:
{
 "meta": {
   "uuid": "5ac9cdc5-e0c6-4de4-b4da-e99ffef027fb",
   "errors": []
 },
 "response": {
   "id": "TestLocation1"
 }
}
Issue another Get Locations request and inspect how only the Featured Message was updated and the other fields did not change.

Let’s try updating the featuredMessage field and provide new content for the tollFreePhone, hours, and holidayHours fields. For your reference, this location’s business hours are below.
  • Sunday: Open 24 Hours a Day
  • Monday: 9:00 AM to 12:00 PM and 2:00 AM to 5:00 PM
  • Tuesday: 9:00 AM to 5:00 PM
  • Wednesday: Closed
  • Thursday: 9:00 AM to 5:00 PM
  • Friday: 9:00 AM to 5:00 PM
  • Saturday: 10:00 AM to 4:00 PM
This location has different hours on some holidays:
  • November 26, 2020: 9:00 AM to 3:00 PM
  • November 27, 2020: Open 24 Hours a Day
  • December 24, 2020: 9:00 AM to 6:00 PM
  • December 25, 2020: Closed
  • January 1, 2021: Regular Hours
PUThttps://api.yext.com/v2/accounts/me/locations/TestLocation1?api_key=API_KEY&v=YYYYMMDD

Request Body:
{
    "featuredMessage": "Come on by and see our updates!!",
    "tollFreePhone": 8008735209,
    "hours": "1:00:00:00:00,2:9:00:12:00,2:14:00:17:00,3:9:00:17:00,4:closed,5:9:00:17:00,6:9:00:17:00,7:10:00:16:00",
    "holidayHours": [
        {
            "date": "2020-11-26",
            "hours": "9:00:15:00",
            "isRegularHours": false
        },
        {
            "date": "2020-11-27",
            "hours": "0:00:0:00",
            "isRegularHours": false
        },
        {
            "date": "2020-12-24",
            "hours": "9:00:18:00",
            "isRegularHours": false
        },
        {
            "date": "2020-12-25",
            "hours": "",
            "isRegularHours": false
        },
        {
            "date": "2021-01-01",
            "isRegularHours": true
        }
    ]
}
As before, the response body will contain the id of the location.
{
 "meta": {
   "uuid": "2d56b310-f4ba-4648-a447-395a3cdba67f",
   "errors": []
 },
 "response": {
   "id": "TestLocation1"
 }
}
Lastly, let’s mark your location as closed. To do this, append “- Closed” to your locationName, set all the hours to closed, and set isClosed to true. You can optionally set closeDate. Let’s look at the example below.

PUThttps://api.yext.com/v2/accounts/me/locations/TestLocation1?api_key=API_KEY&v=YYYYMMDD

Request Body:
{
    "locationName": "Test Location - Closed",
    "closed": {
        "isClosed": true,
        "closeDate": "2025-09-29"
    },
    "hours": "1:closed"
}

Feel free 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!