Using the Administrative API
The Administrative API provides the ability to subscribe locations to a SKU (or SKUs). Each SKUs corresponds to a single service or a collection of services. Each location can have one or more SKUs associated with them. The Administrative API gives you the tools you need to manage those associations.

This guide will walk you through the basics of how to manage your services in Yext.

NOTE: The Administrative API is not available in Developer Accounts. Please contact your Yext Account Manager in order to get a sandbox account, which you can use to test your integration with the Administrative API.

Retrieving Available Services

To see a list of the services that are available for us to add to the Locations we manage, we can make the below call:

GEThttps://api.yext.com/v2/accounts/{accountId}/availableservices?api_key=API_KEY&v=YYYYMMDD


Response Body:
{
	"meta": {
		"uuid": "3cd4cf1e-9e85-4dac-acef-f9a7a2dafd73",
		"errors": []
	},
	"response": {
		"availableServices": [{
			"sku": "SKU-00000275",
                        "serviceDescription": "Knowledge Engine Starter",
			"agreementId": "878"
		}, {
			"sku": "SKU-00000309",
                        "serviceDescription": "Knowledge Engine Professional",
			"agreementId": "878"
		}],
		"count": 2
	}
}
This request returns the SKUs that are available to use. To understand which SKUs should be used for your particular agreement, please work with your Yext Account Manager.

Retrieve Accounts

(For Partner Portal Accounts only) To retrieve a complete list of Accounts that we have access to, we can make the below call.

GEThttps://api.yext.com/v2/accounts/?api_key=API_KEY&v=YYYYMMDD


Response Body:
{
  "meta": {
    "uuid": "3e253b15-dbe1-4ac1-b082-b3bf6ba44fd1",
    "errors": []
  },
  "response": {
    "count": 3,
    "accounts": [
      {
        "accountId": "830447",
        "locationCount": 0,
        "subAccountCount": 1
      },
      {
        "accountId": "CBB-4251158",
        "locationCount": 1,
        "subAccountCount": 0,
        "parentAccountId": "830447"
      }
    ]
  }
}
All services are provisioned at the top-level account (830447 in the example above), so all calls should use the top-level account ID when constructing the URL.

Add Services (New Location)

With the available services information, we can now start adding service to locations. You can either create a new Location and add services to it in a single call, or you can issue a call to add service to a Location that may already exist. First, let’s try adding a Location and adding service in one API call. We are going to send a POST request with all the necessary Location and service information (including a SKU).

POSThttps://api.yext.com/v2/accounts/{accountId}/newlocationaddrequests?api_key=API_KEY&v=YYYYMMDD

Request Body:
{
	"newLocationAccountId": "BCC-6364487045",
	"newLocationData": {
		"address": "100 Washington Ave",
		"categoryIds": [1952],
		"city": "St. Louis",
		"countryCode": "US",
		"description": "Visit us now.",
		"featuredMessage": "Visit today.",
		"featuredMessageUrl": "http://www.gatewayarch.com/",
		"id": "BCC-6364487045",
		"isPhoneTracked": false,
		"localPhone": "",
		"locationName": "Gateway Arch",
		"phone": "3145558247",
		"state": "Missouri",
		"suppressAddress": false,
		"websiteUrl": "http://www.gatewayarch.com/",
		"zip": "63102",
		"locationType":"LOCATION"
	},
	"skus": ["SKU-00000275"],
  "newLocationId": "BCC-6364487045"
}
The newLocationAccountId is the ID of the Account in which this new Location will be created. For Partner Portal accounts, this ID could correspond to an existing sub-account or your main account. If it does not, a new Account will be created with the ID you entered. For non-Partner Portal accounts, this field can be omitted from your requests. In this case, we created a new Account since we used an accountId that didn’t exist already.

Response Body:
{
  "meta": {
    "uuid": "e3b934c9-3b41-4f65-a26d-4ac7d865ef00",
    "errors": []
  },
  "response": {
    "id": 204095,
    "locationMode": "new",
    "newLocationId": "BCC-6364487045",
    "newLocationAccountId": "BCC-6364487045",
    "newLocationData": {
      "id": "BCC-6364487045",
      "accountId": "830447",
      "locationName": "Gateway Arch",
      "address": "100 Washington Ave",
      "city": "St. Louis",
      "state": "Missouri",
      "zip": "63102",
      "countryCode": "US",
      "language": "en",
      "suppressAddress": false,
      "phone": "3145558247",
      "isPhoneTracked": false,
      "localPhone": "",
      "categoryIds": [
        "1952"
      ],
      "featuredMessage": "Visit today.",
      "featuredMessageUrl": "http://www.gatewayarch.com/",
      "websiteUrl": "http://www.gatewayarch.com/",
      "description": "Visit us now.",
      "locationType": "LOCATION"
    },
    "skus": [
      "SKU-00000275"
    ],
    "agreementId": 878,
    "status": "Submitted",
    "dateSubmitted": "2017-01-12T17:36:24",
    "dateCompleted": "",
    "statusDetail": "The request has been submitted for processing. Updated status should be available soon, usually within seconds."
  }
}

Retrieve Add Request

Our request for adding service to a new Location has gone into processing. To check on the status of that request, we can make the below call:

GEThttps://api.yext.com/v2/accounts/{accountId}/addrequests/{addRequestId}?api_key=API_KEY&v=YYYYMMDD


