KPI cards (account)

Overview

Returns period-over-period KPI cards (review counts, ratings, response rate, average response time, awaiting-response, sentiment split) for the account response report. (Same route/handler as Response report — KPIs — getResponseReportKpis.)

Prerequisites

• A bearer token. Callable with Partner and Account tokens.

Base URL

Endpoint

POST /api/v1/reports/response/kpis

Authentication

• Requires a bearer token in the Authorization: Bearer <bearer-token> header.

• Who can call it: Partner and Account tokens.

• Mounted under the account-side reports/response group.

• Scope precedence: store_id (or client_location_id, then store), then single store; else account_id (or client_account_id, then account); else the auth user's tree.

• An account user passes store_id; a partner-context caller can scope to a child account via account_id/client_account_id.

• All id params are guarded by an ownership check.

Rate limit

• No rate limit.

Request body

• Body:

{
  "range_start": "2024-01-01 00:00:00",
  "range_end": "2024-12-31 23:59:59",
  "store_id": 1
}

Response

• reviews_current / reviews_previous (int)
• avg_rating / avg_rating_previous (float)
• response_rate_pct / response_rate_pct_previous (float)
• data.avg_response_time_in_days (string) — e.g. "1.2 Days"
• data.awaiting_response (int)
• data.reviews_sentiments (object) — negativeReviews, negativeReviews_percent, positiveReviews, positiveReviews_percent, neutralReviews, neutralReviews_percent

200 Success — KPI swap (2026-06) · 200

{
  "data": {
    "reviews_current": 13,
    "reviews_previous": 1,
    "avg_rating": 4.2,
    "avg_rating_previous": 2.2,
    "response_rate_pct": 84.62,
    "response_rate_pct_previous": 100.0,
    "avg_response_time_in_days": "1.2 Days",
    "awaiting_response": 2,
    "reviews_sentiments": {
      "negativeReviews": 1,
      "negativeReviews_percent": 7.69,
      "positiveReviews": 10,
      "positiveReviews_percent": 76.92,
      "neutralReviews": 2,
      "neutralReviews_percent": 15.39
    }
  }
}

Errors

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": "2024-01-01 00:00:00", "range_end": "2024-12-31 23:59:59", "store_id": 1}'