Get NPS By Location

Compare Net Promoter Score and customer loyalty across locations.

get_nps_by_location

Description

Returns NPS and promoter, passive, and detractor data for each business location.

Parameters

Parameter	Type	Required	Default	Description
startDate	string	No	12 months ago when no period is requested	Start date in MM/DD/YYYY format
endDate	string	No	Today when no period is requested	End date in MM/DD/YYYY format
reviewSites	list[integer]	No	All sources	Review source IDs to include
businessNumbers	list[integer]	No	All locations	Location IDs to include
sortBy	string	No	"review-count"	Sort by "nps", "review-count", "positive-review-count", "negative-review-count", "neutral-review-count", or "name"
order	string	No	"desc"	"asc" for lowest first or "desc" for highest first
size	integer	No	25	Locations per page
page	integer	No	0	Zero-based page number

Example Usage

Which location has the worst NPS this year?

Example Response

{
  "totalCount": 120,
  "avgNpsScore": "42",
  "promoters": "62",
  "passives": "18",
  "detractors": "20",
  "dataPoints": [
    {
      "label": "Acme Dental - Downtown",
      "detractorPercentile": 15,
      "passivePercentile": 17,
      "promoterPercentile": 68,
      "npsScore": 53,
      "positiveCount": 41,
      "negativeCount": 9,
      "neutralCount": 10,
      "totalCount": 60,
      "businessNumber": 78901
    },
    {
      "label": "Acme Dental - Westlake",
      "detractorPercentile": 25,
      "passivePercentile": 18,
      "promoterPercentile": 57,
      "npsScore": 32,
      "positiveCount": 34,
      "negativeCount": 15,
      "neutralCount": 11,
      "totalCount": 60,
      "businessNumber": 78902
    }
  ],
  "totalPages": 1,
  "page": 0,
  "size": 25
}

Response Fields

The response includes account-level totalCount, avgNpsScore, promoter, passive, and detractor percentages. Each dataPoints entry contains the location label, businessNumber, npsScore, response counts, and segment percentages. Pagination is described by totalPages, page, and size.

Notes

• order uses the strings "asc" and "desc", unlike report tools that use 0 and 1.
• NPS ranges from -100 to 100.
• Choose the intended server-side sort and use the first result for best, worst, or highest-count questions.
• size was not honored in testing. Passing size: 5 still returned every location (900+ entries) with totalPages: 1 and an echoed size far larger than requested. Do not rely on size/page to bound the response on large accounts — scope with businessNumbers instead.
• When startDate/endDate are both omitted, the live API does not default to 12 months back — it returned full account history (dateDiff of ~19,900 days) in testing. Pass explicit dates for a bounded window.