API Policies & Conventions
Policies and Conventions
This section gives you the basic information you need to use our APIs.
API Availability
We currently offer three APIs:
- Knowledge API
- Live API
- Administrative API
Each API is designed for a particular set of users.
To determine which APIs are available to users like you, see the “Overview” page in the Docs section of this site.
(Postman collection includes Knowledge API, Live API, and Administrative API calls.)
Authentication
All requests must be authenticated using an app’s API key via the api_key query parameter. Additionally, the API key can also be passed in as a header parameter named api-key. Note that this is slightly different from the parameter name accepted as a query param (api_key)
GET https://api.yext.com/v2/accounts/[accountId]/locations?api_key=API_KEY&v=YYYYMMDD
The API key should be kept secret.
Versioning
All requests must be versioned using the v parameter.
GET https://api.yext.com/v2/accounts/[accountId]/locations?api_key=API_KEY&v=YYYYMMDD
The v parameter (a date in YYYYMMDD format) is designed to give you the freedom to adapt to Yext API changes on your own schedule. When you pass this parameter, any backward-incompatible changes we made to the API after the specified date will not affect the behavior of the request or the content of the response. You will still benefit from any bug fixes or backward-compatible changes we may have made after the date you’ve specified.
NOTE: Yext has the ability to make changes that affect previous versions of the API, if necessary.
Serialization
API v2 only accepts data in JSON format.
Content-Type Headers
For all requests that include a request body, the Content-Type header must be included and set to application/json.
PUT Requests
Generally, all PUT operations behave as true RESTful PUTs, in which entire objects are overwritten with the provided content.
However, certain endpoints used to work with large, frequently-changing object models may have different semantics to prevent the accidental removal of content (e.g., Locations: Update lets you omit fields you don’t wish to change).
Errors and Warnings
There are three kinds of issues that can be reported for a given request:
FATAL_ERROR- An issue caused the entire request to be rejected.
NON_FATAL_ERROR- An item is rejected, but other items present in the request are accepted (e.g., one invalid Product List item).
- A field is rejected, but the item otherwise is accepted (e.g., invalid website URL in a Location).
WARNING- The request did not adhere to our best practices or recommendations, but the data was accepted anyway (e.g., data was sent that may cause some listings to become unavailable, a deprecated API was used, or we changed the format of a field’s content to meet our requirements).
Dates and Times
- We always use milliseconds since epoch (a.k.a. Unix time) for timestamps (e.g., review creation times, webhook update times).
- We always use ISO 8601 without timezone for local date times (e.g., Event start time, Event end time). Event times are always interpreted in the local timezone of their associated locations.
- Dates are transmitted as strings:
YYYY-MM-DD.
Account ID
In keeping with RESTful design principles, every URL in API v2 has an account ID prefix. This prefix helps to ensure that you have unique URLs for all resources.
In addition to specifying resources by explicit account ID, the following two macros are defined:
me- refers to the account that owns the API key sent with the requestall- refers to the account that owns the API key sent with the request, as well as all sub-accounts (recursively)
IMPORTANT: The me macro is supported in all API methods. The all macro will only be supported in certain URLs. Currently, it can only be used in Analytics, Reviews, and some Listings endpoints.
Examples
This URL refers to an analytics report for all locations in account 123.
https://api.yext.com/v2/accounts/123/analytics/reports?api_key=456&v=20160822This URL refers to an analytics report for all locations in the account that owns API key 456.
https://api.yext.com/v2/accounts/me/analytics/reports?api_key=456&v=20160822This URL refers to an analytics report for all locations in the account that owns API key 456, as well as all locations from any of its child accounts.
https://api.yext.com/v2/accounts/all/analytics/reports?api_key=456&v=20160822Actor Headers
To attribute changes to a particular user, all PUT, POST, and DELETE requests may be passed with the following headers.
NOTE: If you choose to provide actor headers, and we are unable to authenticate the request using the values you provide, the request will result in an error and fail.
- Attribute activity to customer user via username
- Header:
Yext-Username - Value: Customer user’s username
- Header:
- Attribute activity to customer user via Yext user ID
- Header:
Yext-User-Id - Value: Customer user’s Yext user ID
- Header:
Changes will be logged as follows:
- App with no designated actor
- History Entry “Updated By” Value:
App [App ID] - ‘[App Name]’ - Example:
App 432 - ‘Hello World App’
- History Entry “Updated By” Value:
- App with customer user actor
- History Entry “Updated By” Value:
[user name] ([user email]) (App [App ID] - ‘[App Name]’) - Example:
Jordan Smith (jsmith@example.com) (App 432 - ‘Hello World App’)
- History Entry “Updated By” Value:
Response Format
meta- Response metadata
meta.uuid- Unique ID for this request / response
meta.errors[]- List of errors and warnings
meta.errors[].code- Code that uniquely identifies the error or warning
meta.errors[].type- One of:
FATAL_ERRORNON_FATAL_ERRORWARNING
- See “Errors and Warnings” above for details.
- One of:
meta.errors[].message- An explanation of the issue
response- The main content (body) of the response
Example:
{
"meta": {
"uuid": "bb0c7e19-4dc3-4891-bfa5-8593b1f124ad",
"errors": [
{
"code": ...error code...,
"type": ...error, fatal error, non fatal error, or warning...,
"message": ...explanation of the issue...
}
]
},
"response": {
...results...
}
}Status Codes
200 OK- Either there are no errors or warnings, or the only issues are of type
WARNING.
- Either there are no errors or warnings, or the only issues are of type
207 Multi-Status- There are errors of type
itemErrororfieldError(but none of typerequestError).
- There are errors of type
400 Bad Request- A parameter is invalid, or a required parameter is missing. This includes the case where no API key is provided and the case where a resource ID is specified incorrectly in a path.
- This status is if any of the response errors are of type
requestError.
401 Unauthorized- The API key provided is invalid.
403 Forbidden- The requested information cannot be viewed by the acting user.
404 Not Found- The endpoint does not exist.
405 Method Not Allowed- The request is using a method that is not allowed (e.g.,
POSTwith aGET-only endpoint).
- The request is using a method that is not allowed (e.g.,
409 Conflict- The request could not be completed in its current state.
- Use the information included in the response to modify the request and retry.
429 Too Many Requests- You have exceeded your rate limit / quota.
500 Internal Server Error- Yext’s servers are not operating as expected. The request is likely valid but should be resent later.
504 Timeout- Yext’s servers took too long to handle this request, and it timed out.
Quotas and Rate Limits
Default quotas and rate limits are as follows.
- Knowledge API (includes Analytics, Listings, Knowledge Manager, Reviews, Social, and User endpoints): 5,000 requests per hour
- Analytics API: 1,000 requests per 60-minute sliding window (in addition to the Knowledge API quota)
- Administrative API: 1,000 requests per hour
- Live API: 100,000 requests per hour
With the exception of the Analytics API quota, hourly quotas are calculated from the beginning of the hour (minute zero, :00), not on a rolling basis past 60 minutes.
NOTE: Webhook requests do not count towards an account’s quota.
For the most current and accurate rate-limit usage information for a particular request type, check the Rate-Limit-Remaining and Rate-Limit-Limit HTTP headers of your API responses.
If you are currently over your limit, our API will return a 429 error, and the response object returned by our API will be empty. We will also include a Rate-Limit-Reset header in the response, which indicates when you will have additional quota.
Client- vs. Yext-assigned IDs
You can set the ID for the following objects when you create them. If you do not provide an ID, Yext will generate one for you.
- Account
- User
- Location
- Bio List
- Menu
- Product List
- Event List
- Bio List Item
- Menu Item
- Product List Item
- Event List Item
Logging
With the exception of Live API requests, all API requests are logged. API logs can be found in your Developer Console and are stored for 30 days.
Errors and Debugging — Secure Token API
Opposed to other Yext APIs, the Secure Token API does not return non-fatal errors or warnings. Because of this, error responses will never contain a valid token.
400 Errors
Invalid JSON Parameters Error
Example Error Response:
{
"body": {},
"statusCode": 400,
"error": [
{
"code": 46,
"type": 1,
"message": "Invalid/improperly formatted parameters specified in the request body"
}
]
}This error occurs when there is an issue with the JSON in the request body. A list of potential causes include:
- The body of the request contains invalid JSON.
- The body of the request is missing one or more required parameters.
- The body of the request contains one or more unknown parameters.
- The body of the request contains one or more valid parameters whose value is not the correct type.
If this error occurs, inspect the body of the request, ensuring the JSON is valid both in structure and contents. The request body should only contain the required parameters and the value for each parameter is of the correct type.
Invalid expires_in Value Error
Example Error Response:
{
"body": {},
"statusCode": 400,
"error": [
{
"code": 46,
"type": 1,
"message": "the expires_in parameter must be an integer between 60 and 1440. The expires_in parameter determines the number of minutes a token will be valid for"
}
]
}This error occurs when the value of the expires_in parameter is an integer that is not within the range of [60, 1440]. If this error occurs, check the expires_in parameter located within the request body and modify the parameter to be a valid value.
“None” Algorithm Specified Error
Example Error Response:
{
"body": {},
"statusCode": 400,
"error": [
{
"code": 46,
"type": 1,
"message": "the signing method specified cannot be 'none'"
}
]
}This error occurs when the value of the signing_algorithm parameter has been set to “none”. To ensure that the Api Tokens returned by the Secure Token Creation endpoint are secure, a valid signing algorithm must be specified. Valid values include:
- HS256
- RS256
- ES256
If this error occurs, check the signing_algorithm parameter located within the request body and ensure it is valid.
Unknown Algorithm Specified Error
Example Error Response:
{
"body": {},
"statusCode": 400,
"error": [
{
"code": 46,
"type": 1,
"message": "the signing method specified is missing or not valid"
}
]
}401 Errors
Invalid Api Key Error
Example Error Response:
{
"body": {},
"statusCode": 401,
"error": [
{
"code": 1,
"type": 1,
"message": "invalid api key"
}
]
}This error occurs when the provided API key is not a valid Yext API Key. If this error occurs, check the value of the api_key parameter in the request body.
Missing API Key
Example Error Response:
{
"body": {},
"statusCode": 401,
"error": [
{
"code": 1,
"type": 1,
"message": "missing api key"
}
]
}This error occurs when an API key is not provided in the request body. The API key cannot be provided in the query string or request header.
Insufficient Permissions Error
Example Error Response:
{
"body": {},
"statusCode": 401,
"error": [
{
"code": 1,
"type": 1,
"message": "the provided api key does not have permissions to create a token"
}
]
}This error occurs when the provided API key is a valid Yext API key but does not have the permission that enables the API key to be used to create Secure API Tokens. If this error occurs, log into your Yext account and check the app details in your Developer Console. If your app has the appropriate permissions but you are still encountering this error, please contact Yext support.
405 Errors
Method Not Allowed Error
Example Error Response:
{
"body": {},
"statusCode": 405,
"error": [
{
"code": 46,
"type": 1,
"message": "HTTP method _____ not allowed for this resource."
}
]
}This error occurs when the HTTP method of a request is not POST. If this error occurs, check to make sure you are sending a POST request.
415 Errors
Missing Content-Type Error
Example Error Response:
{
"body": {},
"statusCode": 415,
"error": [
{
"code": 6,
"type": 1,
"message": "Missing Content-Type. You must provide a content type of application/json"
}
]
}This error occurs when the Content-Type header of the request was not set. If this error occurs, set the Content-Type header to application/json and retry the request. Note that setting the request body to valid JSON does not necessarily mean the Content-Type header will be set to application/json.
Invalid Content-Type Error
Example Error Response:
{
"body": {},
"statusCode": 415,
"error": [
{
"code": 6,
"type": 1,
"message": "Invalid Content-Type ____. You must provide a content type of application/json"
}
]
}This error occurs when the Content-Type header of the request was set to a value other than application/json. If this error occurs, set the Content-Type header to application/json and retry the request.
429 Errors
Too Many Requests Error
Example Error Response:
{
"body": {},
"statusCode": 429,
"error": [
{
"code": 42,
"type": 1,
"message": "You have exceeded your hourly token creation limit"
}
]
}This error occurs when the number of requests to the CreateToken endpoint exceeds 100,000 requests within an hour. Limits are reset at the start of each hour. If you believe you are being incorrectly rate-limited, please contact Yext support.
500 Errors
Internal Server Error
Example Error Response:
{
"body": {},
"statusCode": 500,
"error": [
{
"code": 9,
"type": 1,
"message": "We had a problem with our software. Please contact support!"
}
]
}This error occurs when an issue with Yext software is interfering with the normal serving of requests or if Yext is currently experiencing a temporary service outage and service will resume shortly. If this error occurs, please contact Yext support.