Load a widget's reviews and settings

Overview

Fetch everything the embedded widget needs to render: its style and the reviews to show.

Called by the embed code when the page loads.

You'll need the widget's unique id, which is in the embed code.

Returns the widget configuration and, with feed_data=1, its review feed. A bearer token is required.

Without feed_data (or with feed_data=0) you get the widget's settings only, and data.data is null. With feed_data=1 you get a page of reviews from the widget's locations, newest first, with the average rating and the widget's settings. The reviews are limited to the review site saved in the widget's options (reviewSiteValue), and the page size is limit, else the widget's numberOfReviews, else 3.

Prerequisites

A bearer token. See Authentication.
The widget's unique_id, from the embed code or from List review widgets.
The widget's location needs an active widget add-on; otherwise you get 400.

Base URL

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

Endpoint

GET /api/v1/widget

Authentication

Partner or Account token

Any valid token works. The widget doesn't have to be in your account tree, because the widget is shown on public pages.
A token is still required: without one you get 401.

Rate limit

This endpoint has no rate limit.

Request parameters

Parameter	In	Type	Required	Description
`unique_id`	query	string	Yes	The widget's unique id. Must match an existing widget.
`feed_data`	query	integer	No	`1` returns the review feed and `avg_rating`. `0` or left out returns the settings only.
`limit`	query	integer	No	Feed page size, 10–100 (values below 10 are raised to 10; above 100 returns `422`). When omitted, the widget's `numberOfReviews` setting, or 3 if that isn't set (either may be below 10).
`page`	query	integer	No	Feed page to return. Default `1`.

Request body

None.

Request payload

None.

Response body

There are two shapes.

Config only (feed_data left out or 0): the payload is inside data: data.widget, data.status and data.data (null).
Feed (feed_data=1): not wrapped. data is the array of reviews, next to widget, status, avg_rating, links and meta.

