I already have a Yext subscription. Do I need to create a Developer Account to use your APIs?
No, you can sign in to your existing Yext account and create an API key in your Developer Console. For more information, see our Get Started guide.
If you are an Enterprise Client interested in adding or updating locations, please contact your Account Manager before creating an API key.
If you are not able to access your Developer Console, contact your Account Manager.
I have a free account, but I'd like to use an API that requires a Yext subscription. How can I sign up?
Email firstname.lastname@example.org a member of the API Support team will help you purchase a subscription that best meets your needs.
Will you continue to support v1 of your APIs?
Yes, we plan to support v1 at least to the end of 2017. However, any new functionality we add to our APIs will be available only in v2.
I currently use v1 of your APIs. How do I upgrade to v2?
To use v2 of our APIs, go to your Developer Console, and create an app to get an API key for v2 endpoints.
You can still use v1 endpoints after you get your v2 API key. You can transition to v2 on an endpoint-by-endpoint basis or you can begin using v2 endpoints exclusively at any time.
Please note, however, that your v2 API key cannot be used to send requests to v1 endpoints and vice versa. Also, there are differences between the versions' requests and responses; attempts to upgrade by replacing "v1" with "v2" in your requests will cause your integration to fail.
For information about each endpoint in v2, see API Reference.
Will I be able to use both v1 and v2 endpoints so I can upgrade to v2 one endpoint at a time?
Yes. For example, you can use the Create Locations endpoint from v2 and the List Reviews endpoint from v1.
I have contacted the API Support team for help. When can I expect a response?
A member of the team will assist you within one business day if you have a current subscription or within seven business days if you have a free account.
How do I format a location's business hours in the API?
Our API supports the same business hour format used by Google My Business. Please visit our Knowledge Manager documentation for more information.
How is my API usage measured against my quota?
API usage is measured hourly. Hourly quotas are calculated from the beginning of the hour (minute zero, ":00"), not on a rolling basis past 60 minutes.
Can I add locations via the API without subscribing them to Yext's services?
Yes. To learn how, see our Manage Locations guide.
- Can I add and edit custom fields via the API?
Can Enterprise clients assign or unassign licences via the API?
No, we do not provide Enterprise clients with licence-management access. When clients add new locations and are API clients, Support gets an automated ticket alerting them that a new location has been added. Depending on the client's preferences, Support either assigns a licence to the new location immediately with normal SLAs, if licences are available, or asks the client's Account Manager for approval to assign a licence.
What data format does the API accept?
Our API only accepts data in JSON format.
What fields do I need to send when adding a new location?
You must send information for the following fields:
- id (Store ID)
- Location name
- categoryIds (must contain at least one category)
Note that if you do not submit a value for featuredMessage, your Featured Message will be "Call Today!" by default.
Do I use the same credentials and business ID in my sandbox account as I do in production?
No, the business ID and credentials we provide during testing are only for your sandbox account. Once you have been approved for production, we will provide new credentials and a production business ID.
Can I change my Store IDs via API?
Yes, but we must specially enable this functionality for your account. In general, we don't recommend that businesses change the IDs of their locations, as doing so will make their integrations more difficult for their IT teams to maintain.
What happens if there is an error?
Our API will return a detailed error message and response code. Please see Error Messages for more information.
Can I submit a full record for every location daily, instead of sending only the changes I've made?
You can do so if you choose; however, we recommend that you send only your changes, if possible, because we want to preserve any changes a user or Yext employee may make to correct data issues or inaccuracies.
Is there a standard testing plan for integrating with your APIs?
While plans may vary slightly, we generally require that a client test their API integration by:
- adding at least one location,
- test-closing one location and
- updating several locations.
Our Support team will provide a more detailed, customised plan at the beginning of the integration process.
Why do my GET responses contain only 50 results when my account has more?
Yext has a limit of 50 results for GET requests.
To view more results, you need to paginate your GET requests. Depending on the kind of data you are retrieving, you can use the limit and offset parameters to create pages of results or you can use pageToken parameter and nextPageToken field to automate this process. More information can be found in the documentation for each of our GET endpoints.
Why am I hitting a rate limit?
You are sending too many requests in an hour.
For current rate limits, please see the "Quotas and Rate Limits" section of our Policies and Conventions.
Do webhook requests count toward my rate limit?
No, your rate limits don't include webhook requests.
How do I know if I'm hitting the my rate limit?
We will return a 429 error message telling you that you have exceeded your rate limit.
Can I increase my rate limits?
It is not possible to increase your rate limit.
You should set your requests to throttle or sleep in order avoid hitting your rate limit.
Can you "close" locations via API?
Yes. Although we do not give clients licence-management access, you can send closed-store content to locations that are closed (i.e., update the name to “[Name] - Closed,” change all hours to "Closed," update your Featured Message and its URL, etc.). We recommend two general strategies, depending on whether you want to power the closed locations or if you want to remove closed locations from the subscription.
- Power Closed Locations: If you want to continue to power closed locations, we recommend applying all of the closed content mentioned above and setting the closed field to “true”. Please notify us when you want to remove the locations from the subscription.
- Do Not Power Closed Locations: If you want to remove closed locations from the subscription, we recommend applying all of the closed content mentioned above but do not set the closed field to “true”. We will remove the location from your subscription within one week.
What are common data-cleaning or -integrity issues that I should be aware of?
Some common issues we run into with client data are listed below. You may want to update your database accordingly before the integration.
- Data in all capital letters -- you should send all data in the proper case for all fields (exception: you can use all capital letters in your business name if that's how your legal business name is written)
- P.O. Boxes in addresses -- P.O. Boxes are not accepted by Yext, our publishers or Google
- Mall information in address or address2 fields -- this information should be in the address3 or displayAddress field.
- Invalid phone numbers (e.g., 000-000-0000 or 999-999-9999 or invalid area codes that do not correspond to the country of the location)
- Blank store IDs -- unique store IDs (id values) are a requirement for API integrations
- HTML in description
- Invalid photo URLs
- Invalid website URLs
- Setting your twitterHandle to "twitter.com/handle" -- can only be formatted as “@handle” or “handle”
- Invalid facebookPageUrl -- this URL should only be to the main page and not a sub-domain
- Geomodifiers in business name, unless it is in the legal name of the location
Do I need to send all content fields or can I apply content templates via the API?
You can apply one content template to locations during the location-creation process. We would recommend applying a template containing as much content as possible so that if you want to change a field's value (e.g., your business description or a custom field), you can do so in our platform.