loading

Add Requests API Endpoints | Hitchhikers Platform

Overview

The Add Requests Administrative API endpoint group is used to manage services for sub-accounts. You can build integrations that dynamically add and remove Yext services from your sub-accounts.

To add and remove Yext location-based services such as Listings or Reviews, use the endpoints marked ‘Location’ in parentheses.


To add and remove Yext sub-account-based services, such as Answers, use the endpoints marked ‘Sub-Account’ in parentheses.

Use Cases
  • Provision services on your sub-accounts

Add Requests: Create (New Location)

Request that a new location be added and services added to it. The location is created only if the "status" field returned is "COMPLETE". In most cases, the "status" returned in the Add Request: Create response will be "SUBMITTED". For a list and explanation of each possible "status", please see the Add Requests: Get (Location) section.

To receive real-time updates on the status of your Add Request, we recommend that you configure the Add Request Update: Webhook in the Developer Console (see the Configure Webhooks guide for more information). Alternatively, use the Add Requests: Get (Location) call to determine the current Add Request "status".

path Parameters
accountId
required
string
query Parameters
v
required
string

A date in YYYYMMDD format.

Request Body schema: application/json
newLocationId
required
string

Your ID for the location to be added.

newLocationAccountId
string

(Partner Portal mode) Supply your ID for the account that the new location should be created in. If this account is your main account or an existing sub-account, the location will be placed there. Otherwise, a new account will be created.

newLocationAccountName
string

(Partner Portal mode) If a new account is created, this field's value will set the account's name. If a new account is created, and a value for this field is not provided, the new account's name will default to the location's name.

newAccountParentAccountId
string

(Partner Portal mode, advanced use only) If you have a multi-layer account structure and want the new account created for this request to be under one of your sub-accounts, rather than directly under your main account, specify that sub-account's ID in this field.

required
object

If you set newLocationId, you must specify either newLocationData or newEntityData.

This field allows you to set the profile data for a location, using our legacy format. Profile content is specified in the same format as when creating a location with the Locations: Create endpoint.

If the Add Request is processed successfully, this data will be used to create a new location in your account.

newEntityType
string
Default: "location"

If you set newEntityData, this field specifies the type of entity to be created.

required
object

If you set newLocationId, you must specify either newLocationData or newEntityData.

This field allows you to set the profile data for an entity. Profile content is specified in the same format as when creating an entity with the Entities: Create endpoint. You can only create entities of a type specified by newEntityType.

If the Add Request is processed successfully, this data will be used to create a new entity in your account.

The dropdown will specify the profile content for newEntityData. Specify the entity type with newEntityType described above.

skus
required
Array of strings

List of SKUs that you would like to sign the location up for, from among those listed in the Available Services: List response with Location recipientType.

agreementId
integer

(Advanced field) The Agreement ID of the agreement that services will be added under. This value is set automatically by Yext when you create the Add request. (You can specify it yourself, but should not do so unless you have intentionally set up multiple active agreements with Yext, since it could cause your integration to break when you renew or upgrade your agreement.)

forceReview
boolean

(Sandbox API only) Forces this Add request into the REVIEW status if it otherwise would have completed successfully.

Responses

Request samples

Content type
application/json
Example
{
  • "newLocationId": "string",
  • "newLocationAccountId": "CST-43843",
  • "newLocationAccountName": "Bill's Auto Shop",
  • "newAccountParentAccountId": "PAR-001",
  • "newLocationData": {
    },
  • "newEntityType": "atm",
  • "newEntityData": {
    },
  • "skus": [
    ],
  • "agreementId": 1588,
  • "forceReview": false
}

Response samples

Content type
application/json
{
  • "meta": {
    },
  • "response": {
    }
}

Add Requests: Create (Existing Location)

Request that one or more available services be added to an existing location.

path Parameters
accountId
required
string
query Parameters
v
required
string

A date in YYYYMMDD format.

Request Body schema: application/json
existingLocationId
required
string

ID of the location to add service for. It must already be in your account (or, if you use the Partner Portal, any of your sub-accounts).

existingLocationAccountId
string

