Dashboard

Widgets API

Create and manage embeddable feedback widgets programmatically.

Widgets are available on all plans. API access requires Business plan with API key authentication.
GET/api/widgets

List all widgets

Returns a paginated list of widgets for the authenticated user. Requires API key.

Response

JSON
{
  "widgets": [
    {
      "id": "widget_abc123",
      "title": "Quick Feedback",
      "description": "Collect user feedback",
      "widget_type": "feedback",
      "published": true,
      "created_at": "2025-01-15T10:30:00Z",
      "updated_at": "2025-01-15T10:30:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 50,
    "total": 1,
    "totalPages": 1
  }
}
POST/api/widgets

Create a widget

Creates a new widget. Requires API key and Pro or Business subscription.

Request body

JSON
{
  "widget_type": "feedback",
  "title": "Quick Feedback",
  "questions": [
    {
      "id": "rating",
      "type": "star_rating",
      "title": "How would you rate your experience?",
      "required": true,
      "starRatingSettings": { "maxStars": 5 }
    },
    {
      "id": "comment",
      "type": "long_text",
      "title": "Any additional feedback?",
      "required": false
    }
  ],
  "trigger_config": {
    "position": "bottom-right",
    "icon": "chat",
    "text": "Feedback",
    "showText": true
  },
  "theme": {
    "primaryColor": "#000000",
    "backgroundColor": "#ffffff"
  },
  "thank_you_title": "Thank you!",
  "thank_you_message": "Your feedback helps us improve."
}

Response

JSON
{
  "id": "widget_abc123",
  "title": "Quick Feedback",
  "widget_type": "feedback",
  "published": false,
  "created_at": "2025-01-15T10:30:00Z"
}
GET/api/widgets/:id

Get a widget

Returns widget configuration. Published widgets are publicly accessible.

Response

JSON
{
  "id": "widget_abc123",
  "title": "Quick Feedback",
  "widget_type": "feedback",
  "questions": [...],
  "trigger_config": {
    "position": "bottom-right",
    "icon": "chat",
    "text": "Feedback"
  },
  "theme": {...},
  "thank_you_title": "Thank you!",
  "thank_you_message": "Your feedback helps us improve.",
  "published": true
}
PUT/api/widgets/:id

Update a widget

Update widget configuration. Requires API key and widget ownership.

Request body

JSON
{
  "title": "Updated Feedback Widget",
  "published": true
}

Response

JSON
{
  "id": "widget_abc123",
  "title": "Updated Feedback Widget",
  "published": true,
  "updated_at": "2025-01-15T11:00:00Z"
}
DELETE/api/widgets/:id

Delete a widget

Permanently deletes a widget and all its responses. Requires API key.

Response

JSON
{ "success": true }

Public submission endpoints

These endpoints are used by the embed SDK. They require embed tokens instead of API keys.

GET/api/widgets/:id/token

Get embed token

Issues a signed token required for submissions. Tokens expire after 30 minutes.

Response

JSON
{
  "token": "eyJhbGciOiJIUzI1NiIs...",
  "expiresIn": 1800
}
POST/api/widgets/:id/submit

Submit widget response

Submit a response to a published widget. Requires embed token.

Request body

JSON
{
  "answers": {
    "rating": 5,
    "comment": "Great experience!"
  },
  "_token": "eyJhbGciOiJIUzI1NiIs...",
  "metadata": {
    "pageUrl": "https://example.com/pricing",
    "pageTitle": "Pricing - Example",
    "fingerprint": "abc123..."
  }
}

Response

JSON
{
  "success": true,
  "id": "resp_xyz789"
}

Widget types

feedbackStar rating + optional comment
nps0-10 NPS scale with follow-up question
contactEmail + message contact form
bug_reportBug description + severity selector
customBuild your own with any form blocks

Trigger configuration

positionbottom-right, bottom-left, top-right, top-left
iconchat, feedback, help, star, heart
textButton label text
showTextShow text alongside icon
triggerModeclick_toggle, scroll, exit_intent, time_delay
scrollPercentageScroll % to trigger (for scroll mode)
timeDelaySeconds before showing (for time_delay)

Error responses

widget_not_found404Widget does not exist
widget_not_published403Widget is not published
widget_closed403Widget closed by date or limit
domain_not_allowed403Submission from unauthorized domain
invalid_token403Missing or expired embed token
← Polls APIResponses API →