Set a site's URLs and credentials

Overview

Set the review URL for a site, and optionally its landing page URL and the login credentials used for posting. This is the step that starts review collection: as soon as a URL is saved on an active location, collection is switched on and a first collection is queued.

Use this when you know the location's page on a review site. Also use it to add or change posting credentials for sites that use a username and password.

You'll need to identify the connection one of three ways: store_review_site_id, or store_id + review_site_id, or client_location_id + review_site_id. Then the url, and optionally landing_page_url (defaults to url), username, and password. A few sites need extra fields (BBB, Caring, SeniorAdvisor); the parameter table lists them.

Collection starts on your plan's schedule. Important: this call replaces the whole connection, not just the fields you send. If you call it to change a password and leave out url, the URL is cleared and collection stops. Always send the url.

Prerequisites

• A bearer token, or the invite hash from a connection link. See Authentication.
• The connection: its store_review_site_id (from List a location's review sites), or the location plus review_site_id.

Base URL

Endpoint

POST /api/v1/store-review-site/update

Authentication

Partner or Account token

• The connection must be on 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. Otherwise 422.
• client_location_id is looked up only among the locations your token can reach, so the same id can mean different locations for different partners.
• Or, with no token: send the invite hash (the token from Send the business owner a connection link) with store_review_site_id. The connection must be on the location the hash is for. The other identifiers aren't accepted with a hash.

Rate limit

30 requests per minute, counted per client IP address. See Rate limits.

Request parameters

None.

Request body

Request payload

{
  "store_review_site_id": 8782,
  "url": "https://www.yelp.com/biz/demo",
  "landing_page_url": "https://www.yelp.com/writeareview/biz/demo",
  "username": "[email protected]",
  "password": "<your-password>"
}

Response body

The payload is inside data.

Response payload

{
  "data": {
    "status": "success",
    "message": "The URL and/or password was successfully updated!"
  }
}

Examples

Success payload

See Response payload.

Error payload

422 No connection identified

{
  "message": "No review-site connection found. Provide one of: store_review_site_id, (store_id + review_site_id), or (client_location_id + review_site_id).",
  "errors": {
    "store_review_site_id": [
      "No review-site connection found. Provide one of: store_review_site_id, (store_id + review_site_id), or (client_location_id + review_site_id)."
    ]
  }
}

422 Connection outside your tree

{
  "message": "The selected store review site id does not belong to your company hierarchy.",
  "errors": {
    "store_review_site_id": [
      "The selected store review site id does not belong to your company hierarchy."
    ]
  }
}

422 Invalid values

{
  "message": "The url field must be at least 5 characters. (and 2 more errors)",
  "errors": {
    "url": [
      "The url field must be at least 5 characters.",
      "The url field must be a valid URL."
    ],
    "username": [
      "The username field must be at least 2 characters."
    ]
  }
}

429 Too many requests

{
  "message": "Too Many Attempts."
}

Example request

curl --request POST \
  --url "https://production-api.shoutaboutus.com/api/v1/store-review-site/update" \
  --header 'Authorization: Bearer <bearer-token>' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{"store_review_site_id": 8782, "url": "https://www.yelp.com/biz/demo", "landing_page_url": "https://www.yelp.com/writeareview/biz/demo", "username": "[email protected]", "password": "<your-password>"}'