List an account's locations

Overview

Get the locations the calling user can access, with full address, account, plan and plan features, and a ready-made link to each location's connection page.

Use this from an account's point of view: the locations a business owner or their staff can see. Partners use it when acting on behalf of an account, by sending the account's company_id.

You'll need an account token (or a partner token acting as the account). Results are paginated.

Returns one entry per accessible location, including its connect_page_url for sending to the owner.

Prerequisites

A Partner or Account token. See Authentication.
Optional: the account's id (company_id), or one 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/store/list

Authentication

Partner or Account token

With no ids, the list is the locations the user behind the token can access.
company_id (or account_id) lists that company's locations; store_id returns just that location.
company_id, account_id and store_id must be inside your own account tree; otherwise 422. A Partner token reaches any location under the partner, an Account token only its own account's locations.

Rate limit

This endpoint has no rate limit.

Request parameters

Parameter	In	Type	Required	Description
`page`	query	integer	No	Page number. Default 1.

Request body

All fields are optional.

Field	Type	Required	Description
`sort_field`	string	No	`store_name` (default), `address`, `zip`, `city_name`, `state_code`, `company_phone`, `country_name`, `state_name`, `storeid` or `account_name`.
`sort_by`	string	No	`asc` or `desc` (either case). Default `ASC`.
`search_field`	string	No	The field to search: any of the `sort_field` values. Use with `search_value`.
`search_value`	string	No	The text to search for. No `<` or `>`. `zip` and `state_code` need an exact match; `company_phone`, `country_name`, `state_name` and `city_name` match from the start; the others match any part.
`active_plan`	integer	No	`1` to list only locations on an active plan.
`company_id`	integer	No	List this company's locations: an account, a location, or your partner. Must be inside your account tree.
`account_id`	integer	No	Same as `company_id`, for an account only. `company_id` wins when you send both.
`store_id`	integer	No	Return only this location. Must be inside your account tree.
`limit`	integer	No	Page size, 10 to 100. Default 10. Values below 10 are raised to 10; above 100 returns `422`.

Request payload

{
  "sort_field": "store_name",
  "sort_by": "ASC",
  "search_field": "store_name",
  "search_value": "SAU",
  "active_plan": 1,
  "company_id": 5994,
  "limit": 10
}

Response body

The payload is inside data, as a page of results.

Field	Type	Description
`current_page`	integer	The page number.
`data`	array	The locations on this page.
`data[].id`	integer	The location's id (`store_id`).
`data[].account_name`	string	The account's name.
`data[].store_name`	string	The location's name.
`data[].store_full_name`	string	The name, plus `- <client_location_id>` (or `- <storeid>` when it has no `client_location_id`).
`data[].storeid`	string	The location's display label.
`data[].client_location_id`	string or null	Your own id for the location.
`data[].address`	string	The address, plus `- <address2>` when it has a second line.
`data[].address1`	string	Street address.
`data[].address2`	string or null	Second address line.
`data[].zip`	string	Postal code.
`data[].country_id`	integer or null	The country's id.
`data[].country_name`	string or null	The country's name.
`data[].country_code`	string or null	The country's code, e.g. `AU`.
`data[].state_id`	integer or null	The state's id.
`data[].state_name`	string or null	The state's name.
`data[].state_code`	string or null	The state's code, e.g. `NSW`.
`data[].city_id`	integer or null	The city's id.
`data[].city_name`	string or null	The city's name.
`data[].company_phone`	string or null	The business phone.
`data[].brand_company_id`	integer	The account's id.
`data[].connect_page_url`	string	The link to the location's connection page, to send to the owner so they can connect review sites.
`data[].active_store_plan`	object or null	The location's active plan, or `null` when it has none.
`data[].active_store_plan.id`	integer	The subscription's id.
`data[].active_store_plan.store_id`	integer	The location's id.
`data[].active_store_plan.plan_id`	integer	The plan's id.
`data[].active_store_plan.status`	string	The subscription's status, e.g. `active`.
`data[].active_store_plan.plan_start`	string	When the subscription started.
`data[].active_store_plan.plan_end`	string	When the subscription ends.
`data[].active_store_plan.cancel_subscription_at`	string or null	When it was cancelled, or `null`.
`data[].active_store_plan.plan`	object	The plan: `id`, `plan_name` and `features`.
`data[].active_store_plan.plan.id`	integer	The plan's id.
`data[].active_store_plan.plan.plan_name`	string	The plan's name.
`data[].active_store_plan.plan.features`	array	The plan's features.
`data[].active_store_plan.plan.features[].id`	integer	The feature row's id.
`data[].active_store_plan.plan.features[].plan_id`	integer	The plan's id.
`data[].active_store_plan.plan.features[].feature_name`	string	The feature, e.g. `ai_response`.
`data[].active_store_plan.plan.features[].options`	array	The feature's display title, when one is set: each with `id`, `feature_value`, `plan_feature_id` and `feature_key` (`title`). Usually `[]`.
`first_page_url`	string	URL of the first page.
`from`	integer or null	Position of the first result on this page.
`last_page`	integer	The last page number.
`last_page_url`	string	URL of the last page.
`links`	array	Page links, each with `url`, `label`, `page` and `active`.
`next_page_url`	string or null	URL of the next page, or `null`.
`path`	string	The endpoint URL.
`per_page`	integer	The page size.
`prev_page_url`	string or null	URL of the previous page, or `null`.
`to`	integer or null	Position of the last result on this page.
`total`	integer	The number of locations across all pages.