Field	Type	Description
`data.widget`	object	Config only. The widget's settings (fields below).
`data.widget.id`	integer	The widget's id.
`data.widget.company_id`	integer or null	The widget's account, when one is set; otherwise `null`.
`data.widget.store_id`	integer	The location the widget belongs to.
`data.widget.widget_text`	string or null	Not set by the API; `null`.
`data.widget.widget_type`	string or null	Not set by the API; `null`. The style is `widget_type_id`.
`data.widget.widget_type_id`	integer	The widget's style, from List widget styles.
`data.widget.widget_title`	string or null	The widget's title.
`data.widget.sub_type`	string or null	Not set by the API; `null`.
`data.widget.unique_id`	string	The widget's unique id, used in the embed code.
`data.widget.widget_options`	object or null	The widget's saved settings, as sent to Create or update a widget. The feed uses `numberOfReviews` and `reviewSiteValue`.
`data.widget.widget_options.numberOfReviews`	integer	Reviews per feed page when `limit` isn't sent.
`data.widget.widget_options.reviewSiteValue`	object	The review site the feed is filtered to.
`data.widget.widget_options.reviewSiteValue.value`	integer	The review site id.
`data.widget.widget_options.reviewSiteValue.label`	string	The review site name.
`data.widget.created_at`	string	When the widget was created (ISO 8601).
`data.widget.updated_at`	string	When the widget was last changed (ISO 8601).
`data.status`	string	Config only. `success`.
`data.data`	null	Config only. Always `null`: no feed was asked for.
`data[]`	array of objects	Feed. The reviews on this page, newest first (fields below).
`data[].id`	integer	The review id.
`data[].source_platform`	string	The platform the review came from, e.g. `google`.
`data[].review`	object	The review.
`data[].review.id`	integer	The review id.
`data[].review.reviewer`	string	The reviewer's name as shown on the review site.
`data[].review.rating`	integer	Star rating.
`data[].review.message`	string	The review text.
`data[].review.review_date`	string or null	When the review was posted.
`data[].reviewsite`	object	The review site.
`data[].reviewsite.id`	integer	The review site id.
`data[].reviewsite.name`	string	The review site name.
`data[].reviewsite.link`	string	The review site's home page.
`data[].reviewsite.review_site_logo`	string	URL of the site's logo.
`data[].reviewsite.review_site_color`	string or null	The site's brand colour.
`data[].reviewsite.auth_type`	string or null	How the site connects (see List supported review sites).
`data[].reviewsite.scraping_enabled`	boolean	Whether reviews are collected from this site.
`data[].reviewsite.posting_enabled`	boolean	Whether responses can be posted to this site.
`data[].store`	object	The location the review is for.
`data[].store.id`	integer	The location id.
`data[].store.name`	string	The location's name.
`data[].store.slug`	string or null	The location's slug.
`data[].store.address`	string	The account's address.
`data[].store_reviewsite`	object	The location's connection to the review site.
`data[].store_reviewsite.id`	integer or null	The connection id.
`data[].store_reviewsite.url`	string or null	The location's page on the review site.
`data[].store_reviewsite.landing_page_url`	string or null	Where customers are sent to leave a review, when set.
`data[].store_reviewsite.connection_status`	string or null	Connection status, e.g. `connected`.
`data[].store_reviewsite.is_connected`	boolean	Whether the location is connected to the site.
`data[].flag`	array of objects	Status notes on the review's response or removal flag (`flag`, `title`, `statusColor`, `icon`). Empty when there are none.
`data[].plan`	string	Plan name on the latest response update, or an empty string.
`data[].review_flag`	object or null	The removal flag on the review; `null` when it isn't flagged.
`data[].is_flaggable`	boolean	Whether the review can be flagged for removal.
`data[].flag_status`	string	Removal flag status; `none` when not flagged.
`data[].flag_details`	object or null	The flag's `reason`, `reason_identifier`, `flag_reason_detail` and `flag_date`; `null` when not flagged.
`data[].response_capabilities`	object	Whether a response can be written for this review.
`data[].response_capabilities.manual`	boolean	A response can be written by hand.
`data[].response_capabilities.ai`	boolean	An AI response can be generated.
`data[].response_capabilities.reason`	string or null	Why responses are unavailable; `null` when they are available.
`data[].response`	object or null	The response to the review; `null` when there is none.
`data[].response.id`	integer	The response id.
`data[].response.status`	string	Response status, e.g. `complete` or `pending`.
`data[].response.public_contents`	string or null	The public response text.
`data[].response.response_date`	string or null	When the response was posted.
`data[].response.deleted`	object or null	Removal details when the response was removed; otherwise `null`.
`widget`	object	Feed. The widget's settings, the same fields as `data.widget`.
`status`	string	Feed. `success`.
`avg_rating`	number	Feed. Average rating across the feed's locations, to 2 decimal places.
`links`	object	Feed. `first`, `last`, `prev` and `next` page URLs (`prev`/`next` are `null` at the ends).
`meta`	object	Feed. Pagination: `current_page`, `from`, `last_page`, `links`, `path`, `per_page`, `to`, `total`.

Response payload

{
  "data": {
    "widget": {
      "id": 5,
      "company_id": null,
      "store_id": 3007,
      "widget_text": null,
      "widget_type": null,
      "widget_type_id": 1,
      "widget_title": "My Reviews",
      "sub_type": null,
      "unique_id": "abc123",
      "widget_options": {
        "numberOfReviews": 5,
        "reviewSiteValue": {
          "value": 44,
          "label": "Google"
        }
      },
      "created_at": "2026-06-15T10:30:00.000000Z",
      "updated_at": "2026-06-15T10:30:00.000000Z"
    },
    "status": "success",
    "data": null
  }
}

Examples

Success payload

Settings only (feed_data=0): see Response payload.

With feed_data=1, a page of reviews:

