Global Definitions

This section provides an overview of the key terms used to organize and understand various survey components, including events, actions, and attributes like countries, languages, and survey properties.

Name	Description	Definition Key
Countries	A list of country names along with their respective two-letter codes.	country
Language	A list of languages available for surveys.	language
Categories	The categories that surveys belong to, help in classifying them.	categories
Survey Statuses	List of Survey Statuses	surveyStatus
Device Types	All surveys have a list of devices on which they can participate.	devicetype
Question type	List of question types	questionType

Qualifications

Qualifications or Questions and Answers are key features of the integration. They are essential for Survey Targeting and Respondent Management.
These Questions and Answers help target surveys and manage quotas, so it's important to ensure that the values on your platform are correctly mapped. If respondents don’t match the survey qualifications, you might see terminations.
We offer various ways to retrieve questions and their answers, as detailed below.

Question Model

Here's an example :

{
      "questionId": 2814,
      "questionText": "What is your age?",
      "questionKey": "AGE",
      "questionType": "Numeric Open End",
      "language": "ENGLISH",
      "questionCategory": [
        "Demographic"
      ]
    }

Details of the model properties

Property	Description
questionId	The numerical ID of the Question.
questionText	The prompt is presented to respondents.
questionKey	The Primary Identifier of the Question is used throughout the our platform.
questionType	The answer type of the Question.
language	The associated language of the Question.
questionCategory	The associated Question Categories of the Question.

Answer Model

Here's an example :

"questionOptions": [
               {
                   "OptionText": "Male",
                   "id": 1,
                   "Order": 1
               },
               {
                   "OptionText": "Female",
                   "id": 2,
                   "Order": 2
               }
           ]

Details of the model properties

Property	Description
id	The numerical ID of the Answer.
OptionText	The answer value that the respondent can choose.
Order	Order that the answer option will be presented to the respondent (Ascending order).

Please note: For Open-Ended or Numeric Questions, there are no Answer Options since the respondent provides the value.

Managing Survey Inventory

In this section, we explore how the inventory-based methodology enables efficient management of available survey data and the steps required to integrate and effectively utilize survey information on the platform.

Core Concepts of Our Survey Workflow

1. Project Id

The "parent" entity for a survey, the Project ID is linked to multiple surveys within the system. Each project can contain several surveys that fall under its umbrella.

2. Survey Attributes

The fundamental unit within our platform is the survey itself. It is here that essential details such as pricing, sample size, and other important parameters are specified. Key survey attributes include:

LOI (Length of Interview)

IR (Incidence Rate)

N (Sample Size)

Country

Language

3. Survey Qualifications (Targeting)

Every survey requires specific qualifications or "targeting" criteria, which define the type of respondents eligible to participate. These qualifications act as filters, ensuring only qualified participants are selected. Targeting is mandatory for all surveys.

4. Survey Quota

Quotas are used to limit the number of respondents in specific survey categories or segments. Quotas are optional, meaning not all surveys will have them. If quotas are set, they help manage the sample distribution and ensure the survey targets the right demographic.

Survey Example Walkthrough
To better understand how surveys, qualifications, and quotas work together, let’s walk through an example:

Scenario:
A smartphone firm wants to conduct a survey to understand consumer preferences for a new smartphone.

Survey A: Smartphone User Preferences
Number of Respondents (N): 200 respondents
Cost per Interview (CPI): $20
Length of Interview (LOI): 30 minutes
Incidence Rate (IR): 50%

Qualifications:

Age: 18-35 years old

Smartphone Ownership: Owns a smartphone

Location: Resides in urban areas within the United States

Quotas:

Gender:

Male: 50%

Female: 50%

Age:

18-24: 30%

25-35: 70%

In this case, The goal is to collect responses from 200 qualified respondents, all of whom must meet the specified qualifications and fall within the designated quota limits.
Once a quota limit (e.g., 50% male or 30% for ages 18-24) is met, no additional respondents within that category will be accepted, even if the overall sample size of 200 respondents has not yet been reached.

