Overview - Policies and Conventions

API Availability

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

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
Sandbox	EU	sbx-api.eu.yextapis.com

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	us.cdn.yextapis.com
Production	EU	eu.cdn.yextapis.com
Sandbox	US	us.sbx-cdn.yextapis.com
Sandbox	EU	eu.sbx-cdn.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.

Quotas and 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.

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.

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

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