How to create a widget using the Shapo API | Shapo Help Center and How-To Guides

Create a Shapo widget from your server and filter it by tags, ratings, sources, or keywords.

The widget creation API is available on the Pro plan.

Before you begin

Get your API key from the Workspace settings page in Shapo.

Keep your API key private. Call the API from your server, not from browser-side JavaScript.

Include these headers with every request:

Authorization: Bearer <YOUR API KEY>
Content-Type: application/json

If you want the widget to display a specific group of imported reviews, import those reviews with a tag before creating the widget.

Create a widget

Send a POST request to:

https://api.shapo.io/widgets

This example creates a widget that displays testimonials tagged as Product A:

curl --request POST 'https://api.shapo.io/widgets' \
  --header 'Authorization: Bearer <YOUR API KEY>' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "name": "Product A Reviews",
    "tags": ["Product A"]
  }'

The default widget type is MultiCarouselWidget.

Request fields

name: Required. A unique widget name from 3 to 50 characters.
type: Optional. The widget type. Default: MultiCarouselWidget.
tags: Optional. An array of up to 10 existing tag names. Unknown tags return an error.
settings: Optional. Testimonial filters and widget behavior.
design: Optional. Widget colors and display options.
labels: Optional. Custom labels and language.
connectedForm: Optional. Testimonial collection form settings.

Supported widget types

MultiCarouselWidget
CarouselWidget
GridWidget
SingleWidget
MarqueeWidget
BadgeWidget
ListWidget
FloatingWidget

Common settings

minRating: Number from 0 to 5.
sortBy: newest, oldest, rating, or random.
hideBranding: true or false.
showTotals: none, all, or filtered.
keywords: Up to 10 strings, with a maximum of 20 characters each.
sources: Up to 20 testimonial source values.
contentType: images, videos, or all.
numTestimonials: Number of testimonials to display. The accepted range depends on the widget type.

The API accepts the same type-specific settings, design options, labels, and connected form fields used by the Shapo widget editor. Invalid values return a 400 Bad Request response.

Customized widget example

curl --request POST 'https://api.shapo.io/widgets' \
  --header 'Authorization: Bearer <YOUR API KEY>' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "name": "Product A Reviews",
    "type": "MultiCarouselWidget",
    "tags": ["Product A"],
    "settings": {
      "minRating": 4,
      "sortBy": "newest",
      "numTestimonials": 12
    },
    "design": {
      "backgroundColor": "transparent",
      "showRating": true,
      "showProfileImage": true
    }
  }'

Response

Example response:

{
  "_id": "66950e605797ea132a5b2781",
  "publicId": "AbC123WidgetPublicId",
  "embedId": "AbC123WidgetPublicId",
  "embedSelectorId": "shapo-widget-AbC123WidgetPublicId",
  "name": "Product A Reviews",
  "type": "MultiCarouselWidget"
}

_id: The internal widget ID.
publicId: The public widget ID.
embedId: The ID used to embed the widget. This matches publicId.
embedSelectorId: The complete HTML container ID.

Use embedSelectorId as the ID of the widget container on your website:

<div id="shapo-widget-AbC123WidgetPublicId"></div>

Load the Shapo widget script on the page as usual.

Rate limit

The API allows 30 widget creation requests per workspace, per hour.

Error responses

Errors contain an error field:

{   
  "error": "API key is invalid" 
}

400 Bad Request: Invalid request fields, unknown tags, or a duplicate widget name.
403 Forbidden: Missing or invalid API key, or the workspace is not on the Pro plan.
429 Too Many Requests: The hourly rate limit was reached.