Surveys - Create Survey

Endpoint

/i/surveys/survey/create

Ⓔ Enterprise Only
This API is available exclusively in Countly Enterprise.

Overview

Creates a Survey widget.

Authentication

Authentication methods:

• API Key (parameter): api_key=YOUR_API_KEY
• Auth Token (parameter): auth_token=YOUR_AUTH_TOKEN
• Auth Token (header): countly-token: YOUR_AUTH_TOKEN

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	Message text object
questions	String (JSON Array)	Yes	Survey questions
appearance	String (JSON Object)	No	Appearance configuration
targeting	String (JSON Object)	No	Targeting rules/cohort source

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 - Missing questions:

{
  "result": "Missing params: 'questions'"
}

• HTTP 400 - DB create failure:

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

Behavior/Processing

• Parses and preprocesses widget properties such as msg, appearance, targeting, and questions.
• Validates Survey payload with Survey form property rules.
• Requires non-empty questions and validates each question definition before insert.
• Creates a feedback_widgets record with type=survey, creator, created, responded=0, shown=0, and wv=1.
• 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.

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.

---

Examples

/i/surveys/survey/create?api_key=YOUR_API_KEY&app_id=YOUR_APP_ID&name=Product Feedback&internalName=product_feedback_v1&status=true&msg={"thanks":"Thank you"}&questions=[{"id":"q1","type":"text","question":"How can we improve?","required":false}]

Limitations

• Requires valid non-empty questions array.

Related Endpoints

• Surveys - Edit Survey
• Surveys - Delete Survey
• Surveys - Update Survey Status

Ⓔ Enterprise

This feature is part of Countly Enterprise.

Get Access:

• Learn about Enterprise
• Contact Sales
• Compare Versions

Already a Customer? Use support portal if you have any questions.

---

Last Updated

2026-04-18