Set landing page URLs in bulk

Overview

Set the landing page URL (the deep link customers use to leave a review) for many sites on a location at once.

Use this when you're setting up review requests across a lot of locations and don't want one call per site.

You'll need the location's store_id, and each site's review_site_id paired with its landing page URL.

Landing page URLs are saved and available to your email and SMS templates. Only empty landing page URLs are filled: a site that already has one is skipped and listed in skipped, so use Set a site's URLs and credentials to change one. When the site has no review URL yet, the same URL is saved as its review URL too, and on an active location review collection is switched on.

Prerequisites

A bearer token. See Authentication.
The location's store_id and the review_site_id of each site.

Base URL

Environment	URL
Production	`https://production-api.shoutaboutus.com`
Development	`https://development-api.shoutaboutus.com`

Endpoint

POST /api/v1/store-review-site/landing-page-url/update

Authentication

Partner or Account token

store_id must be a location inside your own account tree. A Partner token reaches any location under the partner; an Account token only its own account's locations.
A location outside your tree is rejected with 422.

Rate limit

This endpoint has no rate limit.

Request parameters

None.

Request body

Field	Type	Required	Description
`store_id`	integer	Yes	The location. Must exist and be inside your account tree.
`landing_page_urls`	array of objects	Yes	At least one `{review_site_id, url}` pair.
`landing_page_urls[].review_site_id`	integer	Yes	The review site. Must exist.
`landing_page_urls[].url`	string	Yes	The landing page URL. A valid URL, up to 2048 characters.

Request payload

{
  "store_id": 3007,
  "landing_page_urls": [
    {
      "review_site_id": 1,
      "url": "https://www.yelp.com/writeareview/biz/demo"
    },
    {
      "review_site_id": 44,
      "url": "https://search.google.com/local/writereview?placeid=ChIJ123"
    }
  ]
}

Response body

The payload is inside data.

Field	Type	Description
`status`	string	`success`.
`message`	string	`Landing page URL updated successfully`
`total_updated`	integer	How many sites got a landing page URL. `0` when every entry was skipped.
`skipped`	array of objects	The entries left unchanged. Empty when none were skipped.
`skipped[].review_site_id`	integer	The review site of the skipped entry.
`skipped[].reason`	string	`already_set`: the site already has a landing page URL (this endpoint never overwrites one). `not_on_location`: the location doesn't have that review site.

Response payload

{
  "data": {
    "status": "success",
    "message": "Landing page URL updated successfully",
    "total_updated": 1,
    "skipped": [
      {
        "review_site_id": 44,
        "reason": "already_set"
      }
    ]
  }
}

Examples

Success payload

See Response payload.

Error payload

422 Missing fields

{
  "message": "The store id field is required. (and 1 more error)",
  "errors": {
    "store_id": [
      "The store id field is required."
    ],
    "landing_page_urls": [
      "The landing page urls field is required."
    ]
  }
}

422 Invalid entries or location outside your tree

{
  "message": "The selected store id does not belong to your company hierarchy. (and 2 more errors)",
  "errors": {
    "store_id": [
      "The selected store id does not belong to your company hierarchy."
    ],
    "landing_page_urls.0.review_site_id": [
      "The selected landing_page_urls.0.review_site_id is invalid."
    ],
    "landing_page_urls.0.url": [
      "The landing_page_urls.0.url field must be a valid URL."
    ]
  }
}

Status	Meaning
`200`	The URLs were saved where empty; see `total_updated` and `skipped`.
`401`	The token is missing, expired or invalid.
`422`	A field is missing or invalid, a `review_site_id` doesn't exist, or the location is outside your tree.
`500`	Unexpected server error.

Example request

curl --request POST \
  --url "https://production-api.shoutaboutus.com/api/v1/store-review-site/landing-page-url/update" \
  --header 'Authorization: Bearer <bearer-token>' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{"store_id": 3007, "landing_page_urls": [{"review_site_id": 1, "url": "https://www.yelp.com/writeareview/biz/demo"}, {"review_site_id": 44, "url": "https://search.google.com/local/writereview?placeid=ChIJ123"}]}'