KPI cards (partner)

Overview

Returns period-over-period KPI cards (review counts, average ratings, response rate, average response time, awaiting-response backlog, sentiment split) for the partner's review-response report.

Prerequisites

• A bearer token. Callable with Partner tokens.

Base URL

Endpoint

POST /api/v1/partner/report/review-response/kpi

Authentication

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

• Who can call it: Partner tokens.

• Mounted under the partner/report group.

• The handler hard-gates on company.bundle_id == 1 (partner only).

• Store set resolves by precedence: store_id → single store; else account_id (a bundle_id=3 account); else all of the partner-user's stores.

• account_id/store_id/client_* are all validated by an ownership check, so the partner can only reach its own tree.

Rate limit

• No rate limit.

Request body

• Body:

{
  "range_start": "2024-01-01 00:00:00",
  "range_end": "2024-12-31 23:59:59",
  "account_id": 7
}

Response

• data.reviews_current (int) — reviews in range
• data.reviews_previous (int) — reviews in equivalent prior period
• data.avg_rating (float) / avg_rating_previous (float)
• data.response_rate_pct (float) / response_rate_pct_previous (float) — responded/total × 100
• data.avg_response_time_in_days (string) — e.g. "1.5 Days"
• data.awaiting_response (int) — plan-aware backlog count
• data.reviews_sentiments (object) — positiveReviews / neutralReviews / negativeReviews counts (each with a matching *_percent)

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

{
  "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
    }
  }
}

Errors

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