Self-installation requires Decipher Cloud & Server Admin. Contact your Account Manager if you're interested in setting up Sample API.
1: What is Sample & Panel API?
Sample API allows the sample or panel provider to communicate via API with their server using JSON objects to pull in stored respondent data for use in Decipher surveys. The sample API benefits users that manage their own regularly changing panels or lists of respondents and the associated information, such as demographics, firmogramphics or similar categorical data.
The steps for enabling the sample API can be found here:
2: Using Sample & Panel API in the Survey Editor
To use the sample/panel from your API in the survey editor, simply click "Add Survey Element," or click on the sample element in the question tree and select "Add New Sample Source."
Select the "Sample Sources" tab, then select the Sample API and click "Insert." This name is determined from
"sampleName" during setup, however you may edit how it will appear in the report using the field provided.
2.1: Select Questions & a List
The right panel contains the lists of questions configured by the sample API (if applicable). Select the questions you'd like to pull from the list, then click "Check for Available Lists."
If a list of questions wasn't configured, simply click "Check for Available Lists," and all questions will be added from the chosen list.
Choose a list from the options. Select the list and click "Use Selected List."
A list is rejected for the following reasons:
- A question(s) does not exist in the list retrieved from the API.
- Note the question label(s) and click "Ok" to close the warning window. Then uncheck the question(s) and click "Check for Available Lists" again.
- A unique variable is not included in the selected list.
- The unique variable must be specified in the
sampleproviders.pyfile. Then return to this step to sync the information.
- The unique variable must be specified in the
When the list is successfully matched to the questions, the API configuration will look similar to the screenshot below. The sample list variables are also generated as individual elements, tracking the imported the data once available.
2.2: URL Variables
The Sample and Panel API requires a unique variable during setup, when the
sampleproviders.py file is configured. This variable is automatically added in the element and is not editable within the element. The variable is appended to the respondent's URL when they enter the survey, and is used to retrieve the corresponding data for the report.
To add an additional variable, select "+ Variable." Then configure the variable options:
- Var Name: The variable that's appended to the URL for this sample provider.
- Required: Allows you to specify if the variable is optional, required or unique.
- Optional: The variable does not have to be included in the URL for the respondent to take the survey.
- Required: The variable must be included in the URL for the respondent to be able to take the survey.
- Unique: The variable must be included in the URL for the respondent to be able to take the survey, and it must contain a unique value as tracked by the survey system.
- Authentication: Allows you to specify how you would like to validate the variable.
- If the requirement is set to "Optional," no authentication can be set.
- If the requirement is set to "Required" you can specify No Authentication, meaning the variable is required in the URL but can be anything, or you can select Value List, which allows you to specify the valid values for your variable.
- If the requirement is set to "Unique" you can specify No Authentication, meaning the variable is required in the URL but can be anything and the system will use internal tracking to verify the uniqueness of the value. You can also select File, which allows you to upload a file that contains the values you wish to verify variable values against. The file must be plain text (.txt) with one value per line, one column only.
- Note: If you upload a file, the file name will not match the name of the uploaded file. This is a security precaution.
Once the variable has been defined, click "Save." The variable will be added for the custom sample source. To delete the variable, click on the "X" next to the variable name. To edit the variable, simply make changes using the dropdown menus and fields within the element.
2.3: Exit Pages
The exit pages are laid out for you to configure for terminated, over-quota and qualified respondents. Simply select "Message" to show the respondent a message at the end of the survey, or choose "Redirect" and enter the URL in the field provided.
You also have the ability to add a custom exit page and define the logic condition for it. Click here to learn more.