Managing Survey Inventory: Step-by-Step Guide

This section outlines the process for managing survey inventory, including fetching available surveys, retrieving qualification and quota details, and understanding how these elements work together.

Step 1: Fetching the Survey Inventory

To access the available survey inventory, use the "Get Available Surveys" API endpoint. This call provides a list of all currently active surveys available for participation. Since the inventory is updated in real-time—new surveys become accessible, and paused/closed ones are removed. We recommend refreshing the inventory every 5 minutes to stay up-to-date.

If you need to retrieve information for a specific survey, you can use the "Get Available Surveys By Id" endpoint.

Survey Availability

When a survey appears in the "Get Available Surveys" response, it indicates that the survey is currently live and available for use. If a survey no longer appears in the response, it may no longer be active or could be temporarily paused. As surveys can change status frequently, it's important to set up your system to handle such fluctuations and avoid missing opportunities.

To track surveys that have been paused or closed, you can use the "Get Available Surveys By Id" endpoint for detailed information.

Step 2: Survey Qualifications

Survey qualifications define the specific requirements that respondents must meet to participate in a survey. After retrieving the survey inventory, the next step is to fetch the qualifications for each survey using the "Get Available Surveys By Id" API. This data will provide the demographic or behavioral criteria needed to qualify for participation.

Step 3: Survey Quotas

While qualifications specify the type of respondents required for a survey, quotas determine how many respondents from each qualification group are needed. For example, a survey may require participants aged 18-36, but a quota can specify that 10 participants be from the 18-25 age group and 15 participants from the 26-36 age group.

Example Quota Response

Here’s an example of a response containing quota details for a survey:

 {
                "id": 41,
                "quotaName": "GROCERY",
                "title": "GROCERY",
                "quotaN": 1,
                "hardStop": true,
                "clk": 0,
                "cmp": 0,
                "hardStopType": 0,
                "quotaStatus": "Open",
                "RemainingN": 1,
                "targeting": {
                    "STANDARD_GROCERY_STORES_US": [
                        {
                            "OptionId": 2,
                            "OptionText": "Albertsons"
                        },
                        {
                            "OptionId": 3,
                            "OptionText": "Costco"
                        },
                        {
                            "OptionId": 4,
                            "OptionText": "Food Lion"
                        },
                        {
                            "OptionId": 5,
                            "OptionText": "Giant"
                        }
                    ]
                }
}

Understanding Quota Properties

Here’s what each property in the quota response represents:

Field	Value Type	Meaning
quotaN	Integer	The total number of completions required for this quota.
RemainingN	Integer	The number of completions still needed for this quota.
quotaStatus	“Open" / "Closed"	"Open" means respondents can still participate; "Closed" means no further participation is allowed.
hardStop	Boolean (true/false)	Indicates whether the quota has a hard or soft limit. If true, respondents will receive an "OverQuota" rejection if they qualify; if false, they won't.
hardStopType	Integer (0 or 1)	If 0, the quota is based on completions. If 1, it is based on survey starts.
targeting	{object}	Contains the specific qualification criteria for this quota.

Survey Exclusions

The excluded_surveys field in a survey indicates the surveys that are either "linked" or set to prevent respondent duplication for this specific survey. It doesn't refer to literal duplicates but rather ensures that respondents who have already interacted with related surveys are not eligible for the current one.

How to Interpret Exclusions

Any respondent who has a status listed in the excluded_status field for the surveys in the excluded_surveys field should not be routed to this survey. If they attempt to participate, they will automatically be rejected to avoid duplication.

Example of Survey Exclusion

{
  "surveyId": 1,
  "Language": "ENGLISH",
  "reContact": false,
  "surveyLiveURL": "https://www.example.com/screener?survey=z36mXYbQ&supplierId=2&pid=",
  "actualIR": 0,
  "actualLOI": 0,
  "excluded_surveys": [5, 6, 7, 8, 9, 10],
  "excluded_status": [
    "Client Completes",
    "Client Fails",
    "Client OverQuota",
    "Client Quality Termination"
  ]
}

