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

This endpoint has no rate limit.

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

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.
`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}'