The Agreements API lets you subscribe locations to one or more SKUs, where each SKU corresponds to a single service or a collection of services. Use these endpoints to manage which services are active for a location, add new locations with services already attached, and cancel services you no longer need.
The Agreements API isn't available in Developer Accounts. Contact your Yext account team to get a Sandbox Account for testing your integration.
Retrieve Available Services
See the services available to add to the locations you manage:
GET https://api.yextapis.com/v2/accounts/me/availableservices?api_key=API_KEY&v=YYYYMMDDThe response returns the SKUs available to use. You can work with your Yext account team to understand which SKUs should be used for your particular agreement.
Retrieve Accounts
This section applies only to Partner Portal accounts.
Retrieve a complete list of accounts you have access to:
GET https://api.yextapis.com/v2/accounts?api_key=API_KEY&v=YYYYMMDDYext provisions all services at the top-level account, so use the top-level account ID when constructing calls to the other endpoints in this article.
Add Services to a New Location
Create a new location and subscribe it to one or more SKUs in a single call:
POST https://api.yextapis.com/v2/accounts/me/newlocationaddrequests?api_key=API_KEY&v=YYYYMMDDThe request body requires the following fields: newLocationId, newLocationData (including name, address, city, state, zip, phone, and categoryIds), and skus.
newLocationAccountId is the ID of the account where the new location is created. For Partner Portal accounts, this can be an existing sub-account or your main account; if the ID doesn't match an existing account, Yext creates a new one. Non-Partner Portal accounts can omit this field.
A successful request returns the new add request's id and a status of Submitted. The status transitions to Completed or Canceled within seconds if there's no potential duplicate, or to Review first if there's a potential duplicate conflict, followed by Completed or Canceled within 48 hours.
Retrieve an Add Request
Check the status of an add request:
GET https://api.yextapis.com/v2/accounts/me/addrequests/{addRequestId}?api_key=API_KEY&v=YYYYMMDDThe response includes a statusDetail field explaining the current status, including any issues such as missing or invalid data or duplicate locations.
To retrieve all add requests instead of one, omit addRequestId:
GET https://api.yextapis.com/v2/accounts/me/addrequests?api_key=API_KEY&v=YYYYMMDDThis endpoint also supports filtering by query parameters.
Add Services to an Existing Location
Add one or more SKUs to a location that already exists:
POST https://api.yextapis.com/v2/accounts/me/existinglocationaddrequests?api_key=API_KEY&v=YYYYMMDDThe request body requires existingLocationId, existingLocationAccountId, and skus (an array of the SKUs to add).
List Services
Check which services are currently provisioned for your account:
GET https://api.yextapis.com/v2/accounts/me/services?api_key=API_KEY&v=YYYYMMDDThis endpoint returns active services by default. Add a status parameter to include stopped or future services.
Cancel Services
Cancel one or more services for a location:
POST https://api.yextapis.com/v2/accounts/me/cancelservices?api_key=API_KEY&v=YYYYMMDDThe request body requires locationId and skus (an array of the SKUs to cancel). A successful request returns each canceled service with a status of STOPPED.