In this example, the excluded_surveys field lists surveys 5, 6, 7, 8, 9, and 10. Any respondent who has participated in one of these surveys and has a status of “Client Completes,” “Client Fails,” “Client OverQuota,” or “Client Quality Termination” will be automatically excluded from participating in this survey.

Clarification of Survey Exclusion

For instance, if a respondent has previously participated in surveys 3792333, 3861802, or 3571128 and received any of the following statuses—“Client Completes,” “Client Fails,” “Client OverQuota,” or “Client Quality Termination”, they will not be eligible to participate in survey 3571128. This exclusion helps prevent repeated participation from the same respondent in linked surveys.

Respondent Journey: From Survey Entry to Completion

This section provides a detailed guide on how to effectively route respondents to surveys, manage their interactions, and ensure a smooth return to your platform.

Respondent Journey Overview

The general flow of the respondent’s journey can be outlined as follows:

Supplier Platform → Our Platform → Client Survey/Questionnaire → Our Platform → Supplier Platform

This process can be divided into three key stages:

Survey Initiation Phase: The respondent begins on your platform (the Supplier) and is directed to our platform.

In-Survey Phase: The respondent participates in the survey hosted on our platform or within a client questionnaire.

Survey Completion Phase: After completing the survey, the respondent is directed back to our platform via a return link.

Identifying Respondents

Respondents are identified by a Panelist ID (PID), which is unique and persistent for each individual. This ensures consistent tracking and allows respondents to be reliably recognized each time they are directed to a survey.

For example, when a participant engages in a survey, their Respondent ID (RID) remains constant each time they are directed to our platform for any survey.

If you need to pass a Session Identifier for the participant, you can include it in a query string parameter called trackId. The value provided through this parameter can be returned to your platform via the Redirect URL.

Routing Respondents to Surveys (Survey Initiation)

Each survey in our platform is associated with a unique surveyLiveURL, which links respondents from your platform to ours. This URL is crucial for routing the respondent to the right survey.

Here’s an example of how this surveyLiveURL might look after calling the Get Available Surveys API endpoint:

...
{
"surveyId": 1,
"Status": "Live",
"survayName": "India",
"N": 1,
"CPI": 3,
"remainingN": 1,
"LOI": 1,
"IR": 1,
"Country": "India",
"Language": "ENGLISH",
"reContact": false,
"surveyLiveURL": "https://www.example.com/screener?survey=z36mXYbQ&supplierId=2&pid=",
...
}
...

Key Components of the Survey Entry Link

When you use the surveyLiveURL to route respondents, it’s important to understand the following key components:

Landing Page: https://www.example.com/screener?

This is the initial page where all respondents will arrive to begin the survey process.

Survey Identifier: survey

An encrypted code that uniquely identifies the survey, ensuring the respondent is routed to the correct one.

Supplier Identifier: supplierId

This parameter tracks the source of the respondent (your platform) and helps us monitor traffic coming from your system.

Respondent ID: pid

The unique identifier for each respondent, must remain consistent for every survey the respondent participates in.

Session ID: trackId

If you need to pass a Session ID for the respondent, you can include it in a query string parameter labeled trackId.

Together, these parameters ensure the respondent is properly routed through the survey flow.

Routing Respondents to the Client Survey (In-Survey)

Once the respondent reaches our platform, they undergo necessary pre-survey validations and checks. After successfully passing these checks, they are directed to the appropriate Client Survey or Questionnaire.

Once the respondents have completed the survey, they are quickly redirected back to our platform for final processing, and soon after, they are routed back to your platform through the specified redirect URL.

Redirecting Respondents Back to Your Platform (Survey Completion)

To complete the respondent’s journey back to your platform, we need to know where to send them after survey completion. This is handled by the Redirect URL, which you provide in advance.

