# Description Get the first page of a survey using the campaign/recipient hash ## Request payload ```json { "hash": "...", "uuid": "...", "device": "...", "isTest": ..., "admin": ..., "panelVariables": ... } ``` where: - `hash`: hash of the survey - `uuid`: - `device`: DESKTOP or MOBILE - `isTest`: set test mode (readonly mode) - `admin`: set admin mode (using as channel) - `panelVariables`: panels variables as a json key:value object, where key is the name of the variable ## Response Codes: - 200: in case there is a page to show - 404: project or campaign does not exists - 409: in case of quotas exceded, recipient already submit a response ```json { "page": page object, "currentPage": int, "customization": customization object, "totalPages": int, "projectTitle": string, "projectId": "string", "clientTimezone": "string", "userData": string, } ``` where: - `clientTimezone`: time zone detected using the public IP address of the client (format: `Continent/City`) - `currentPage`: number of the page that should be shown, depends on the project configuration, usualy should be 0 - `customization`: customization object (see [Customization object](#customization-object)) - `page`: page object (see [Page object](#page-object)) - `projectId`: id of the project - `projectTitle`: title of the project - `totalPages`: number of amount of pages available to this project, it should be used for progress bar generation - `userData`: encrypted user information and memory ## Customization object ```json { "backgroundColor": "string", "foregroundColor": "string", "mobilePaging": "string", "paging": "string", "showNumbers": "boolean", "showTitle": "boolean", "disableBackButton": "boolean", "progressBar": { "enabled": "boolean", "type": "string", }, "question": { "font": "string", "color": "string", "align": "string" }, "answer": { "font": "string", "color": "string", "align": "string" }, "nextPreviousButton": { "type": "string", } } ``` where: - `backgroundColor`: Hex color code for the survey's background. - `foregroundColor`: Hex color code of buttons shown in the survey. - `paging`: The type of paging used for the desktop version of the survey. Possible values are: - `none` - `page` - `question` - `mobilePaging`: The type of paging used for the mobile version of the survey. The values are the same of `paging`. - `showNumbers`: Whether the survey should show question numbers or not. - `showTitle`: Whether to show the name of the project in the survey or not. - `disableBackButton`: Whether to disable the back button or not. - `progressBar` - `enabled`: Whether the progress bar is shown or not in the survey. - `type`: The type of progress bar. Possible values are: - `percent` - `bar` - `simple` - `question` - `font`: Font of the questions titles. Defaults to `Source Sans Pro`. - `color`: Color of the font of the questions titles. - `align`: Alignment of the questions titles. - `answer` - `font`: Font of the questions' options. Defaults to `Source Sans Pro`. - `color`: Color of the font of the questions' options. - `align`: Alignment of the questions' options. - `nextPreviousButton` - `type`: Type of the previous button. Possible values are: - `default` - `simple` - `bigger` ## Page object The page object depends on the configuration of the project, the pages types are: ### Welcome page ```json { "type": "WELCOME_PAGE", "welcomeText": string, "termsAndConditions": string } ``` where: - `welcomeText` (optional): html content for welcome message - `termsAndConditions`(optional): html content for terms and conditions message ### End of survey page (last page before submit responses ```json { "type": "END_OF_SURVEY_PAGE", } ``` #### Note: this page only appears when there are skip logic or some configurations for change the visibility of the last item of the project ### Thank you page ```json { "type": "THANK_YOU_PAGE", "endOfSurveyText": string } ``` where: - `welcomeText` (optional): html content for welcome message - `termsAndConditions`(optional): html content for terms and conditions message ### Redirect page ```json { "type": "REDIRECT", "redirectTo": url } ``` where: - `redirectTo`: the url to redirect #### Note: this page replace the thank you page when there is a redirection configured, ### Items page ```json { "type": "QUESTION_PAGE", "items": array of item object (see [available types](#item-types)) } ``` where: - items: is an array of items objects #### item object ```json { "_id": string, "title" (optional): string, "text" (optional): string, "type": string, "subtype" (optional): string, "frontendId": string, "description" (optional): string, "dependentQuestions" (optional): string, "config" (optional): config object, "options" (optional): array of subItems, "rows" (optional): array of subItems } ``` where: - `_id`: question id, used for send answers of a question - `title` (optional): title of the question - `text` (optional): text of a decorator - `type`: item type (see [available types](#item-types)) - `subtype`: item sub-type (see [available types](#item-types)) - `frontendId`: item id used on logic or references to other items - `dependentQuestions`: array of dependent questions frontendIds - `config`: config object (see [Config object](#config-object)) - `options`: array of sub-items objects (see [Sub-type object](#sub-item-types)) - `rows`: array of sub-items objects (see [Sub-type object](#item-types)) #### config object The config object depends on the type of questions, the config types are: ##### Multiple choice (type=multiple, subtype=text,number) ```json { "allowMultipleSelection": "boolean", "anchoredOption": "array", "columnCustomization": "string|number", "displayAs": "string", "exclusiveOptions": "array", "maxResponses": "number", "minResponses": "number", "randomize": "boolean", "image": "string", "allowOther": "boolean", "allowNoneOfAbove": "boolean", "noneOfAboveFrontendId": "number" } ``` where: - `allowMultipleSelection`: Whether the question allows multiple selection or not. - `maxResponses`: Maximum number of responses if `allowMultipleSelection` is set to `true`. - `minResponses`: Minimum number of responses if `allowMultipleSelection` is set to `true`. - `exclusiveOptions`: An array of the frontendIds of the options that are exclusive. If a user selects an option from here, the question is considered to be answered and will ignore the `minResponses` configuration. - `columnCustomization`: The number of columns shown for this question. If the value is `auto`, then the type of the value is `string`. Otherwise, it is a `number`. Possible values are: - `auto` - `1` - `2` - `3` - `displayAs`: Whether the question should be displayed as a list or as a dropdown. Possible values are: - `list` - `dropdown` - `randomize`: Whether the question should randomize its options or not. - `anchoredOption`: An array of the ids of the options that are anchored when `randomize` is set to `true`. These options are always shown at the end of the list of options of the question and are not randomized. - `image`: The URL of the title image (if any). - `allowOther`: Whether the item accepts "Other" as an answer or not. - `allowNoneOfAbove`: Whether the item accepts "None of above" as an answer or not. - `noneOfAboveFrontendId`: FrontendId of the "None of above" option if `allowNoneOfAbove` is set to `true`. ##### Multiple choice image ```json { "imageSize": "string", "showTitles": "boolean", "fitCover": "boolean" } ``` where: - `imageSize`: The size of the image. Possible values are: - `small` - `medium` - `large` - `showTitles`: Whether the titles of the images should be shown or not. - `fitCover`: If set to `false`, the image is not going to keep its aspect ratio. ##### Grid / Rating scale (type=grid,subtype=undefined) ```json { "allowMultipleSelectionPerRow": "boolean", "maxResponsesPerRow": "number", "minResponsesPerRow": "number", "displayAs": "string", "autoPopulateData": "string", "displayNaColumn": "boolean", "randomize": "boolean", "randomizeColumns": "boolean", "requires": { "type": "string", "value": "number", "min": "number", "max": "number" }, "rowPerPage": "boolean", "shouldForceRanking": "boolean" } ``` where: - `allowMultipleSelectionPerRow`: Whether the user can select multiple choices for each row or not. - `maxResponsesPerRow`: Maximum number of responses if `allowMultipleSelectionPerRow` is set to `true`. - `minResponsesPerRow`: Minimum number of responses if `allowMultipleSelectionPerRow` is set to `true`. - `displayAs`: Whether the question should be displayed as multiple rows or a single row. Possible values are: - `multipleRows` - `singleRow` - `autoPopulateData`: Whether the rows come from another source or not. - `displayNaColumn`: Whether an additional N/A column should be displayed or not. - `randomize`: Whether rows should be randomized or not. - `randomizeColumns`: Whether columns should be randomized or not. - `requires` - `type`: Whether the question requires to answer all rows or not. Possible values are: - `all` - `exactly` - `atLeast` - `atMost` - `range` - `value`: If `type` is `exactly`, `atLeast` or `atMost`, then a value must be specified. - `min`: If `type` is `range`, then a minimum number of rows to answer must be set. - `max`: If `type` is `range`, then a maximum number of rows to answer must be set. - `rowPerPage`: Whether we should display the question by row or not. - `shouldForceRanking`: Whether we should force ranking (one response per column) or not. ##### NPS (type=grid,subtype=nps) ```json { "allowComments": "boolean", "leftLabel": "string", "rightLabel": "string", } ``` where: - `allowComments`: Whether NPS allows comments or not. - `leftLabel`: The label of left anchor. - `rightLabel`: The label of the right anchor. We also force the following properties inside `config`: - `displayAs`: `promoter` - `requires` - `type`: `all` ##### Max diff basic (type=grid,subtype=max-diff) ```json { "allowMultipleSelectionPerRow": false, "displayAs": "multipleRows", "requires": { "type": "exactly", "value": "2", }, "shouldForceRanking": "true", } ``` ###### Note: Always has the same config object ##### Max diff experiment (type=grid,subtype=max-diff-experiment) ```json { "numberOfSets": "number", "setSize": "number" } ``` where: - `numberOfSets`: The number of sets to be shown in the survey. - `setSize`: The size of each set. We also force the following properties inside the config object: - `allowMultipleSelectionPerRow`: `false` - `displayAs`: `multipleRows` - `requires` - `type`: `exactly` - `value`: `2` - `shouldForceRanking`: `true` ##### Rank order (type=rank,subtype=undefined) ```json { "randomize": "boolean", } ``` where: - `randomize`: Whether the options are randomized or not. ##### Scale (type=scale,subtype=slider,icon) ```json { "granularity": "number", "leftLabel": "string", "rightLabel": "string", "minValue": "number", "maxValue": "number" } ``` where: - `granularity`: The granularity of the scale. If `subtype` is `icon`, possible values are: - 1 - 0.5 - `leftLabel`: The far left side of scale answer. Only available when `subtype` is `slider`. - `rightLabel`: The far right side of scale answer. Only available when `subtype` is `slider`. - `minValue`: The minimum value of the scale. - `maxValue`: The maximum value of the scale. ##### Text entry (type=input,subtype=text) ```json { "maxLength": "number", "multipleInputs": "boolean" } ``` where: - `maxLength`: If the short response option is enabled, then `maxLength` is equal to `250`. Otherwise, its value is `0`. - `multipleInputs`: Whether we should show multiple inputs or not. ##### Numeric entry (type=input,subtype=number) ```json { "minValue": "number", "maxValue": "number", "allowDecimals": "boolean", "multipleInputs": "boolean", "maxLength": "number" } ``` where: - `minValue`: The minimum number allowed. - `maxValue`: The maximum number allowed. - `allowDecimals`: Whether decimals are allowed or not. - `multipleInputs`: Whether multiple inputs should be shown or not. ##### Constant sum (type=constant-sum,subtype=undefined) ```json { "validationType": "string", "mustTotalValue": "number", "minSumValue": "number", "maxSumValue": "number", "randomize": "boolean" } ``` where: - `validationType`: Validation type of the total sum. Possible values are: - `mustTotal` - `range` - `mustTotalValue`: Total sum value when `validationType` is `mustTotal`. - `minSumValue`: Minimum total sum when `validationType` is `range`. - `maxSumValue`: Maximum total sum when `validationType` is `range`. - `randomize`: Whether the rows are randomized or not. ##### Text block (type=decorator,subtype=info) This type of item doesn't have config object ##### Date (type=date,subtype=undefined) ```json { "maxYear": "number", "minYear": "number" } ``` where: - `maxYear`: The maximum year to be shown in the survey. - `minYear`: The minimum year to be shown in the survey. ##### Contact info (type=contact-info,subtype=undefined) ```json { "showAddressLine1": "boolean", "showAddressLine2": "boolean", "showCountry": "boolean", "showEmail": "boolean", "showFirstName": "boolean", "showLastName": "boolean", "showPhone": "boolean", "showUsState": "boolean", "showZipCode": "boolean", "countryMultipleChoiceId": "number", "stateMultipleChoiceId": "number" } ``` where: - `showAddressLine1`: Show the address line 1 field in the survey or not. - `showAddressLine2`: Show the address line 2 field in the survey or not. - `showCountry`: Show the country selector in the survey or not. - `showEmail`: Show the email field in the survey or not. - `showFirstName`: Show the first name field in the survey or not. - `showLastName`: Show the last name field be asked in the survey or not. - `showUsState`: Show the US State selectorin the survey or not. - `showZipCode`: Show the zip code field in the survey or not. - `countryMultipleChoiceId`: If `showCountry` is set to `true`, another item (more specifically, a multiple choice question where the options are the countries) is created automatically. This field represents the id of that new item. - `stateMultipleChoiceId`: If `showUsState` is set to `true`, another item (more specifically, a multiple choice question where the options are the US states) is created automatically. This field represents the id of that new item. ##### Conjoint (type=conjoint,subtype=undefined) ```json { "numberOfCardsPerSet": "number", "numberOfSets": "number", "allowNone": "boolean", } ``` where: - `numberOfCardsPerSet`: The number of cards per set to be shown in the survey. - `numberOfSets`: The number of sets to be shown in the survey. - `allowNone`: Whether we should allow the "None" card or not. ##### Concept test (type=decorator,subtype=concept-test) ```json { "type": "string", "url": "string", "title": "string", "hideLinkAfterShow": "boolean", "timeToDisplay": "number", "videoId": "string", "thumbnailUrl": "string" } ``` where: - `type`: Type of concept to be shown. Possible values are: - `imageUpload` - `youtubeVideo` - `externalLink` - `audio` - `url`: URL of the image, video or external link. - `title`: Name of the concept (if any). - `hideLinkAfterShow`: Whether the link of the resource should be hidden or not after it was shown in the survey. - `timeToDisplay`: The number of seconds the image, video or external link should be displayed in the survey. - `videoId`: Id of the YouTube video. Only present if `type` is `youtubeVideo`. - `thumbnailUrl`: URL of the external link. Only present if `type` is `externalLink`. #### sub-item object ```json { "frontendId": string, "label": string, "position": string, "allowComments": boolean, "isOther": boolean, "isNoneOfAbove": boolean, "labelCatalogItemId": string, "imageCatalogItemId": string, "isDisabled": boolean, "questionId": string, "questionFrontendId": string, "url": string, "image": string, "allowLevelImages": boolean, "levels": array of strings, "enableRangeLevels": boolean, "validation": string, "rangeStep": number, "rangeStart": number, "rangeEnd": number, "autopopulated": string, "sourceId": string, } ``` where: - `frontendId`: sub-item id used on logic or references to other items - `label`: sub-item label - `position`: sub-item position, used to send answers - `allowComments`: if the questions - `isOther` (optional): sub-item is an "other" option, - `isNoneOfAbove` (optional): sub-item is an "none of above" option, - `labelCatalogItemId` (optional): catalog item id for label, - `imageCatalogItemId` (optional): catalog item id for image, - `isDisabled`: (optional): sub-item is disabled, - `questionId`: (optional): question id of dependent question only works for multiple numeric/text entry, - `questionFrontendId`: (optional): frontendId of dependent question only works for multiple numeric/text entry, - `url`: url of an image in case the question is image multiple-choice question, - `image`: url of an image in case the question is grid - `validation`: , - `autopopulated`: (optional): sub-item is populated, - `sourceId`: (optional): sub-item frontend id of populated source option, only works when option is populated, options for conjoint rows: - `levels`: is an array of options frontendIds (levels) that belong to the row (attribute) - `enableRangeLevels`: the row (attribute) is a range base - `rangeStep`: granularity of the attribute(only works when enableRangeLevels is enabled) - `rangeStart`: higher limit (only works when enableRangeLevels is enabled) - `rangeEnd`: lower limit (only works when enableRangeLevels is enabled) - `allowLevelImages`: allow images on level (only works when enableRangeLevels is disabled) ## Item types - `multiple`: Multiple choice question, sub-type can be `text`, `number` or `ìmage` - `input`: Entry question, sub-type can be `text` or `number` - `scale`: Scale question, sub-type can be `slider` or `icon` - `grid`: Grid question, sub-type can be `nps` or `max-diff-experiment` or `max-diff` or `undefined` - `conjoint` Conjoint question, doesn't have sub-type - `rank`: Rank question, doesn't have sub-type - `decorator`: Decorators blocks, sub-type can be `info` or `concept-test` - `constant-sum`: Constant sum question, doesn't have sub-type - `date`: Date question, doesn't have sub-type - `contact-info`: Contact info question, doesn't have sub-type