List all URLs for a location

Overview

Get the review URL and landing page URL for every site on a location in one call.

Use this to audit what's set and what's missing before a review-request campaign, or to sync URLs into your own system.

You'll need the url_type (which URL you're working on), and the store_id for one location. Without store_id, every location you can reach is listed. Use filter to see only the sites missing that URL, or only those that have it.

Returns each site with both URLs, blank where not yet set, sorted by location name and then site name, one page at a time.

Prerequisites

A bearer token. See Authentication.
Optional: the location's store_id, or the account's id (account_id).

Base URL

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

Endpoint

POST /api/v1/store-review-site/url-list

Authentication

Partner or Account token

Only locations inside your own account tree are listed. A Partner token sees every location under the partner; an Account token only its own account's locations.
A store_id or account_id outside your tree returns an empty page.

Rate limit

This endpoint has no rate limit.

Request parameters

None.

Request body

Field	Type	Required	Description
`url_type`	string	Yes	Which URL you're working on: `review_site` (the review URL) or `landing_page`. `filter` applies to it.
`filter`	string	No	`all` (default), `missing` (sites without that URL) or `completed` (sites that have it).
`page`	integer	No	The page to return, from `1`. Default `1`.
`per_page`	integer	No	Rows per page, 10–100. Default `20`. Values below 10 are raised to 10; above 100 returns `422`.
`search`	string	No	Matches part of the location name, the review site name or your `client_location_id`. Up to 255 characters.
`review_site_id`	integer	No	Only this review site. Must exist.
`account_id`	integer	No	Only this account's locations. Must exist.
`store_id`	integer	No	Only this location. Must exist.
`oauth`	string	No	Only sites that connect by signing in with the platform: `yes` (signed in) or `no` (not signed in).

Request payload

{
  "url_type": "review_site",
  "filter": "all",
  "store_id": 3007,
  "per_page": 10
}

Response body

The payload is inside data.

Field	Type	Description
`data`	array of objects	One row per site per location.
`data[].id`	integer	The connection's id (`store_review_site_id`). Use it with Set a site's URLs and credentials.
`data[].store_id`	integer	The location's id.
`data[].store_name`	string	The location's name.
`data[].client_location_id`	string or null	Your own id for the location, or `null`.
`data[].brand_id`	integer or null	The account's id.
`data[].brand_name`	string or null	The account's name.
`data[].review_site_id`	integer	The review site's id.
`data[].review_site_name`	string	The review site's name.
`data[].review_site_icon`	string	URL of the site's logo.
`data[].review_site_color`	string or null	The site's brand colour, e.g. `#d32200`.
`data[].scraping_enabled`	boolean	Whether reviews can be collected from this site.
`data[].sendto_scrapper`	string	`Y` when review collection is on for this location, `N` when it's off.
`data[].url_status`	string	`enable` or `disable`. Whether the landing page URL is used in review requests.
`data[].oauth_supported`	boolean	`true` when the site connects by signing in with the platform.
`data[].oauth_connected`	boolean	`true` when that sign-in is in place for this location. Always `false` for other sites.
`data[].review_site_url`	string or null	The review URL, or `null` when not set.
`data[].landing_page_url`	string or null	The landing page URL, or `null` when not set.
`data[].review_site_url_missing`	boolean	`true` when there's no review URL.
`data[].landing_page_url_missing`	boolean	`true` when there's no landing page URL.
`meta`	object	Paging.
`meta.current_page`	integer	This page.
`meta.per_page`	integer	Rows per page.
`meta.total`	integer	Rows across all pages.
`meta.last_page`	integer	The last page.

Response payload