The Redirect URL is critical for ensuring that respondents are routed back to your platform, along with any necessary data that needs to be passed through.

Redirect URLs: Directing Respondents Based on Survey Outcomes

When a respondent finishes their survey, they must be redirected back to your platform. This is achieved through a Redirect URL, which ensures the respondent is sent to the correct webpage based on the survey outcome.

The pages linked to your Redirect URLs should be configured to capture any necessary data and guide the respondent through the next steps, depending on their survey results.

Overview of Redirect URL Categories

To handle respondents accurately, our platform provides various categories of Redirect URLs based on the survey results. These URLs correspond to specific transaction statuses and help direct respondents based on their participation outcome:

Category	Description	Transaction Statuses
Successful Completion	Used when a respondent completes the survey.	Client Completes
Survey Termination	Triggered when a respondent is terminated mid-survey by the client.	Client Fails
Quota Exceeded	Used when a respondent is categorized as over quota by the client.	Client OverQuota
Quality	Applied when a respondent is disqualified due to quality issues during the survey.	Client Quality Termination
Screener Exit	Used when a respondent does not meet the qualifications or encounters Screener issues.	Screener Dropouts, Screener Terminates, Screener OverQuota, Screener Quality Termination

By utilizing these Redirect URLs, you can effectively manage the routing of respondents based on the outcome of their survey participation. This ensures that respondents are directed back to your platform accurately and that their experience is managed according to the specific requirements of the survey.

Embedding Profiling Data of Respondent In URL

Capture Profiling Information Through the Redirect URL

To streamline the survey process and avoid asking respondents the same questions, you can append profiling data directly to the Redirect URL. The data is passed in the format: &{QuestionKey}={AnswerOptionID}, ensuring that each respondent’s profile is recorded once and referenced for future interactions.

Example:

For key profiling information, such as age, gender, and personal income level, included in the Redirect URL:

https://www.example.com/screener?survey=z36mXYbQ&supplierId=2&pid=TESTPID&AGE=26&GENDER=1&Personal_Income_IN=5

Note: For the multiple-answer option, you can pass comma-separated AnswerOptionIDs, as shown below:

https://www.example.com/screener?survey=z36mXYbQ&supplierId=2&pid=TESTPID&AGE=26&GENDER=1&JOB_SEARCH=3,4,5

This allows your platform to efficiently capture and reuse the respondent’s profile data.

Secure Redirect URL Hashing

To enhance security and protect against fraud, we implement a process known as Redirect URL Hashing, also called URL signing. This method ensures that the integrity of the redirect URL is maintained and that it has not been tampered with during the redirection process.

How Redirects URL Hashing Works

Complete URL Construction → Hash Value Calculation → Hash Appending → URL Redirection

Complete URL Construction: We first construct the complete redirect URL.

Hash Value Calculation: We compute a hash value based on the complete URL using a shared secret key and a predetermined hashing algorithm.

Hash Appending: The generated hash value is then appended to the redirect URL.

URL Redirection: Finally, the respondent is redirected back to your platform with the secured URL.

Supported Hashing Algorithms

We currently support the following hashing algorithms:

MD5

SHA1

SHA256

SHA3-256

Explanation for Generating a Hash using MD5, SHA1 and SHA3-256

Prerequisites

Encryption Type: SHA1

Secret Key: A string that adds an extra layer of security (in this example, it will be your_secret_key).

Hashing Option: We will hash the entire URL concatenated with the secret key and include the hash as a parameter in the query string.

Steps for Hashing the URL

Example URL:

https://www.example.com/path?param1=value1&param2=value2

Concatenate the URL with the Secret Key:

'https://www.example.com/path?param1=value1&param2=value2' + 'your_secret_key'

Generate the Hash Value:

Use the SHA1 algorithm to generate a hash of the concatenated string.

Append the Hash Value to the URL:

The final URL will include the original URL along with the generated hash.

Example Code Implementation

Here’s how to implement this in JavaScript:

