Survey
Surveys represent individual questionnaires within your workspace. Each survey contains a series of questions designed to gather information or opinions from respondents. This section of the API allows you to retrieve information about the surveys in your workspace
List all surveys
This endpoint allows you to fetch a list of all surveys within your workspace, including their associated metadata and configuration parameters.
Optional parameters
- Name
items_per_page- Type
- integer
- Description
The number of items to display per page in the response. This parameter helps manage the size of each response, making it easier to work with large datasets by breaking them into smaller, paginated results. The minimum value for this parameter is 1, and the maximum is 100.
- Name
start- Type
- string
- Description
The start timestamp to filter surveys by their creation date. Surveys created on or after this timestamp will be included in the response. The timestamp should be in the ISO 8601 format, including microseconds (e.g., '2023-01-01T00:00:00.000000Z').
- Name
end- Type
- string
- Description
The end timestamp to filter surveys by their creation date. Surveys created before or at this timestamp will be included in the response. The timestamp should be in the ISO 8601 format, including microseconds (e.g., '2023-01-01T00:00:00.000000Z').
Response properties
- Name
pagination_data.has_more- Type
- boolean
- Description
Specifies if additional pages are available for retrieval (True or False).
- Name
pagination_data.next_url- Type
- string
- Description
URL to navigate to the subsequent set of paginated results.
- Name
data[0].id- Type
- string
- Description
The survey's unique unchangeable identifier.
- Name
data[0].type- Type
- PageSurvey | WidgetSurvey | MobileSurvey | IntercomSurvey
- Description
The survey's unchangeable type. The type of survey corresponds to the distribution method the survey is delivered to your respondents: * PageSurvey is Email & Sharable Link Survey * WidgetSurvey is Web & In-Product Survey * MobileSurvey is Mobile App Survey * IntercomSurvey is Intercom Messenger Survey
- Name
data[0].name- Type
- string
- Description
The name of the survey.
- Name
data[0].created_at- Type
- string
- Description
The timestamp when the survey was creatd. The timestamp should be in the ISO 8601 format, including microseconds (e.g., '2023-01-01T00:00:00.000000Z').
- Name
data[0].enabled- Type
- boolean
- Description
Indicates whether a survey is available for respondents (true or false).
- Name
data[0].responses- Type
- integer
- Description
The total number of survey responses.
- Name
data[0].launch.start_at- Type
- string
- Description
Date when the survey will start appearing to respondents.
- Name
data[0].launch.end_at- Type
- string
- Description
Date when the survey will stop appearing to respondents.
- Name
data[0].launch.responses_limit- Type
- integer
- Description
The survey will stop being available to respondents after collecting that amount of responses.
Response
{
"pagination_data": {
"has_more": true,
"next_url": "/surveys?start=2023-01-01T00:00:00.000000Z"
},
"data": [
{
"id": "69f3dcf0d3220de7",
"type": "PageSurvey | WidgetSurvey | MobileSurvey | IntercomSurvey",
"name": "Customer satisfaction survey",
"created_at": "2023-01-13T00:00:00.000000Z",
"enabled": true,
"responses": 34206,
"launch": {
"start_at": "2023-06-13T00:00:00.000000Z",
"end_at": "2023-06-31T00:00:00.000000Z",
"responses_limit": 1400
}
}
]
}Retrieve survey information
Fetches the details and parameters of a specific survey using its unique survey ID.
Required parameters
- Name
survey_id- Type
- string
- Description
The unique identifier of the survey you wish to retrieve.
Response properties
- Name
id- Type
- string
- Description
The survey's unique unchangeable identifier.
- Name
type- Type
- PageSurvey | WidgetSurvey | MobileSurvey | IntercomSurvey
- Description
The survey's unchangeable type. The type of survey corresponds to the distribution method the survey is delivered to your respondents: * PageSurvey is Email & Sharable Link Survey * WidgetSurvey is Web & In-Product Survey * MobileSurvey is Mobile App Survey * IntercomSurvey is Intercom Messenger Survey
- Name
name- Type
- string
- Description
The name of the survey.
- Name
created_at- Type
- string
- Description
The timestamp when the survey was creatd. The timestamp should be in the ISO 8601 format, including microseconds (e.g., '2023-01-01T00:00:00.000000Z').
- Name
enabled- Type
- boolean
- Description
Indicates whether a survey is available for respondents (true or false).
- Name
responses- Type
- integer
- Description
The total number of survey responses.
- Name
launch.start_at- Type
- string
- Description
Date when the survey will start appearing to respondents.
- Name
launch.end_at- Type
- string
- Description
Date when the survey will stop appearing to respondents.
- Name
launch.responses_limit- Type
- integer
- Description
The survey will stop being available to respondents after collecting that amount of responses.
- Name
author.name- Type
- string
- Description
The full name of the individual who created the survey.
- Name
author.email- Type
- string
- Description
The email address of the individual who created the survey.
- Name
folder- Type
- string
- Description
The name of the folder in which the survey is stored.
- Name
first_response_at- Type
- string
- Description
This is the timestamp indicating when the first response to the survey was received. It should be in the ISO 8601 format, including microseconds (e.g., '2023-01-01T00:00:00.000000Z').
- Name
last_response_at- Type
- string
- Description
This is the timestamp indicating when the last response to the survey was received. It should be in the ISO 8601 format, including microseconds (e.g., '2023-01-01T00:00:00.000000Z').
Response
{
"id": "69f3dcf0d3220de7",
"type": "PageSurvey | WidgetSurvey | MobileSurvey | IntercomSurvey",
"name": "Customer satisfaction survey",
"created_at": "2023-01-13T00:00:00.000000Z",
"enabled": true,
"responses": 34206,
"launch": {
"start_at": "2023-06-13T00:00:00.000000Z",
"end_at": "2023-06-31T00:00:00.000000Z",
"responses_limit": 1400
},
"author": {
"name": "John Doe",
"email": "john.doe@example.com"
},
"folder": "Marketing Team Surveys",
"first_response_at": "2023-06-13T00:00:00.000000Z",
"last_response_at": "2023-06-31T00:00:00.000000Z"
}List questions
This endpoint fetches all questions included in a specified survey, making it easy to review or analyze the survey structure.
Required parameters
- Name
survey_id- Type
- string
- Description
The unique identifier of the survey.
Optional parameters
- Name
items_per_page- Type
- integer
- Description
The number of items to display per page in the response. This parameter helps manage the size of each response, making it easier to work with large datasets by breaking them into smaller, paginated results. The minimum value for this parameter is 1, and the maximum is 100.
- Name
start- Type
- string
- Description
The unique identifier of the question, used to return paginated results. This identifier is included in the response for each request, as part of the 'next_url' parameter.
Response properties
- Name
pagination_data.has_more- Type
- boolean
- Description
Specifies if additional pages are available for retrieval (True or False).
- Name
pagination_data.next_url- Type
- string
- Description
URL to navigate to the subsequent set of paginated results.
- Name
data[0].id- Type
- integer
- Description
The question's unique unchangeable identifier.
- Name
data[0].type- Type
- single | multiple | dropdown_list | rating | ranking | smiley_scale | numerical_scale | csat
- Description
The question's type
- Name
data[0].question- Type
- string
- Description
Text of the question as displayed to the respondent.
- Name
data[0].introduction- Type
- string
- Description
Introduction to the question as displayed to the respondent.
- Name
data[0].answer_choices[0].id- Type
- integer
- Description
The answer's unique unchangeable identifier.
- Name
data[0].answer_choices[0].content- Type
- string
- Description
Text of the answer option as displayed to the respondent.
- Name
data- Type
- Description
List of the survey's questions and possible answers.
Response
{
"pagination_data": {
"has_more": true,
"next_url": "/surveys/69f3dcf0d3220de7/questions?start=2345"
},
"data": [
{
"id": 372624,
"type": "single | multiple | dropdown_list | rating | ranking | smiley_scale | numerical_scale | csat",
"question": "Would you recommend us to your friend?",
"introduction": "One more quick question.",
"answer_choices": [
{
"id": 0,
"content": "Very happy"
}
]
},
{
"id": 372624,
"type": "text | date",
"question": "Would you recommend us to your friend?",
"introduction": "One more quick question."
},
{
"id": 372624,
"type": "matrix",
"question": "Would you recommend us to your friend?",
"introduction": "One more quick question.",
"answer_choices": [
{
"id": 0,
"content": "Very happy"
}
],
"columns": [
"sample string"
]
},
{
"id": 372624,
"type": "form",
"question": "Would you recommend us to your friend?",
"introduction": "One more quick question.",
"fields": [
{
"type": "sample string",
"label": "sample string"
}
]
},
{
"id": 372624,
"type": "nps",
"question": "Would you recommend us to your friend?",
"introduction": "One more quick question."
},
{
"id": 372624,
"type": "empty | button_close | button_link | button_next | redirect_timeout | social_cta",
"question": "Would you recommend us to your friend?",
"introduction": "One more quick question."
}
]
}