{
  "data": {
    "data": [
      {
        "id": 8783,
        "store_id": 3007,
        "store_name": "Acme Coffee",
        "client_location_id": "docs-test-loc-001",
        "brand_id": 5994,
        "brand_name": "Acme Coffee",
        "review_site_id": 3,
        "review_site_name": "Facebook",
        "review_site_icon": "https://d2ny6zb7otrnhl.cloudfront.net/assets/backend/images/logos/facebook_ic.png",
        "review_site_color": "#1877F2",
        "scraping_enabled": true,
        "sendto_scrapper": "N",
        "url_status": "disable",
        "oauth_supported": true,
        "oauth_connected": false,
        "review_site_url": null,
        "landing_page_url": null,
        "review_site_url_missing": true,
        "landing_page_url_missing": true
      },
      {
        "id": 8784,
        "store_id": 3007,
        "store_name": "Acme Coffee",
        "client_location_id": "docs-test-loc-001",
        "brand_id": 5994,
        "brand_name": "Acme Coffee",
        "review_site_id": 44,
        "review_site_name": "Google",
        "review_site_icon": "https://d2ny6zb7otrnhl.cloudfront.net/assets/backend/images/logos/google_ic.png",
        "review_site_color": "#4285F4",
        "scraping_enabled": true,
        "sendto_scrapper": "Y",
        "url_status": "disable",
        "oauth_supported": true,
        "oauth_connected": false,
        "review_site_url": "https://www.google.com/maps/place/Wynyard/@-33.8648805,151.2065622,1523m/data=!3m1!1e3!4m6!3m5!1s0x6b12ae40e6fcf9eb:0x45845f7ff56e0d1!8m2!3d-33.86594!4d151.2061!16s%2Fg%2F1262gn7v0?entry=ttu&g_ep=EgoyMDI2MDkyMC4wIKXMDSoASAFQAw%3D%3D",
        "landing_page_url": "https://www.google.com/maps/place/Wynyard/@-33.8648805,151.2065622,1523m/data=!3m1!1e3!4m6!3m5!1s0x6b12ae40e6fcf9eb:0x45845f7ff56e0d1!8m2!3d-33.86594!4d151.2061!16s%2Fg%2F1262gn7v0?entry=ttu&g_ep=EgoyMDI2MDkyMC4wIKXMDSoASAFQAw%3D%3D",
        "review_site_url_missing": false,
        "landing_page_url_missing": false
      },
      {
        "id": 8782,
        "store_id": 3007,
        "store_name": "Acme Coffee",
        "client_location_id": "docs-test-loc-001",
        "brand_id": 5994,
        "brand_name": "Acme Coffee",
        "review_site_id": 1,
        "review_site_name": "Yelp",
        "review_site_icon": "https://d2ny6zb7otrnhl.cloudfront.net/assets/backend/images/logos/yelp_ic.png",
        "review_site_color": "#d32200",
        "scraping_enabled": true,
        "sendto_scrapper": "Y",
        "url_status": "disable",
        "oauth_supported": false,
        "oauth_connected": false,
        "review_site_url": null,
        "landing_page_url": null,
        "review_site_url_missing": true,
        "landing_page_url_missing": true
      }
    ],
    "meta": {
      "current_page": 1,
      "per_page": 10,
      "total": 3,
      "last_page": 1
    }
  }
}

Examples

Success payload

All the sites on one location: see Response payload.

No matching rows, or a store_id outside your tree:

{
  "data": {
    "data": [],
    "meta": {
      "current_page": 1,
      "per_page": 20,
      "total": 0,
      "last_page": 1
    }
  }
}

Error payload

422 Missing url_type

{
  "message": "The url type field is required.",
  "errors": {
    "url_type": [
      "The url type field is required."
    ]
  }
}

422 Invalid values

{
  "message": "The selected url type is invalid. (and 2 more errors)",
  "errors": {
    "url_type": [
      "The selected url type is invalid."
    ],
    "filter": [
      "The selected filter is invalid."
    ],
    "oauth": [
      "The selected oauth is invalid."
    ]
  }
}

422 per_page over 100

{
  "message": "The per page field must not be greater than 100.",
  "errors": {
    "per_page": [
      "The per page field must not be greater than 100."
    ]
  }
}

Status	Meaning
`200`	A page of rows, or an empty page.
`401`	The token is missing, expired or invalid.
`422`	`url_type` is missing, a value isn't allowed, an id doesn't exist, or `per_page` is over 100.
`500`	Unexpected server error.

Example request

curl --request POST \
  --url "https://production-api.shoutaboutus.com/api/v1/store-review-site/url-list" \
  --header 'Authorization: Bearer <bearer-token>' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{"url_type": "review_site", "filter": "all", "store_id": 3007, "per_page": 10}'

Updated 17 days ago

Did this page help you?