Response Body:
{
	"meta": {
		"uuid": "821042ea-5f0e-4aa8-95aa-ab52b89edf9f",
		"errors": []
	},
	"response": {
		"id": 204095,
		"locationMode": "new",
		"skus": ["SKU-00000275"],
		"agreementId": 878,
		"status": "Complete",
		"dateSubmitted": "2017-01-12T17:36:24",
		"dateCompleted": "2017-01-12T17:36:25",
		"statusDetail": "The request was completed and the specified services were started. Account ID BCC-6364487045 was created by this request. Location ID BCC-6364487045 was created in this request."
	}
}
The response will indicate if there are any issues with your request. Yext can block Add Service requests for various reasons, such as missing or invalid data or duplicate Locations. You can also set up a webhook to retrieve service notifications instantly rather than sending multiple requests to check the status.

You can also retrieve a list of all add requests by removing the addRequestId parameter from the call. This endpoint also allows you to do some filtering of these results based on a series of query parameters. For example:

GEThttps://api.yext.com/v2/accounts/{accountId}/addrequests?api_key=API_KEY&v=YYYYMMDD


Response Body:
{
  "meta": {
    "uuid": "2c23855c-a8b2-4042-bcbc-03d8715f0dae",
    "errors": []
  },
  "response": {
    "addRequests": [
      {
        "id": 204104,
        "locationMode": "existing",
        "skus": [
          "SKU-00000309"
        ],
        "agreementId": 878,
        "status": "Complete",
        "dateSubmitted": "2017-01-13T16:44:37",
        "dateCompleted": "2017-01-13T16:44:37",
        "statusDetail": "The request was completed and the specified services were started."
      },
      {
        "id": 204096,
        "locationMode": "new",
        "skus": [
          "SKU-00000275"
        ],
        "agreementId": 878,
        "status": "Review",
        "dateSubmitted": "2017-01-12T19:28:42",
        "dateCompleted": "",
        "statusDetail": "Yext is reviewing this request to ensure that the specified location does not already have incompatible service in another account. You do not need to take any action."
      },
      {
        "id": 204095,
        "locationMode": "new",
        "skus": [
          "SKU-00000275"
        ],
        "agreementId": 878,
        "status": "Complete",
        "dateSubmitted": "2017-01-12T17:36:24",
        "dateCompleted": "2017-01-12T17:36:25",
        "statusDetail": "The request was completed and the specified services were started. Account ID BCC-6364487045 was created by this request. Location ID BCC-6364487045 was created in this request."
      }
    ],
    "count": 3
  }
}
Please reference the documentation for more information about these filters.

Add Services (Existing Location)

If you currently have Locations in your account or sub-accounts, you can provide additional or new services to them by making the below call:

POSThttps://api.yext.com/v2/accounts/{accountId}/existinglocationaddrequests?api_key=API_KEY&v=YYYYMMDD


Request Body:
{
	"existingLocationId": "BCC-6364487045",
	"existingLocationAccountId": "BCC-6364487045",
	"skus": [
		"SKU-00000309"
	]
}
The skus array is an array of all the new services that should be added to a Location. Since we had already added “SKU-00000275” to this Location when it was created earlier, we are adding “SKU-00000309” to this existing Location.

Response Body:
{
  "meta": {
    "uuid": "c117f7f8-7850-478d-b2fc-83c8fcfa52b3",
    "errors": []
  },
  "response": {
    "id": 204104,
    "locationMode": "existing",
    "existingLocationId": "BCC-6364487045",
    "skus": [
      "SKU-00000309"
    ],
    "agreementId": 878,
    "status": "Submitted",
    "dateSubmitted": "2017-01-13T16:44:37",
    "dateCompleted": "",
    "statusDetail": "The request has been submitted for processing. Updated status should be available soon, usually within seconds."
  }
}

List Services

To check on what services are currently being provisioned through your account, you can make the below call:

GEThttps://api.yext.com/v2/accounts/{accountId}/services?api_key=API_KEY&v=YYYYMMDD


Response Body:
{
	"meta": {
		"uuid": "00dffa6b-f175-4546-bba6-9260d01eed74",
		"errors": []
	},
	"response": {
		"count": 1,
		"services": [{
			"id": 132483,
			"sku": "SKU-00000275",
			"serviceDescription": "Knowledge Engine Starter",
			"agreementId": 878,
			"locationId": "BCC-6364487045",
			"locationAccountId": "BCC-6364487045",
			"status": "ACTIVE",
			"started": "2017-01-12"
		}]
	}
}
By default, this endpoint will return all currently active services. To return any stopped or future services, add a status parameter to the URL. For more information, see the documentation for the List Services endpoint.

Cancel Services

In the event that we want to cancel all services or one service for a Location, we can make the below call:

POSThttps://api.yext.com/v2/accounts/{accountId}/cancelservices?api_key=API_KEY&v=YYYYMMDD


Request Body:
{
	"locationId": "BCC-6364487045",
	"skus": [
		"SKU-00000275"
	]
}


Response Body:
{
  "meta": {
    "uuid": "b7eaa8f9-db74-48a1-84f8-665b31e4f418",
    "errors": []
  },
  "response": [
    {
      "id": 132483,
      "sku": "SKU-00000275",
      "serviceDescription": "Knowledge Engine Starter",
      "agreementId": 878,
      "locationId": "BCC-6364487045",
      "status": "STOPPED",
      "started": "2017-01-12",
      "stopped": "2017-01-13",
      "stopOnDate": ""
    }
  ]
}