Performance by review site

Overview

Get reviews and ratings broken down by site: Google, Yelp, Facebook, and so on.

Use this to see where reviews are coming from.

You'll need a partner token and a date range.

Returns one row per site.

Prerequisites

A Partner bearer token. See Authentication.
A date range: range_start and range_end, both Y-m-d H:i:s.
Optional: a store_id or account_id (or your own client_location_id / client_account_id) to narrow the report. Leave them out to cover every location under your partner.

Base URL

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

Endpoint

POST /api/v1/partner/report/review-response/by-site

Authentication

Partner token

Which locations are covered: store_id (one location) if sent, otherwise account_id (that account's locations), otherwise every location under your partner. client_location_id and client_account_id are used when store_id and account_id aren't sent.
When the user behind the token is limited to some locations, only those are covered.
Every id you send must be inside your own tree: a location or account under your partner. Anything else is rejected with 422.

Rate limit

120 requests per minute, counted per user (the token’s user). See Rate limits.

Request parameters

None.

Request body

Field	Type	Required	Description
`range_start`	string	Yes	Start of the date range, as `Y-m-d H:i:s`.
`range_end`	string	Yes	End of the date range, as `Y-m-d H:i:s`.
`store_id`	integer	No	One location to report on. Must exist and be inside your tree.
`account_id`	integer	No	One account under your partner (an account id, not a location). Must exist and be inside your tree.
`client_location_id`	string	No	Your own id for a location. Used in place of `store_id` when `store_id` isn't sent. Max 255 characters; must be inside your tree.
`client_account_id`	string	No	Your own id for an account. Used in place of `account_id` when `account_id` isn't sent. Max 255 characters; must be inside your tree.

Request payload

{
  "range_start": "2026-01-01 00:00:00",
  "range_end": "2026-09-30 23:59:59",
  "account_id": 5994
}

Response body

data is an array with one entry per review site.

Field	Type	Description
`data`	array of objects	One entry per review site that has reviews in the range, most reviews first. An empty array `[]` when there are none.
`data[].id`	integer	The review site's id (`review_site_id`).
`data[].review_site`	string	The review site's name in lower case, e.g. `google`.
`data[].review_site_logo`	string or null	URL of the site's logo.
`data[].total_reviews`	integer	Reviews from this site dated within the range.
`data[].avg_rating`	number	Average star rating of this site's rated reviews in the range, to 2 decimals.
`data[].per_of_total`	number	This site's share of all reviews in the range, as a percentage to 2 decimals.
`data[].total_response`	integer	Responses to this site's reviews in the range. Failed responses (no login saved, login error, chose not to respond) aren't counted.
`data[].per_total_response`	number	`total_response` as a percentage of `total_reviews`, to 2 decimals.

Response payload

{
  "data": [
    {
      "id": 44,
      "review_site": "google",
      "review_site_logo": "https://d2ny6zb7otrnhl.cloudfront.net/assets/backend/images/logos/google_ic.png",
      "total_reviews": 223,
      "avg_rating": 4.4,
      "per_of_total": 100,
      "total_response": 0,
      "per_total_response": 0
    }
  ]
}

Examples

Success payload

See Response payload.

No reviews in the range:

{
  "data": []
}

Error payload

422 Date range missing

{
  "message": "The range start field is required. (and 1 more error)",
  "errors": {
    "range_start": [
      "The range start field is required."
    ],
    "range_end": [
      "The range end field is required."
    ]
  }
}

422 Wrong date format

{
  "message": "The range start field must match the format Y-m-d H:i:s.",
  "errors": {
    "range_start": [
      "The range start field must match the format Y-m-d H:i:s."
    ]
  }
}

422 Account outside your tree

{
  "message": "The selected account id does not belong to your company hierarchy.",
  "errors": {
    "account_id": [
      "The selected account id does not belong to your company hierarchy."
    ]
  }
}

422 Location doesn't exist

{
  "message": "The selected store id is invalid. (and 1 more error)",
  "errors": {
    "store_id": [
      "The selected store id is invalid.",
      "The selected store id does not belong to your company hierarchy."
    ]
  }
}

429 Too many requests

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

Status	Meaning
`200`	One entry per review site, or `[]`.
`401`	The token is missing, expired or invalid.
`422`	A date is missing or not `Y-m-d H:i:s`, or `store_id`, `account_id`, `client_location_id` or `client_account_id` doesn't exist or is outside your tree.
`429`	More than 120 requests in a minute from this user.
`500`	Unexpected server error.

Example request

curl --request POST \
  --url "https://production-api.shoutaboutus.com/api/v1/partner/report/review-response/by-site" \
  --header 'Authorization: Bearer <bearer-token>' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{"range_start": "2026-01-01 00:00:00", "range_end": "2026-09-30 23:59:59", "account_id": 5994}'