(Partner Portal mode only) If the existingLocationId you specified is not unique among your sub-accounts, use this to specify which account the existing location is in.

skus
required
Array of strings

List of SKUs that you would like to sign the location up for, from among those listed in the Available Services: List response with Location recipientType.

agreementId
integer

(Advanced field) The Agreement ID of the agreement that services will be added under. This is set automatically by Yext when you create the add request. (You can specify it yourself, but should not do so unless you have intentionally set up multiple active agreements with Yext, since this could cause your integration to break when you renew or upgrade your agreement.)

forceReview
boolean

(Sandbox API only) Forces this add request into the REVIEW status if it otherwise would have completed successfully.

Responses

Request samples

Content type
application/json
{
  • "existingLocationId": "A48934",
  • "existingLocationAccountId": "B098329",
  • "skus": [
    ],
  • "agreementId": 1588,
  • "forceReview": false
}

Response samples

Content type
application/json
{
  • "meta": {
    },
  • "response": {
    }
}

Add Requests: Create (Existing Sub-Account)

Request that one or more available services be added (or increased in quantity) to an existing sub-account.

path Parameters
accountId
required
string
query Parameters
v
required
string

A date in YYYYMMDD format.

Request Body schema: application/json
subAccountId
required
string

The existing sub-account ID to add service to.

required
Array of objects

List of objects representing the SKUs to be added (or increased in quantity) to the sub-account, from among those listed in the Available Services: List response with Sub-Account recipientType. If the sub-account already has an active service for a SKU, the service quantity will be increased. The added quantity will default to 1 for any SKU without a specified quantity.

agreementId
integer

(Advanced field) The Agreement ID of the agreement that services will be added under. This is set automatically by Yext when you create the add request. (You can specify it yourself, but should not do so unless you have intentionally set up multiple active agreements with Yext, since this could cause your integration to break when you renew or upgrade your agreement.).

Responses

Request samples

Content type
application/json
{
  • "subAccountId": "B093879",
  • "skuAdditions": [
    ],
  • "agreementId": 1588
}

Response samples

Content type
application/json
{
  • "meta": {
    },
  • "response": {
    }
}

Add Requests: Process (Sandbox API Only)

Request that an add request in REVIEW be processed to COMPLETE, CANCELED, or FAILED. Only applicable for location add requests.

path Parameters
accountId
required
string
query Parameters
v
required
string

A date in YYYYMMDD format.

Request Body schema: application/json
addRequestId
required
integer

ID of the add request with REVIEW status

status
required
string

Action to take on the add request.

Responses

Request samples

Content type
application/json
{
  • "addRequestId": 0,
  • "status": "COMPLETE"
}

Response samples

Content type
application/json
{
  • "meta": {
    },
  • "response": { }
}

Add Requests: List (Location)

Get all of the add requests in the account that were created for locations. The response includes both New Location Add Requests and Existing Location Add Requests.

Possible status values for each add request:

  • SUBMITTED - The request has been submitted for processing. Updated status should be available soon, usually within seconds.
  • PROCESSING - The request is currently being processed. Updated status should be available soon, usually within seconds.
  • COMPLETE - The request was successfully processed and service was added. You can verify this by retrieving services for the location.
  • CANCELED - The request was purposefully canceled by Yext and was not processed. Details are available in the results field.
  • REVIEW - The request is being reviewed by Yext, most likely because this location may be a duplicate of another location already receiving this service through Yext. Once the review is complete, status will be updated to either CANCELED or COMPLETE.
  • FAILED - Processing the request failed due to a technical issue. Details may be available in the statusDetail field. No changes were made to your account, so you can try the request again.
path Parameters
accountId
required
string
query Parameters
v
required
string

A date in YYYYMMDD format.

status
string
Enum: "SUBMITTED" "PROCESSING" "COMPLETE" "CANCELED" "REVIEW" "FAILED"

Filters the list to add requests in a specific status.

submittedAfter
string <date>

(YYYY-MM-DDThh:mm:ss format)

submittedBefore
string <date>

(YYYY-MM-DDThh:mm:ss format)

updatedAfter
string <date>

(YYYY-MM-DDThh:mm:ss format)

