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 request
all - 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=20160822

This 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=20160822

This 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=20160822

Actor 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
Attribute activity to customer user via Yext user ID
- Header: Yext-User-Id
- Value: Customer user’s Yext user ID

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’
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’)

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_ERROR
  - NON_FATAL_ERROR
  - WARNING
- See “Errors and Warnings” above for details.
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.
207 Multi-Status
- There are errors of type itemError or fieldError (but none of type requestError).
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., POST with a GET-only endpoint).
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.