Response payload

{
  "data": {
    "current_page": 1,
    "data": [
      {
        "id": 3007,
        "account_name": "Acme Coffee",
        "store_name": "Acme Coffee",
        "store_full_name": "Acme Coffee - docs-test-loc-001",
        "storeid": "Sydney",
        "client_location_id": "docs-test-loc-001",
        "address": "1 George St",
        "address1": "1 George St",
        "address2": null,
        "zip": "2000",
        "country_id": 14,
        "country_name": "Australia",
        "country_code": "AU",
        "state_id": 3909,
        "state_name": "New South Wales",
        "state_code": "NSW",
        "city_id": 3243,
        "city_name": "Sydney",
        "company_phone": null,
        "brand_company_id": 5994,
        "connect_page_url": "https://production.shoutaboutus.com/connect-review-sites/5oogfx",
        "active_store_plan": {
          "id": 14935,
          "store_id": 3007,
          "plan_id": 36,
          "status": "active",
          "plan_start": "2026-10-01T01:00:23.000000Z",
          "plan_end": "2026-10-31T23:59:59.000000Z",
          "cancel_subscription_at": null,
          "plan": {
            "id": 36,
            "plan_name": "Growth — Unlimited",
            "features": [
              {
                "id": 1116,
                "plan_id": 36,
                "feature_name": "ai_response",
                "options": []
              },
              {
                "id": 1117,
                "plan_id": 36,
                "feature_name": "review_flag",
                "options": []
              },
              {
                "id": 1118,
                "plan_id": 36,
                "feature_name": "response_to_past_reviews",
                "options": []
              }
            ]
          }
        }
      }
    ],
    "first_page_url": "https://production-api.shoutaboutus.com/api/v1/store/list?page=1",
    "from": 1,
    "last_page": 1,
    "last_page_url": "https://production-api.shoutaboutus.com/api/v1/store/list?page=1",
    "links": [
      {
        "url": null,
        "label": "&laquo; Previous",
        "page": null,
        "active": false
      },
      {
        "url": "https://production-api.shoutaboutus.com/api/v1/store/list?page=1",
        "label": "1",
        "page": 1,
        "active": true
      },
      {
        "url": null,
        "label": "Next &raquo;",
        "page": null,
        "active": false
      }
    ],
    "next_page_url": null,
    "path": "https://production-api.shoutaboutus.com/api/v1/store/list",
    "per_page": 10,
    "prev_page_url": null,
    "to": 1,
    "total": 1
  }
}

The example shows one location and three of its plan's features.

Examples

Success payload

See Response payload.

Error payload

422 Company outside your tree

{
  "message": "The selected company id does not belong to your company hierarchy.",
  "errors": {
    "company_id": ["The selected company id does not belong to your company hierarchy."]
  }
}

422 Invalid sort field

{
  "message": "The selected sort field is invalid.",
  "errors": {
    "sort_field": ["The selected sort field is invalid."]
  }
}

Status	Meaning
`200`	The locations.
`401`	The token is missing, expired or invalid.
`422`	The request failed validation, e.g. an id outside your tree, an unknown `sort_field`, or `limit` above 100.
`500`	Unexpected server error.

Example request

curl --request POST \
  --url "https://production-api.shoutaboutus.com/api/v1/store/list" \
  --header 'Authorization: Bearer <bearer-token>' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{"sort_field": "store_name", "sort_by": "ASC", "search_field": "store_name", "search_value": "SAU", "active_plan": 1, "company_id": 5994, "limit": 10}'