Surveys - Create NPS

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

/i/surveys/nps/create

Overview

Creates an NPS widget.

Authentication

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

Permissions

• Surveys: Create 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
name	String	Yes	Widget display name
internalName	String	Yes	Internal widget name
status	Boolean/String	Yes	Initial active status
msg	String (JSON Object)	Yes	NPS message object
followUpType	String	No	Follow-up mode
appearance	String (JSON Object)	No	Appearance configuration
targeting	String (JSON Object)	No	Targeting rules/cohort source

Examples

/i/surveys/nps/create?api_key=YOUR_API_KEY&app_id=YOUR_APP_ID&name=NPS Q1&internalName=nps_q1&status=true&msg={"mainQuestion":"How likely are you to recommend us?"}

Response

Success Response

{
  "result": {
    "_id": "67b9db56f67aab0012cd8899",
    "text": "Successfully created 67b9db56f67aab0012cd8899"
  }
}

Response Fields

Field	Type	Description
result	Object	Create result wrapper
result._id	String	Created widget ID
result.text	String	Success message

Error Responses

• HTTP 400 - Invalid params:

{
  "result": "Invalid params: ..."
}

• HTTP 400 - DB create failure:

{
  "result": "Failed to create widget(DB error)"
}

Behavior

• Parses and preprocesses widget properties such as msg, appearance, and targeting.
• Validates NPS payload with NPS form property rules.
• Creates a feedback_widgets record with type=nps, creator, created, responded=0, shown=0, wv=1, and scores={total,promoter,detractor,passive} initialized to zero.
• Uploads logo when provided and records it in appearance.logo; if upload fails, the widget can still be created and the response includes the new widgetId with an error.
• Creates a linked cohort when targeting is provided, stores its ID as cohortID, and emits surveys_widget_created.

Related Endpoints

• Surveys - Edit NPS
• Surveys - Delete NPS
• Surveys - Update NPS Status

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.cohorts	Endpoint data source	Stores endpoint-related records this endpoint reads or modifies.