Headline numbers

Overview

Get the period's totals for the account: reviews, rating, response rate, response time, reviews awaiting a response, and the sentiment split.

Reviews, rating and response rate also come with the previous period's value (*_previous): the window of the same length immediately before range_start.

Use this for a dashboard header.

You'll need a token and a date range.

Returns the KPI values.

Prerequisites

A bearer token. See Authentication.
A date range (range_start, range_end), both Y-m-d H:i:s.
Optional: a location (store_id or client_location_id) or an account (account_id or client_account_id) to narrow the report.

Base URL

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

Endpoint

POST /api/v1/reports/response/kpis

Authentication

Partner or Account token

Every id you send must be inside your own account tree; otherwise 422.
Scope, in order: store_id (or client_location_id) is one location; otherwise account_id (or client_account_id) is every location of that account; otherwise every location the token can see.
An Account token normally sends only store_id; a Partner token can send account_id or client_account_id to report on one account under the partner.

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 period, `Y-m-d H:i:s` (e.g. `2026-01-01 00:00:00`). A date without a time is rejected.
`range_end`	string	Yes	End of the period, `Y-m-d H:i:s` (e.g. `2026-09-30 23:59:59`).
`store_id`	integer	No	One location to report on. Must exist and be inside your account tree. Takes priority over every other scope field.
`account_id`	integer	No	An account to report on (all its locations). Must exist and be inside your account tree. Ignored when `store_id` or `client_location_id` is sent.
`client_account_id`	string	No	Your own id for the account, instead of `account_id`. Up to 255 characters. Ignored when `account_id` is sent.
`client_location_id`	string	No	Your own id for the location, instead of `store_id`. Up to 255 characters. Ignored when `store_id` is sent.

Request payload

{
  "range_start": "2026-09-01 00:00:00",
  "range_end": "2026-09-30 23:59:59",
  "store_id": 3007
}

Response body

The payload is inside data.

Field	Type	Description
`reviews_current`	integer	Reviews in the period.
`reviews_previous`	integer	Reviews in the previous period: the window of the same length immediately before `range_start`.
`avg_rating`	number	Average star rating of the period's reviews. `0` when there are none.
`avg_rating_previous`	number	Average star rating in the previous period. `0` when there are none.
`response_rate_pct`	number	Percentage of the period's reviews that have a response of any kind. `0` when there are no reviews.
`response_rate_pct_previous`	number	The same percentage for the previous period.
`avg_response_time_in_days`	string	Average time to respond, in days, as text, e.g. `"1.2 Days"`. `"0 Days"` when there are no responses.
`awaiting_response`	integer	Reviews in the period with no response yet that the location may respond to (the review is newer than the location, or the plan covers past reviews).
`reviews_sentiments`	object	The period's reviews split into negative, positive and neutral.
`reviews_sentiments.negativeReviews`	integer	Reviews rated below 3 stars.
`reviews_sentiments.negativeReviews_percent`	number	Negative reviews as a percentage of the period's reviews.
`reviews_sentiments.positiveReviews`	integer	Reviews rated above 3 stars.
`reviews_sentiments.positiveReviews_percent`	number	Positive reviews as a percentage of the period's reviews.
`reviews_sentiments.neutralReviews`	integer	The rest: 3-star reviews, and Facebook reviews with no star rating.
`reviews_sentiments.neutralReviews_percent`	number	Neutral reviews as a percentage of the period's reviews.

Response payload

{
  "data": {
    "reviews_current": 33,
    "reviews_previous": 37,
    "avg_rating": 4.33,
    "avg_rating_previous": 4.43,
    "response_rate_pct": 0,
    "response_rate_pct_previous": 0,
    "avg_response_time_in_days": "0 Days",
    "awaiting_response": 33,
    "reviews_sentiments": {
      "negativeReviews": 2,
      "negativeReviews_percent": 6.06,
      "positiveReviews": 27,
      "positiveReviews_percent": 81.82,
      "neutralReviews": 4,
      "neutralReviews_percent": 12.12
    }
  }
}

Examples

Success payload

One location, September 2026: see Response payload.

No reviews in the period:

{
  "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 Dates 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 Date not in Y-m-d H:i:s

{
  "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 Location outside your tree

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

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."
    ]
  }
}

429 Too many requests

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

Status	Meaning
`200`	The KPI values for the period.
`401`	The token is missing, expired or invalid.
`422`	A date is missing or not `Y-m-d H:i:s`, or an 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/reports/response/kpis" \
  --header 'Authorization: Bearer <bearer-token>' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{"range_start": "2026-09-01 00:00:00", "range_end": "2026-09-30 23:59:59", "store_id": 3007}'