--- title: Survey description: >- Surveys represent individual questionnaires within your workspace. Each survey contains a series of questions designed to gather information or opinions from respondents. source_url: html: 'https://developers.survicate.com/data-export/survey/' md: 'https://developers.survicate.com/data-export/survey.md' --- # 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 GET /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. If omitted, the API applies its default page size. Name: start Type: string Description: Optional newer bound of the creation date range, and the point the page starts from. Surveys are ordered from latest to oldest, so 'start' is the later of the two timestamps: surveys created at or before it are included (inclusive). The timestamp should be in the ISO 8601 format, including microseconds (e.g., '2023-01-01T00:00:00.000000Z'). Name: end Type: string Description: Optional older bound of the creation date range. Surveys are ordered from latest to oldest, so 'end' is the earlier of the two timestamps: surveys created at or after it are included (inclusive). The timestamp should be in the ISO 8601 format, including microseconds (e.g., '2023-01-01T00:00:00.000000Z'). ### Response 200 The operation was successful, and the requested data has been returned in the response. #### 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: Path to the next set of paginated results. It is always returned as a path relative to the API base URL (https://data-api.survicate.com/v2), never as an absolute URL, so prepend the base URL and request it as-is. Only present when 'has_more' is true. 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. ```json { "pagination_data": { "has_more": { "value": true, "description": "Specifies if additional pages are available for retrieval (True or False)." }, "next_url": { "value": "/surveys?start=2023-01-01T00:00:00.000000Z", "description": "Path to the next set of paginated results. It is always returned as a path relative to the API base URL (https://data-api.survicate.com/v2), never as an absolute URL, so prepend the base URL and request it as-is. Only present when 'has_more' is true." } }, "data": [ { "id": { "value": "69f3dcf0d3220de7", "description": "The survey's unique unchangeable identifier." }, "type": { "value": "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:\n* PageSurvey is Email & Sharable Link Survey\n* WidgetSurvey is Web & In-Product Survey\n* MobileSurvey is Mobile App Survey\n* IntercomSurvey is Intercom Messenger Survey\n" }, "name": { "value": "Customer satisfaction survey", "description": "The name of the survey." }, "created_at": { "value": "2023-01-13T00:00:00.000000Z", "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')." }, "enabled": { "value": true, "description": "Indicates whether a survey is available for respondents (true or false)." }, "responses": { "value": 34206, "description": "The total number of survey responses." }, "launch": { "value": { "start_at": { "value": "2023-06-13T00:00:00.000000Z", "description": "Date when the survey will start appearing to respondents." }, "end_at": { "value": "2023-06-31T00:00:00.000000Z", "description": "Date when the survey will stop appearing to respondents." }, "responses_limit": { "value": 1400, "description": "The survey will stop being available to respondents after collecting that amount of responses." } }, "description": "Indicates whether the survey is scheduled to start or stop being available at a specific date." } } ] } ``` --- ## Retrieve survey information GET /surveys/{survey_id} 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 200 The operation was successful, and the details of the requested survey have been returned. #### 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'). Name: attributes Type: ["string"] Description: The names of the respondent attributes passed to Survicate together with this survey's responses (for example through the JavaScript or mobile SDK, or the survey link), sorted alphabetically. Attributes synced from integrations are not included. The response endpoints return only the attributes you name in their 'attributes[]' parameter, so use this list to know which names to request. ```json { "id": { "value": "69f3dcf0d3220de7", "description": "The survey's unique unchangeable identifier." }, "type": { "value": "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:\n* PageSurvey is Email & Sharable Link Survey\n* WidgetSurvey is Web & In-Product Survey\n* MobileSurvey is Mobile App Survey\n* IntercomSurvey is Intercom Messenger Survey\n" }, "name": { "value": "Customer satisfaction survey", "description": "The name of the survey." }, "created_at": { "value": "2023-01-13T00:00:00.000000Z", "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')." }, "enabled": { "value": true, "description": "Indicates whether a survey is available for respondents (true or false)." }, "responses": { "value": 34206, "description": "The total number of survey responses." }, "launch": { "value": { "start_at": { "value": "2023-06-13T00:00:00.000000Z", "description": "Date when the survey will start appearing to respondents." }, "end_at": { "value": "2023-06-31T00:00:00.000000Z", "description": "Date when the survey will stop appearing to respondents." }, "responses_limit": { "value": 1400, "description": "The survey will stop being available to respondents after collecting that amount of responses." } }, "description": "Indicates whether the survey is scheduled to start or stop being available at a specific date." }, "author": { "value": { "name": { "value": "John Doe", "description": "The full name of the individual who created the survey." }, "email": { "value": "john.doe@example.com", "description": "The email address of the individual who created the survey." } }, "description": "Provides basic information about the creator of the survey." }, "folder": { "value": "Marketing Team Surveys", "description": "The name of the folder in which the survey is stored." }, "first_response_at": { "value": "2023-06-13T00:00:00.000000Z", "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')." }, "last_response_at": { "value": "2023-06-31T00:00:00.000000Z", "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')." }, "attributes": { "value": [ "order_id" ], "description": "The names of the respondent attributes passed to Survicate together with this survey's responses (for example through the JavaScript or mobile SDK, or the survey link), sorted alphabetically. Attributes synced from integrations are not included. The response endpoints return only the attributes you name in their 'attributes[]' parameter, so use this list to know which names to request." } } ``` ### Response 404 The specified survey could not be found. --- ## List questions GET /surveys/{survey_id}/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. If omitted, the API applies its default page size. 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 200 The operation was successful, and the details of the requested survey have been returned. #### 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: Path to the next set of paginated results. It is always returned as a path relative to the API base URL (https://data-api.survicate.com/v2), never as an absolute URL, so prepend the base URL and request it as-is. Only present when 'has_more' is true. 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: [{"id":{"value":"integer","description":"The question's unique unchangeable identifier."},"type":{"value":"single | multiple | dropdown_list | rating | ranking | smiley_scale | numerical_scale | csat","description":"The question's type"},"question":{"value":"string","description":"Text of the question as displayed to the respondent."},"introduction":{"value":"string","description":"Introduction to the question as displayed to the respondent."},"answer_choices":[{"id":{"value":"integer","description":"The answer's unique unchangeable identifier."},"content":{"value":"string","description":"Text of the answer option as displayed to the respondent."}}]},{"id":{"value":"integer","description":"The question's unique unchangeable identifier."},"type":"text | date","question":{"value":"string","description":"Text of the question as displayed to the respondent."},"introduction":{"value":"string","description":"Introduction to the question as displayed to the respondent."}},{"id":{"value":"integer","description":"The question's unique unchangeable identifier."},"type":"matrix","question":{"value":"string","description":"Text of the question as displayed to the respondent."},"introduction":{"value":"string","description":"Introduction to the question as displayed to the respondent."},"answer_choices":[{"id":{"value":"integer","description":"The answer's unique unchangeable identifier."},"content":{"value":"string","description":"Text of the answer option as displayed to the respondent."}}],"columns":["string"]},{"id":{"value":"integer","description":"The question's unique unchangeable identifier."},"type":"form","question":{"value":"string","description":"Text of the question as displayed to the respondent."},"introduction":{"value":"string","description":"Introduction to the question as displayed to the respondent."},"fields":[{"type":"string","label":"string"}]},{"id":{"value":"integer","description":"The question's unique unchangeable identifier."},"type":"nps","question":{"value":"string","description":"Text of the question as displayed to the respondent."},"introduction":{"value":"string","description":"Introduction to the question as displayed to the respondent."}},{"id":{"value":"integer","description":"The question's unique unchangeable identifier."},"type":"empty | button_close | button_link | button_next | redirect_timeout | social_cta","question":{"value":"string","description":"Text of the question as displayed to the respondent."},"introduction":{"value":"string","description":"Introduction to the question as displayed to the respondent."}}] Description: List of the survey's questions and possible answers. ```json { "pagination_data": { "has_more": { "value": true, "description": "Specifies if additional pages are available for retrieval (True or False)." }, "next_url": { "value": "/surveys/69f3dcf0d3220de7/questions?start=2345", "description": "Path to the next set of paginated results. It is always returned as a path relative to the API base URL (https://data-api.survicate.com/v2), never as an absolute URL, so prepend the base URL and request it as-is. Only present when 'has_more' is true." } }, "data": { "value": [ { "id": { "value": 372624, "description": "The question's unique unchangeable identifier." }, "type": { "value": "single | multiple | dropdown_list | rating | ranking | smiley_scale | numerical_scale | csat", "description": "The question's type" }, "question": { "value": "Would you recommend us to your friend?", "description": "Text of the question as displayed to the respondent." }, "introduction": { "value": "One more quick question.", "description": "Introduction to the question as displayed to the respondent." }, "answer_choices": [ { "id": { "value": 0, "description": "The answer's unique unchangeable identifier." }, "content": { "value": "Very happy", "description": "Text of the answer option as displayed to the respondent." } } ] }, { "id": { "value": 372624, "description": "The question's unique unchangeable identifier." }, "type": "text | date", "question": { "value": "Would you recommend us to your friend?", "description": "Text of the question as displayed to the respondent." }, "introduction": { "value": "One more quick question.", "description": "Introduction to the question as displayed to the respondent." } }, { "id": { "value": 372624, "description": "The question's unique unchangeable identifier." }, "type": "matrix", "question": { "value": "Would you recommend us to your friend?", "description": "Text of the question as displayed to the respondent." }, "introduction": { "value": "One more quick question.", "description": "Introduction to the question as displayed to the respondent." }, "answer_choices": [ { "id": { "value": 0, "description": "The answer's unique unchangeable identifier." }, "content": { "value": "Very happy", "description": "Text of the answer option as displayed to the respondent." } } ], "columns": [ "sample string" ] }, { "id": { "value": 372624, "description": "The question's unique unchangeable identifier." }, "type": "form", "question": { "value": "Would you recommend us to your friend?", "description": "Text of the question as displayed to the respondent." }, "introduction": { "value": "One more quick question.", "description": "Introduction to the question as displayed to the respondent." }, "fields": [ { "type": "sample string", "label": "sample string" } ] }, { "id": { "value": 372624, "description": "The question's unique unchangeable identifier." }, "type": "nps", "question": { "value": "Would you recommend us to your friend?", "description": "Text of the question as displayed to the respondent." }, "introduction": { "value": "One more quick question.", "description": "Introduction to the question as displayed to the respondent." } }, { "id": { "value": 372624, "description": "The question's unique unchangeable identifier." }, "type": "empty | button_close | button_link | button_next | redirect_timeout | social_cta", "question": { "value": "Would you recommend us to your friend?", "description": "Text of the question as displayed to the respondent." }, "introduction": { "value": "One more quick question.", "description": "Introduction to the question as displayed to the respondent." } } ], "description": "List of the survey's questions and possible answers." } } ``` ### Response 404 The specified survey could not be found.