Migrating from v1 to v2
As part of the migration from v1 of our API to v2, you will need to reintegrate many of the API calls you make. The majority of the APIs for managing locations, retrieving analytics and listings data, managing users, and generating optimization links (a.k.a. content capture links) are the same between the two APIs. Many of the changes to these APIs involve the renaming of fields. The largest change in v2, however, is the new Administrative API.

Subscriptions replaced with Services

In the v1 API, a Location needed to be part of a Subscription before it could receive Yext services. This Subscription gave a Customer Yext’s offerings, such as PowerListings, beginning from the start date of the Subscription to its paid-through date. If a Customer canceled the Subscription, the offerings associated with the Subscription remained the same until the paid-through date. This lingering service complicated billing and made it difficult to add new services for an existing Customer.

In v2 of the API, Subscriptions are now replaced with Services. Services and Subscriptions share some similarities. In v1, specific Yext offerings were associated with a Subscription via an Offer id. In v2, the same offerings are associated with a Service with a sku ID.

However, there are a few key differences:
  1. A Service cannot be canceled until the minimum usage commitment has been met. For most Customers, this commitment is one month.
  2. A Customer stops receiving a Service the moment the Service is canceled (i.e., there is no paid-through date for a Service).
  3. There is no way to un-cancel a canceled Service. Instead, a new Service must be added to a Customer.
These differences make it easier to manage the features a Customer is receiving, and they simplify operational and billing overhead on both sides.

Consolidated API workflow

In v1 of the API, whenever a request was submitted to add a Location to a Subscription, Yext had to first check if it was a potential duplicate of a Location that already existed in the system. This check led to some delay in processing the Add Subscription request and led to two “success” responses:
  1. The Location was not a duplicate, and the location was immediately added to the Subscription, and
  2. The Location was a potential duplicate, so Yext needed to first determine whether it was indeed a duplicate before processing the Subscription.
The second response required users to query an ORDERS endpoint to learn the status of the order. The workflow is diagrammed below:

OldSubscriptionAPIV1Workflow

In v2 of the API, the workflow has been optimized and simplified. Requests to Add Service are quickly acknowledged, and all requests require querying the Add Requests: GET endpoint. This new workflow is shown below:

AdminApiWorkflowV2
This change eliminates the overhead of knowing when to query the ORDER endpoint and helps Yext process your requests faster and asynchronously. Although this change requires two API calls, the status of the order should transition as follows:
  • from PROCESSING to COMPLETED or CANCELED within a few seconds if there is no potential duplicate, or
  • from PROCESSING to REVIEW if there is a potential duplicate conflict within a few seconds, and then from REVIEW to COMPLETED and CANCELED within 48 hours.
In addition, the new API flow replaces creating customers with multiple Locations in a single API call in favor of sending individual API calls for each Location. The benefit here is you will now know which Location is marked as a potential duplicate of an existing Yext Location and can more easily control individual Location Services.

To help you better understand the changes in the API, the field mappings from v1 to v2 and the new API workflow are detailed below:

API Workflow

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

Detailed Administrative API changes

Note that in all v2 requests below, accountId is the account ID you are provisioning from. For Portal partners, this account is generally your top-level account.

1. Get Available Offers for a customer/account

Old API Request:
  • Offers List – GET https://api.yext.com/v1/offers
  • Response: List of Offers
New API Request:
  • Available Services: ListGET https://api.yext.com/v2/accounts/{accountId}/availableservices
  • Response: List of Available Services
Key Change:
  • Offer id is replaced with sku
2. Get existing customers/accounts

Old API Request:
  • Customers List – GET https://api.yext.com/v1/customers
  • Response: List of Customers
New API Request:
  • Accounts: ListGET https://api.yext.com/v2/accounts/
  • Response: List of Accounts
3. Create Customer Request with Single Location and Subscribe Location

Old API Request:
  • POST https://api.yext.com/v1/customers/
  • Response: 201 or 202 Success Response
New API Request: 4. Create Customer Request Multiple Location and Subscribe Locations

Old API Request:
  • POST https://api.yext.com/v1/customers/
  • Response: 201 or 202 Success Response
New API Request: Key Change:
  • You cannot create a multi-location account with a single API request
5. Subscribe an Existing Location

Old API Request:
  • PUT https://api.yext.com/v1/customers/customerId/subscriptions/subscriptionId/locationIds/locationId
  • Response: 201 or 202 Success Response
New API Request:
  • Multiple Add Requests: Create (Existing Location)POST https://api.yext.com/v2/accounts/{accountId}/existinglocationaddrequests
  • Note you will need to issue one call per location
  • Response: Add Service Request Object
6. Check Order Status

Old API Request:
  • GET https://api.yext.com/v1/ofers/orderId
  • Response: Order Object
New API Request:
  • Add Requests: GetGET https://api.yext.com/v2/accounts/{accountId}/addRequests/[addRequestId]
  • Response: Add Service Request Object
7. Cancel Subscription

Old API Request:
  • PUT https://api.yext.com/v1/customers/customerId/subscriptions/subscriptionId/locationIds/locationId
  • Response: 200 Response
New API Request:
  • Services: CancelPOST https://api.yext.com/v2/accounts/{accountId}/cancelservices
  • Response: List of Service Objects
8. Uncancel Subscription

Old API Request:
  • PUT https://api.yext.com/v1/customers/customerId/subscriptions/subscriptionId/locationIds
  • Response: 200 Response
New API Request:
  • This functionality is not explicitly supported in v2. Create a new Service using Add Request: Create (Existing Location).
9. Update Customer Information

Old API Request:
  • PUT https://api.yext.com/v1/customers/customerId
  • Response: 201 or 202 Success Response
New API Request:
  • Update request not supported in v2