updatedBefore
string <date>

(YYYY-MM-DDThh:mm:ss format)

sku
string
agreementId
integer
locationId
string
limit
integer <= 1000
Default: 100
offset
integer
Default: 0

Number of results to skip. Used to page through results. Cannot be used together with pageToken.

Responses

Response samples

Content type
application/json
{
  • "meta": {
    },
  • "response": {
    }
}

Add Requests: Get (Location)

Get status information about an add request that was previously created for a location.

Possible statuses:

  • SUBMITTED - The request has been submitted for processing. Updated status should be available soon, usually within seconds.
  • PROCESSING - The request is currently being processed. Updated status should be available soon, usually within seconds.
  • COMPLETE - The request was successfully processed and service was added. You can verify this by retrieving services for the location.
  • CANCELED - The request was purposefully canceled by Yext and was not processed. Details are available in the results field.
  • REVIEW - The request is being reviewed by Yext, most likely because this location may be a duplicate of another location already receiving this service through Yext. Once the review is complete, status will be updated to either CANCELED or COMPLETE.
  • FAILED - Processing the request failed due to a technical issue. Details may be available in the statusDetail field. No changes were made to your account, so you can try the request again.
path Parameters
accountId
required
string
addRequestId
required
integer

addRequestId returned from a previous call to Add Requests: Create (New Location), Add Requests: Create (Existing Location), or retrieved from Add Requests: List (Location)

query Parameters
v
required
string

A date in YYYYMMDD format.

Responses

Response samples

Content type
application/json
{
  • "meta": {
    },
  • "response": {
    }
}

Add Requests: List (Sub-Account)

Get all of the add requests in the account that were created for sub-accounts.

Possible status values for each add request:

  • SUBMITTED - The request has been submitted for processing. Updated status should be available soon, usually within seconds.
  • PROCESSING - The request is currently being processed. Updated status should be available soon, usually within seconds.
  • COMPLETE - The request was successfully processed and service was added. You can verify this by retrieving services for the sub-account.
  • CANCELED - The request was purposefully canceled by Yext and was not processed. Details are available in the results field.
  • FAILED - Processing the request failed due to a technical issue. Details may be available in the statusDetail field. No changes were made to your account, so you can try the request again.
path Parameters
accountId
required
string
query Parameters
v
required
string

A date in YYYYMMDD format.

status
string
Enum: "SUBMITTED" "PROCESSING" "COMPLETE" "CANCELED" "FAILED"

Filters the list to add requests in a specific status.

submittedAfter
string <date>

(YYYY-MM-DDThh:mm:ss format)

submittedBefore
string <date>

(YYYY-MM-DDThh:mm:ss format)

updatedAfter
string <date>

(YYYY-MM-DDThh:mm:ss format)

updatedBefore
string <date>

(YYYY-MM-DDThh:mm:ss format)

sku
string
agreementId
integer
subAccountId
string
limit
integer <= 1000
Default: 100
offset
integer
Default: 0

Number of results to skip. Used to page through results. Cannot be used together with pageToken.

Responses

Response samples

Content type
application/json
{
  • "meta": {
    },
  • "response": {
    }
}

Add Requests: Get (Sub-Account)

Get status information about an add request that was previously created for a sub-account.

Possible statuses:

  • SUBMITTED - The request has been submitted for processing. Updated status should be available soon, usually within seconds.
  • PROCESSING - The request is currently being processed. Updated status should be available soon, usually within seconds.
  • COMPLETE - The request was successfully processed and service was added. You can verify this by retrieving services for the sub-account.
  • CANCELED - The request was purposefully canceled by Yext and was not processed. Details are available in the results field.
  • FAILED - Processing the request failed due to a technical issue. Details may be available in the statusDetail field. No changes were made to your account, so you can try the request again.
path Parameters
accountId
required
string
addRequestId
required
integer

addRequestId returned from a previous call to Add Requests: Create (Existing Sub-Account) or retrieved from Add Requests: List (Sub-Account)

query Parameters
v
required
string

A date in YYYYMMDD format.

Responses

Response samples

Content type
application/json
{
  • "meta": {
    },
  • "response": {
    }
}