To test v2 before moving to production, contact your Yext account team to request new Sandbox credentials. v1 API keys don't work in v2 integrations, so after you receive Sandbox access, create a new App to generate a v2 API key.

Most APIs for managing locations, retrieving analytics and listings data, managing users, and generating optimization links are the same between v1 and v2, with field renames in some cases. The largest change in v2 is the new Administrative API described below.

Subscriptions Replaced with Services

In v1, a location needed to be part of a subscription before it could receive Yext services. A subscription gave a customer Yext's offerings, such as Listings, from the subscription's start date to its paid-through date. If a customer canceled the subscription, its offerings remained active until the paid-through date, which complicated billing and made it difficult to add new services for an existing customer.

In v2, subscriptions are replaced with services. In v1, specific offerings were tied to a subscription through an offer id; in v2, the same offerings are tied to a service through a sku ID.

Key differences:

• A service can't be canceled until the minimum usage commitment is met (one month, for most customers).
• A customer stops receiving a service the moment it's canceled; there's no paid-through date.
• A canceled service can't be uncanceled. Add a new service instead.

Consolidated API Workflow

In v1, every request to add a location to a subscription first checked whether the location was a potential duplicate, which delayed processing and produced two possible outcomes: an immediate addition, or a duplicate check requiring a separate call to an ORDERS endpoint.

In v2, requests to add a service are acknowledged quickly, and every request requires a follow-up call to the Add Requests: Get endpoint to confirm status. This adds a call but processes requests faster and asynchronously. Status transitions as follows:

• PROCESSING to COMPLETED or CANCELED within a few seconds, if there's no potential duplicate.
• PROCESSING to REVIEW within a few seconds if there's a potential duplicate, then to COMPLETED or CANCELED within 48 hours.

v2 also replaces creating a customer with multiple locations in a single call with individual calls per location. This lets you identify which specific location is a potential duplicate and manage services per location.

API workflow:

1. If the location already exists, send an Add Requests: Create (Existing Location) request.
2. Otherwise, send an Add Requests: Create (New Location) request.
3. Query Add Requests: Get until the status is COMPLETED or CANCELED.

Detailed Endpoint Changes

accountId in all v2 requests below is the account you're provisioning from. Partner Portal accounts generally use their top-level account.