Headline numbers

Overview

Get the totals for the period: reviews collected, response rate, average rating, average response time, and reviews awaiting a response, each with the figure for the previous period.

Use this for a dashboard header.

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

Returns the KPI values.

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/kpi

Authentication

Partner token

Only Partner tokens can call it.
Which locations are covered: store_id (one location) if sent, otherwise account_id (that account's locations), otherwise every location under your partner.
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. When sent, it's used instead of `store_id`. Max 255 characters; must be inside your tree.
`client_account_id`	string	No	Your own id for an account. When sent, it's used instead of `account_id`. 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

The payload is inside data.

Field	Type	Description
`reviews_current`	integer	Reviews dated within the range.
`reviews_previous`	integer	Reviews in the previous period: a window of the same length immediately before `range_start`.
`avg_rating`	number	Average star rating of the reviews in the range, to 2 decimals. `0` when there are none.
`avg_rating_previous`	number	Average star rating in the previous period, to 2 decimals.
`response_rate_pct`	number	Percentage of the reviews in the range that have a response, to 2 decimals. `0` when there are no reviews.
`response_rate_pct_previous`	number	The same percentage for the previous period. `0` when the previous period has no reviews.
`avg_response_time_in_days`	string	Average time to respond, in days, followed by `Days`, e.g. `"1.5 Days"`. `"0 Days"` when there are no responses.
`awaiting_response`	integer	Reviews in the range that still have no response and that the location may respond to: reviews dated on or after the location was added, plus older reviews when the location's plan includes responding to past reviews.
`reviews_sentiments`	object	How the reviews in the range split by star rating.
`reviews_sentiments.negativeReviews`	integer	Reviews rated below 3 stars. For Facebook, a review with no star rating (0) is not counted as negative.
`reviews_sentiments.negativeReviews_percent`	number	Negative reviews as a percentage of all reviews in the range, to 2 decimals. `0` when there are none.
`reviews_sentiments.positiveReviews`	integer	Reviews rated above 3 stars.
`reviews_sentiments.positiveReviews_percent`	number	Positive reviews as a percentage of all reviews in the range, to 2 decimals.
`reviews_sentiments.neutralReviews`	integer	All other reviews: rated 3, or with no star rating.
`reviews_sentiments.neutralReviews_percent`	number	Neutral reviews as a percentage of all reviews in the range, to 2 decimals.

Response payload

{
  "data": {
    "reviews_current": 580,
    "reviews_previous": 530,
    "avg_rating": 4.3,
    "avg_rating_previous": 4.1,
    "response_rate_pct": 89.66,
    "response_rate_pct_previous": 84.2,
    "avg_response_time_in_days": "1.5 Days",
    "awaiting_response": 14,
    "reviews_sentiments": {
      "negativeReviews": 50,
      "negativeReviews_percent": 8.62,
      "positiveReviews": 450,
      "positiveReviews_percent": 77.59,
      "neutralReviews": 80,
      "neutralReviews_percent": 13.79
    }
  }
}

Examples

Success payload

See Response payload.

No reviews in the range:

{
  "data": {
    "reviews_current": 0,
    "reviews_previous": 0,
    "avg_rating": 0,
    "avg_rating_previous": 0,
    "response_rate_pct": 0,
    "response_rate_pct_previous": 0,
    "avg_response_time_in_days": "0 Days",
    "awaiting_response": 0,
    "reviews_sentiments": {
      "negativeReviews": 0,
      "negativeReviews_percent": 0,
      "positiveReviews": 0,
      "positiveReviews_percent": 0,
      "neutralReviews": 0,
      "neutralReviews_percent": 0
    }
  }
}

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`	The KPI values.
`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/kpi" \
  --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}'