Skip to main content
POST
Get survey first page

​
Description

Get the first page of a survey using the campaign/recipient hash

​
Request payload

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
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)
  • page: page object (see 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

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

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

​
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

where:
  • welcomeText (optional): html content for welcome message
  • termsAndConditions(optional): html content for terms and conditions message

​
Redirect page

where:
  • redirectTo: the url to redirect

​
Note:

this page replace the thank you page when there is a redirection configured,

​
Items page

where:
  • items: is an array of items objects

​
item object

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)
  • subtype: item sub-type (see available types)
  • frontendId: item id used on logic or references to other items
  • dependentQuestions: array of dependent questions frontendIds
  • config: config object (see Config object)
  • options: array of sub-items objects (see Sub-type object)
  • rows: array of sub-items objects (see Sub-type object)

​
config object

The config object depends on the type of questions, the config types are:
Multiple choice (type=multiple, subtype=text,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
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)
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)
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)
Note:
Always has the same config object
Max diff experiment (type=grid,subtype=max-diff-experiment)
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)
where:
  • randomize: Whether the options are randomized or not.
Scale (type=scale,subtype=slider,icon)
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)
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)
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)
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)
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)
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)
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)
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

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

Authorizations

​
Authorization
string
header
required

Access token obtained from the m2m-token endpoint.

Body

application/json

The body is of type object.

Response

Successful response