List review widgets

Overview

Get the account's review widgets with their embed codes.

Use this to manage widgets or copy an embed code.

You'll need a store_id (one location) or a company_id (an account, or a partner for all its accounts). Partner and Account tokens both work.

Returns one entry per widget. If you send both store_id and company_id, store_id is used.

Prerequisites

A bearer token. See Authentication.
A location id (store_id) or an account id (company_id).

Base URL

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

Endpoint

POST /api/v1/account/widget/list

Authentication

Partner or Account token

store_id or company_id must be inside your own account tree. A Partner token can list widgets anywhere under the partner (a partner's company_id lists the widgets of all its accounts); an Account token only its own.
An id outside your tree, or one that doesn't exist, is rejected with 422.

Rate limit

This endpoint has no rate limit.

Request parameters

None.

Request body

Field	Type	Required	Description
`store_id`	integer	One of `store_id` / `company_id`	A location. Lists that location's widgets. Must exist and be inside your account tree. Required when `company_id` isn't sent.
`company_id`	integer	One of `store_id` / `company_id`	An account (its widgets) or a partner (the widgets of all its accounts). Must exist and be inside your account tree. Required when `store_id` isn't sent.
`limit`	integer	No	Widgets per page, 10–100 (values below 10 are raised to 10; above 100 returns `422`). Default 10.
`page`	integer	No	Page number, from 1. Default 1.
`sort_field`	string	No	Field to sort by. Without it, no sort order is applied.
`sort_by`	string	No	Sort direction when `sort_field` is sent. Default `DESC`.
`search_field`	string	No	Field to search, used with `search_value`. Same values as `sort_field`.
`search_value`	string	No	Text to search for (partial match). For `created_at` / `updated_at`, a date. With `search_field` `store_name`, `all` lists widgets with no location.

Request payload

{
  "company_id": 5994,
  "limit": 10,
  "page": 1,
  "sort_field": "created_at",
  "sort_by": "DESC",
  "search_field": "widget_title",
  "search_value": "Feed"
}

Response body

Not wrapped in data: the response is the page itself.

Field	Type	Description
`current_page`	integer	The page returned.
`data`	array of objects	The widgets on this page. An empty array `[]` when there are none.
`data[].id`	integer	The widget's id.
`data[].store_id`	integer or null	The location the widget belongs to.
`data[].unique_id`	string	The widget's unique id, used in the embed code and in Load a widget's reviews and settings.
`data[].created_at`	string	When the widget was created (ISO 8601).
`data[].widget_title`	string or null	The widget's title.
`data[].widget_type`	string	The style's name, from List widget styles.
`data[].widget_type_id`	integer	The style's id.
`data[].account_name`	string or null	The account's name.
`data[].store_name`	string or null	The location's name, followed by its client location id (or store id) when it has one.
`first_page_url`	string	URL of the first page.
`from`	integer or null	Position of the first widget on this page; `null` when there are none.
`last_page`	integer	The last page number.
`last_page_url`	string	URL of the last page.
`links`	array of objects	Page links (`url`, `label`, `page`, `active`).
`next_page_url`	string or null	URL of the next page, or `null`.
`path`	string	The endpoint URL.
`per_page`	integer	Widgets per page.
`prev_page_url`	string or null	URL of the previous page, or `null`.
`to`	integer or null	Position of the last widget on this page; `null` when there are none.
`total`	integer	Total widgets that match.

Response payload

{
  "current_page": 1,
  "data": [
    {
      "id": 14,
      "store_id": 3007,
      "unique_id": "abc123",
      "created_at": "2026-06-15T10:30:00.000000Z",
      "widget_title": "Homepage Feed Widget",
      "widget_type": "Feed Widget",
      "widget_type_id": 1,
      "account_name": "Acme Coffee",
      "store_name": "Acme Coffee - docs-test-loc-001"
    }
  ],
  "first_page_url": "https://production-api.shoutaboutus.com/api/v1/account/widget/list?page=1",
  "from": 1,
  "last_page": 1,
  "last_page_url": "https://production-api.shoutaboutus.com/api/v1/account/widget/list?page=1",
  "links": [
    {
      "url": null,
      "label": "&laquo; Previous",
      "page": null,
      "active": false
    },
    {
      "url": "https://production-api.shoutaboutus.com/api/v1/account/widget/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/account/widget/list",
  "per_page": 10,
  "prev_page_url": null,
  "to": 1,
  "total": 1
}

Examples

Success payload

A page of widgets: see Response payload.

No widgets match:

{
  "current_page": 1,
  "data": [],
  "first_page_url": "https://production-api.shoutaboutus.com/api/v1/account/widget/list?page=1",
  "from": null,
  "last_page": 1,
  "last_page_url": "https://production-api.shoutaboutus.com/api/v1/account/widget/list?page=1",
  "links": [
    {
      "url": null,
      "label": "&laquo; Previous",
      "page": null,
      "active": false
    },
    {
      "url": "https://production-api.shoutaboutus.com/api/v1/account/widget/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/account/widget/list",
  "per_page": 10,
  "prev_page_url": null,
  "to": null,
  "total": 0
}

Error payload

422 Neither store_id nor company_id

{
  "message": "The store id field is required when company id is not present. (and 1 more error)",
  "errors": {
    "store_id": [
      "The store id field is required when company id is not present."
    ],
    "company_id": [
      "The company id field is required when store id is not present."
    ]
  }
}

422 Account 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 Unknown sort_field or sort_by

{
  "message": "The selected sort field is invalid. (and 1 more error)",
  "errors": {
    "sort_field": [
      "The selected sort field is invalid."
    ],
    "sort_by": [
      "The selected sort by is invalid."
    ]
  }
}

422 limit is above 100

{
  "message": "The limit field must not be greater than 100.",
  "errors": {
    "limit": [
      "The limit field must not be greater than 100."
    ]
  }
}

Status	Meaning
`200`	A page of widgets (`data` is `[]` when there are none).
`401`	The token is missing, expired or invalid.
`422`	Neither `store_id` nor `company_id` was sent, an id doesn't exist or is outside your tree, a sort or search value isn't allowed, or `limit` is above 100.
`500`	Unexpected server error.

Example request

curl --request POST \
  --url "https://production-api.shoutaboutus.com/api/v1/account/widget/list" \
  --header 'Authorization: Bearer <bearer-token>' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{"company_id": 5994, "limit": 10, "page": 1, "sort_field": "created_at", "sort_by": "DESC", "search_field": "widget_title", "search_value": "Feed"}'