Overview - Policies and Conventions

API Availability

Yext APIs are organized into two groups: Management API and Content Delivery API. You’re currently viewing our Content Delivery API. For Management API documentation, visit Management API .

Content Delivery API

The Content Delivery API is used to create customer-serving experience. For example, you can use the Content Delivery API endpoints to surface entity information for any consumer-facing applications such as locators, mobile apps, email applications, in-store receipts, and more.

Specifically, you can:

Show a list of nearby locations
Inject schema.org markup onto your webpages
Build a store locator or help site search

Domain Updates

With the Access of the Spring ‘23 Release on March 22, 2023 we updated the API group names and domains. The

With this update, the Live API grouping has been updated to the Content Delivery API, and can be accessed at cdn.yextapis.com.

The new API domains are available to use as of this date, and you will see the new names reflected in the all documentation.

Environment	Old Domain	New Domain
Production	liveapi.yext.com	cdn.yextapis.com
Sandbox	sbx-liveapi.yext.com	sbx-cdn.yextapis.com

The old API domain (liveapi.yext.com) will not be deprecated, and they will continue to work for any existing integrations. Anyone setting up a new integration should do so on the new domains (cdn.yextapis.com). We also encourage anyone who is planning changes to existing integrations to update to the new domains as part of that work.

Specify Partitions

You can also optionally specify partition in addition to environment and API type. Possible values include:

us
eu

Example base URL for US and EU Partition:

Environment	Partition	Domain
Production	US	cdn.us.yextapis.com
Production	EU	cdn.eu.yextapis.com
Sandbox	US	sbx-cdn.us.yextapis.com

Capacity Requirements

Use of the Content Delivery API requires a paid subscription priced according to the relevant capacity bucket needed. This is provisioned via the Live API capacity.

Some endpoint groups in the Content Delivery API require a paid subscription in order to use them. Actions to these are provisioned via the Live API Capacity.

Management API

The Management API is used for managing Yext accounts. For example, you can use the Management API to push or pull data from the Knowledge Graph, Analytics, Reviews, or Listings in or out of Yext. You can also use it to connect Yext to your other systems and use Webhooks to keep systems in sync.

The Management API also consists of the Agreements API endpoints which can be used to manage Yext agreements in accounts and sub-accounts. For example, you can use this to build integrations that dynamically add and remove Yext services from your sub-accounts.

Specifically you can:

Sync entities into your Knowledge Graph from your source of truth system with Entities endpoints
Retrieve a list of available publishers with the Publishers endpoint
Pull your reviews into an external system with the Reviews endpoint
Create an analytics report with the Analytics endpoints

Domain Updates

With the Access of the Spring ‘23 Release on March 22, 2023 we updated the API group names and domains.

With this update, the Knowledge API grouping has been updated to the Management API, and can be accessed at api.yextapis.com.

The new API domains are available to use as of this date, and you will see the new names reflected in the all documentation.

Environment	Old Domain	New Domain
Production	api.yext.com	api.yextapis.com
Sandbox	sbx-api.yext.com	sbx-api.yextapis.com

The old API domain (api.yext.com) will not be deprecated, and they will continue to work for any existing integrations. Anyone setting up a new integration should do so on the new domains (api.yextapis.com). We also encourage anyone who is planning changes to existing integrations to update to the new domains as part of that work.

Specify Partitions

You can also optionally specify partition in addition to environment and API type. Possible values include:

us
eu

Example base URL for US and EU Partition:

Environment	Partition	Domain
Production	US	api.us.yextapis.com
Production	EU	api.eu.yextapis.com
Sandbox	US	sbx-api.us.yextapis.com

Quotas and Rate Limits

Hourly Rate Limits:

Management API: 5,000 requests per hour (with the exception of the following):
- Analytics API Endpoint Group: 1,000 requests per hour (in addition to the Management API quota)
- Agreement API Endpoint Group: 1,000 requests per hour
Content Delivery API: 100,000 requests per hour

The hourly quota window is calculated on a rolling basis. The hour starts when a user has full quota and makes their first request, and it refreshes 60 minutes later.

Webhook requests do not count towards an account’s quota.

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.

GCRA Rate Limiting:

We have burst-limiting built into our API. This means that if there are too many requests made within a short window of time, they will be rejected even if they are below the hourly limits listed above.

When a request is rejected due to GCRA rate limiting, an HTTP status code of 429 is returned, with a Yext Internal error of too_frequent_requests. Additionally, along with the response headers that Quota Rate Limiting return, when a request is rejected by GCRA, the following header is also returned: Rate-Limit-Retry-At.

API Response Headers:

Rate-Limit-Limit - The total number of requests allowed in the hourly period
Rate-Limit-Remaining - The number of allowed requests remaining in the current hourly period
Rate-Limit-Reset - The time at which the current hourly period will end and refresh the hourly quota
Rate-Limit-Retry-At - At what time requests will stop being rejected due to GCRA for the given business ID + API group

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.

Rate Limit Impacts on Apps: API requests to installed apps count towards the app owner’s quota, not the app installer’s quota.

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.yextapis.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.yextapis.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.

You should always specify a “fixed” date version parameter when building your integrations, and should never use a dynamic date. If you use a dynamic date you are continuously requesting the most recent version, and are susceptible to breakages as updates are made to our APIs.

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.

For any accounts using a subaccount structure, providing the subaccount ID in the API request while using the parent account API key will work.

Examples

This URL refers to an analytics report for all locations in account 123.

https://api.yextapis.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.yextapis.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.yextapis.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...
    }
}

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 Content Delivery API requests, all API requests are logged. API logs can be found in your Developer Console and are stored for 30 days.