List comparison themes

Overview

Get the themes a report can compare on: service, price, quality, and so on.

Use this to let a user pick what to compare.

You'll need the store_id.

Returns the themes, each with the KPIs it scores. If the report provider can't be reached, you get the two built-in themes (home-services and food-dining) with no KPIs listed.

Prerequisites

A bearer token. See Authentication.
The location's id (store_id).

Base URL

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

Endpoint

POST /api/v1/account/competitive-report/themes

Authentication

Partner or Account token

store_id must be inside your own account tree. A Partner token can list themes for any location under the partner; an Account token only for its own locations.
A location outside your tree is rejected with 422.

Rate limit

60 requests per minute, counted per user (the token’s user). See Rate limits.

Request parameters

None.

Request body

Field	Type	Required	Description
`store_id`	integer	Yes	The location the report will be for. Must exist and be inside your account tree.

Request payload

{
  "store_id": 3007
}

Response body

The payload is inside data.

Field	Type	Description
`themes`	array	The themes you can use.
`themes[].slug`	string	The theme's id, e.g. `home-services`. Send it as `theme` in Generate a competitive report.
`themes[].label`	string	The theme's display name, e.g. `Home Services`.
`themes[].kpis`	array of strings	The KPIs the theme scores, e.g. `Service Quality`. Empty `[]` for the built-in themes returned when the report provider can't be reached.

Response payload

{
  "data": {
    "themes": [
      {
        "slug": "food-dining",
        "label": "Food Dining",
        "kpis": [
          "Customer Experience",
          "Food and Beverage",
          "Service Quality",
          "Wait Times"
        ]
      },
      {
        "slug": "home-services",
        "label": "Home Services",
        "kpis": [
          "Service Quality",
          "Communication and Responsiveness",
          "Pricing and Value",
          "Professionalism and Staff Behavior"
        ]
      },
      {
        "slug": "legal-services",
        "label": "Legal Services",
        "kpis": [
          "Communication and Responsiveness",
          "Professionalism and Trust",
          "Fees and Billing Clarity"
        ]
      },
      {
        "slug": "real-estate-multi-family",
        "label": "Property Management",
        "kpis": [
          "Maintenance and Repairs",
          "Office Staff and Communication",
          "Move-In / Move-Out and Leasing Experience"
        ]
      },
      {
        "slug": "health-medical",
        "label": "Health Medical",
        "kpis": [
          "Bedside Manner & Compassion",
          "Communication & Clarity",
          "Staff & Front-Desk Service"
        ]
      },
      {
        "slug": "car-wash",
        "label": "Car Wash",
        "kpis": [
          "Value",
          "Cleaning Results",
          "Service & Site Experience"
        ]
      },
      {
        "slug": "retail",
        "label": "Retail",
        "kpis": [
          "Helpful, Friendly Staff",
          "Clean, Well-Organized Store",
          "Fast, Accurate Checkout & Short Waits"
        ]
      },
      {
        "slug": "hospitality",
        "label": "Hospitality",
        "kpis": [
          "Service & Staff",
          "Core Offering Quality",
          "Value for Money"
        ]
      },
      {
        "slug": "entertainment",
        "label": "Entertainment",
        "kpis": [
          "Staff & Guest Service",
          "Attractions & Experience Quality",
          "Crowds, Lines & Pace",
          "Value & Add-On Pricing"
        ]
      }
    ]
  }
}

Examples

Success payload

See Response payload.

The report provider can't be reached:

{
  "data": {
    "themes": [
      {
        "slug": "home-services",
        "label": "Home Services",
        "kpis": []
      },
      {
        "slug": "food-dining",
        "label": "Food Dining",
        "kpis": []
      }
    ]
  }
}

Error payload

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 store_id missing

{
  "message": "The store id field is required.",
  "errors": {
    "store_id": [
      "The store id field is required."
    ]
  }
}

429 Too many requests

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

Status	Meaning
`200`	The themes.
`401`	The token is missing, expired or invalid.
`422`	`store_id` is missing, doesn't exist or is outside your tree.
`429`	More than 60 requests in a minute from this user.
`500`	Unexpected server error.

Example request

curl --request POST \
  --url "https://production-api.shoutaboutus.com/api/v1/account/competitive-report/themes" \
  --header 'Authorization: Bearer <bearer-token>' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{"store_id": 3007}'