Step 2: 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:

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:

This change eliminates the overhead of knowing when to query the ORDERS 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.

For more information, see the documentation for the Add Requests: List endpoint.

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.
3. Query Add Request: Get until status is COMPLETED or CANCELED.