List widgets

Overview

Returns a paginated list of widgets scoped to a single store (store_id) or an account company and its child companies (company_id). Rows are joined to widget type, store, and company-account names, with optional search/sort.

Prerequisites

• A bearer token. Callable with Partner and Account tokens.

Base URL

Endpoint

POST /api/v1/account/widget/list

Authentication

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

• Who can call it: Partner and Account tokens.

• Authentication in the role-agnostic account/* group (route name api.brand.widget.list). No HiPages gate.

• Target must sit inside your own account tree, keyed on store_id/company_id, which walks the auth user's company hierarchy.

• When store_id is absent, the controller resolves company_id. An account-bundle company (bundle_id = ACCOUNT) lists its own widgets, otherwise it lists widgets of all child companies (childids).

• A partner reaches a wider tree than an account user, but the param shape is identical.

Rate limit

• No rate limit.

Request body

• Body:

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

Response

• current_page (integer)
• data[].id (integer)
• data[].store_id (integer, nullable)
• data[].unique_id (string) — hashid widget code
• data[].created_at (datetime)
• data[].widget_title (string, nullable)
• data[].widget_type (string) — the widget type's name
• data[].widget_type_id (integer) — the widget type's id
• data[].account_name (string, nullable) — the account's name
• data[].store_name (string, nullable) — store name, suffixed with the client location id when one is set (else the storeid)
• per_page / total / last_page / links etc. (standard paginator meta)

200 OK · 200

{
  "current_page": 1,
  "data": [
    {
      "id": 14,
      "store_id": 102,
      "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": "North Brand",
      "store_name": "North Branch - NB01"
    }
  ],
  "first_page_url": "https://api.example.com/api/v1/account/widget/list?page=1",
  "from": 1,
  "last_page": 1,
  "per_page": 10,
  "to": 1,
  "total": 1
}

422 Validation error · 422

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

Errors

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": 1, "limit": 10, "page": 1, "sort_field": "created_at", "sort_by": "DESC", "search_field": "widget_title", "search_value": "Feed"}'