{
  "data": [
    {
      "id": 1546,
      "source_platform": "google",
      "review": {
        "id": 1546,
        "reviewer": "Jane D.",
        "rating": 5,
        "message": "Fantastic service!",
        "review_date": "2026-06-14 12:00:00"
      },
      "reviewsite": {
        "id": 44,
        "name": "Google",
        "link": "https://www.google.com",
        "review_site_logo": "https://d2ny6zb7otrnhl.cloudfront.net/static/images/img-google.png",
        "review_site_color": "#4285F4",
        "auth_type": "oauth",
        "scraping_enabled": true,
        "posting_enabled": true
      },
      "store": {
        "id": 3007,
        "name": "Demo Store",
        "slug": "demo-store",
        "address": "123 Main St, Sydney, NSW"
      },
      "store_reviewsite": {
        "id": 91,
        "url": "https://maps.google.com/?cid=1234567890",
        "landing_page_url": null,
        "connection_status": "connected",
        "is_connected": true
      },
      "flag": [],
      "plan": "",
      "review_flag": null,
      "is_flaggable": false,
      "flag_status": "none",
      "flag_details": null,
      "response_capabilities": {
        "manual": true,
        "ai": true,
        "reason": null
      },
      "response": null
    }
  ],
  "widget": {
    "id": 5,
    "company_id": null,
    "store_id": 3007,
    "widget_text": null,
    "widget_type": null,
    "widget_type_id": 1,
    "widget_title": "My Reviews",
    "sub_type": null,
    "unique_id": "abc123",
    "widget_options": {
      "numberOfReviews": 5,
      "reviewSiteValue": {
        "value": 44,
        "label": "Google"
      }
    },
    "created_at": "2026-06-15T10:30:00.000000Z",
    "updated_at": "2026-06-15T10:30:00.000000Z"
  },
  "status": "success",
  "avg_rating": 4.5,
  "links": {
    "first": "https://production-api.shoutaboutus.com/api/v1/widget?page=1",
    "last": "https://production-api.shoutaboutus.com/api/v1/widget?page=1",
    "prev": null,
    "next": null
  },
  "meta": {
    "current_page": 1,
    "from": 1,
    "last_page": 1,
    "links": [
      {
        "url": null,
        "label": "&laquo; Previous",
        "page": null,
        "active": false
      },
      {
        "url": "https://production-api.shoutaboutus.com/api/v1/widget?page=1",
        "label": "1",
        "page": 1,
        "active": true
      },
      {
        "url": null,
        "label": "Next &raquo;",
        "page": null,
        "active": false
      }
    ],
    "path": "https://production-api.shoutaboutus.com/api/v1/widget",
    "per_page": 10,
    "to": 1,
    "total": 1
  }
}

Error payload

400 No active widget add-on

{
  "message": "You do not have any active widget add-ons. Please add an add-on to your location in order to access the widget features.",
  "status": "error",
  "errors": []
}

422 unique_id is missing

{
  "message": "The unique id field is required.",
  "errors": {
    "unique_id": [
      "The unique id field is required."
    ]
  }
}

422 unique_id doesn't match a widget

{
  "message": "The selected unique id is invalid.",
  "errors": {
    "unique_id": [
      "The selected unique id is invalid."
    ]
  }
}

422 feed_data isn't 0 or 1

{
  "message": "The selected feed data is invalid.",
  "errors": {
    "feed_data": [
      "The selected feed data 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`	The widget's settings, or a page of its reviews.
`400`	The widget's location has no active widget add-on.
`401`	The token is missing, expired or invalid.
`422`	`unique_id` is missing or doesn't match a widget, `feed_data` isn't `0` or `1`, or `limit` is above 100.
`500`	Unexpected server error.

Example request

curl --request GET \
  --url "https://production-api.shoutaboutus.com/api/v1/widget?unique_id=abc123&feed_data=0" \
  --header 'Authorization: Bearer <bearer-token>' \
  --header 'Accept: application/json'