Lifetime reviews by site

Overview

Get all-time review totals by site, not limited to a period. Each row also has the review count and rating for the date range you send.

Use this for a big-picture view.

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

Returns totals 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 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-publisher

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.
This endpoint doesn't use client_location_id or client_account_id to choose locations; they're only checked. Send store_id or account_id.
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	Checked (max 255 characters, must be inside your tree) but not used by this endpoint. Send `store_id` instead.
`client_account_id`	string	No	Checked (max 255 characters, must be inside your tree) but not used by this endpoint. Send `account_id` instead.

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 with reviews, most lifetime reviews first. Sites with no reviews at all are left out. 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 display name, e.g. `Google`.
`data[].review_site_logo`	string	URL of the site's logo.
`data[].review_site_color`	string or null	The site's brand colour as a hex code, e.g. `#4285F4`, or `null` when none is set.
`data[].total_reviews`	integer	Lifetime total: the site's own count where it has been synced, otherwise the number of reviews we hold. Not limited to the date range.
`data[].overall_rating`	number or null	Lifetime rating: the site's own rating, weighted by each location's review count, or the average of the reviews we hold when the site's rating isn't synced. `null` when there's no rating.
`data[].period_reviews`	integer	Reviews from this site dated within the range.
`data[].period_rating`	number or null	Average star rating of this site's rated reviews in the range, to 2 decimals. `null` when there are none.

Response payload

{
  "data": [
    {
      "id": 44,
      "review_site": "Google",
      "review_site_logo": "https://d2ny6zb7otrnhl.cloudfront.net/assets/backend/images/logos/google_ic.png",
      "review_site_color": "#4285F4",
      "total_reviews": 684,
      "overall_rating": 4.2,
      "period_reviews": 223,
      "period_rating": 4.4
    }
  ]
}

Examples

Success payload

See Response payload.

No reviews at all:

{
  "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-publisher" \
  --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}'