Surveys - NPS Widget

Enterprise

This endpoint is part of Countly Enterprise. To get access, contact sales or compare versions. Existing customers can reach the support portal with questions.

Endpoint

/o/surveys/nps/widget

Overview

Returns one NPS widget (widget_id) or multiple NPS widgets (widget_ids).

Authentication

Pass api_key or auth_token as a query parameter, or send countly-token as a header. See Authentication.

Permissions

• Surveys: Read permission.

Request Parameters

Parameter	Type	Required	Description
api_key	String	Yes (or auth_token)	API key authentication
auth_token	String	Yes (or api_key)	Auth token authentication
app_id	String	Yes	App ID
widget_id	String	Conditional	Single widget ID
widget_ids	String	Conditional	Comma-separated widget IDs
shown	Boolean/String	No	Record display/impression metadata
platform	String	No	Shown context
app_version	String	No	Shown context
journeyId	String	No	Optional source tagging

Examples

/o/surveys/nps/widget?api_key=YOUR_API_KEY&app_id=YOUR_APP_ID&widget_id=67b9db56f67aab0012cd8899

Response

Success Response

{
  "_id": "67b9db56f67aab0012cd8899",
  "type": "nps",
  "name": "NPS Q1",
  "msg": {
    "mainQuestion": "How likely are you to recommend us?"
  },
  "followUpType": "score"
}

Response Fields

Field	Type	Description
_id	String	Widget ID
type	String	nps
name	String	Widget name
msg	Object	NPS message texts
followUpType	String	NPS follow-up mode

Error Responses

• HTTP 400 - Missing/invalid widget identifier:

{
  "result": "Missing parameter \"widget_id\" or \"widget_ids\""
}

• HTTP 404 - Not found:

{
  "result": "Widget not found."
}

Behavior

• Requires either widget_id or comma-separated widget_ids.
• Reads only active widgets (status=true) from feedback_widgets.
• For widget_id, returns a single object; for widget_ids, returns an array.
• Returned fields are limited to app/type/name/message/score/appearance/link/final text/version/consent fields used by SDK clients.
• If shown is present with a single widget, increments widget shown, records a custom metric in the Survey/NPS aggregate collection, and stores metric metadata for the widget/platform/app version/source key.

Related Endpoints

• Surveys - NPS Widgets
• Surveys - NPS Overview Metrics

Implementation details

Database Collections

Collection	Used for	Data touched by this endpoint
countly.feedback_widgets	Endpoint data source	Stores endpoint-related records this endpoint reads or modifies.
countly.apps	App configuration and metadata	Stores app-level feature settings and metadata used or modified by this endpoint.