Example Output

Assuming the secret key is "your_secret_key" the output might look like:

https://www.example.com/path?param1=value1&param2=value2&hash=e39dfb40180bff81866c3f58a86aefb1c3bf3c4f

Note: This procedure is used for MD5, SHA1, and SHA3-256 Algorithms.

Explanation for Generating a Hash using SHA256

Prerequisites

Encryption Type: SHA256

Secret Key: A string that adds an extra layer of security (in this example, it will be your_secret_key).

Hashing Option: We are hashing the pathname and query string using HMAC-SHA256, with the secret key used in the hash generation.

Steps for Hashing the URL

Example URL

      https://www.example.com/path?param1=value1&param2=value2

Select the Part of the URL to Hash:

Extract the pathname and query string from the URL

The pathname might look like /path, and the query string could be ?param1=value1&param2=value2

     /path?param1=value1&param2=value2

Generate the SHA-256 Hash:

Use the HMAC (Hash-based Message Authentication Code) with the SHA-256 algorithm and the secret key to generate the hash.

This ensures that the hash is unique to the combination of the URL portion and the secret key.

Append the Hash Value to the URL:

The final URL will include the original URL along with the generated hash.

Example Code Implementation

Here’s how to implement this in JavaScript:

Example Output

Assuming the secret key is your_secret_key, the output might look like:

https://www.example.com/path?param1=value1&param2=value2&hash=ebd0f5f6f2d96391d850c62895ed73f6bfcfb8f0db82ef3939f249189473b20f

Transaction Statuses

Each respondent’s survey attempt is categorized with a status that indicates the outcome of their participation.

Status	Description	ID
Screener Dropouts	The respondent abandoned the survey midway while on our platform.	0
Client Completes	The respondent completed the client survey.	1
Client Fails	The survey attempt was terminated.	2
Client OverQuota	The respondent could not proceed because the quota was reached.	3
Client Quality Termination	The respondent’s attempt was terminated due to quality concerns.	4
Screener Terminates	Disqualification occurred during the pre-survey screening process.	5
Client Dropouts	The respondent abandoned the survey midway while in the client interface.	6
Screener OverQuota	The screening quota was exceeded, so the respondent could not participate.	7
Screener Quality Termination	The respondent was disqualified during screening due to quality issues.	8

Overview of the API Workflow

This guide outlines the steps involved in using the API to manage your survey pool, ensuring that surveys are correctly matched with qualified respondents and that participants are properly routed.

Get Survey Inventory

Use the "Get Available Surveys" endpoint to obtain a list of all currently available surveys.

Retrieve Survey Specifics

For each survey, access the "Get Available Surveys By Id" endpoint to retrieve its qualification requirements and quota details.

Match Respondent to the Right Survey

Based on the qualifications, your system will identify the most appropriate survey for each respondent.

Direct Respondent to Survey

Once matched, the respondent will be directed to the survey using the survey entry link (surveyLiveURL), with the respondent’s ID (PID) appended.

Survey Completion

The respondent will complete the survey as per the provided flow and instructions.

Return to Platform

Upon survey completion, the respondent will be redirected back to your platform through the specified redirect URL.

Guides

Global Definitions#

Qualifications#

Managing Survey Inventory#

Managing Survey Inventory: Step-by-Step Guide#

Step 1: Fetching the Survey Inventory#

Survey Availability#

Step 2: Survey Qualifications#

Step 3: Survey Quotas#

Survey Exclusions#

Respondent Journey: From Survey Entry to Completion#

Respondent Journey Overview#

Routing Respondents to Surveys (Survey Initiation)#

Routing Respondents to the Client Survey (In-Survey)#

Redirecting Respondents Back to Your Platform (Survey Completion)#

Redirect URLs: Directing Respondents Based on Survey Outcomes#

Embedding Profiling Data of Respondent In URL#

Supported Hashing Algorithms#

Transaction Statuses#

Overview of the API Workflow#