Global Definitions

This section defines the core concepts of a survey, covering events, actions, and key attributes like country, language, and survey classification for clear reference.

Name	Description	Definition Key
Countries	A list of country names with their associated two-letter ISO codes.	country
Language	The set of languages available for use in surveys.	language
Categories	Classification groups that organize surveys into categories.	categories
Survey Statuses	Indicators that represent the current state of a survey.	surveyStatus
Device Types	Types of devices through which surveys can be accessed or completed.	devicetype
Question Type	Different formats of questions that can be included in surveys.	questionType

Qualifications

Qualifications, also referred to as Questions and Answers, are a core part of the integration. They play a critical role in survey targeting and respondent management.

These question–answer pairs ensure accurate survey targeting and quota control, so it is important to correctly map values on your platform. If respondents fail to meet the defined qualifications, the survey will terminate.

Multiple methods are available to retrieve qualification questions and their respective answers, as outlined below.

Question Model

Here's an example :

    {
          "questionId": 2004,
          "questionText": "What is your gender?",
          "questionKey": "GENDER",
          "questionType": "Single Punch",
          "language": "ENGLISH",
          "questionCategory": [
            "Demographic"
          ]
    }

Details of the Model Properties

Property	Description
questionId	Numeric identifier assigned to the question.
questionText	The text of the prompt shown to respondents.
questionKey	Primary identifier used to reference the question across the platform.
questionType	The format or type of response expected for the question.
language	Language in which the question is defined.
questionCategory	Categories that classify the question (e.g., Demographic, Behavioral).

Answer Model

Here's an example :

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

Details of the model properties

Property	Description
id	Numeric identifier assigned to the answer option.
optionText	The answer text available for selection by the respondent.
order	Position of the answer option in the list, displayed in ascending order.

Managing Survey Inventory

Here, we describe the inventory-based method for managing survey data and the process required to integrate and apply this information effectively within the platform.

Key Elements of Survey Workflow

1. Project Id

The Project ID serves as the top-level entity in the survey workflow. It acts as a container that can hold multiple surveys, making it easier to manage related surveys under a single umbrella project.

2. Survey Attributes

The survey itself is the central unit of the platform, where all key details are defined. Attributes describe the survey’s structure and requirements, including pricing, sample size, and other critical specifications. Important survey attributes include:

LOI (Length of Interview) - Estimated time required for respondents to complete the survey.

IR (Incidence Rate) - The percentage of respondents expected to qualify for the survey.

N (Sample Size) - The total number of respondents required.

Country - The geographic location where the survey will be conducted.

Language - The language in which the survey is delivered.

3. Survey Qualifications (Targeting)

Qualifications, also referred to as targeting criteria, define which respondents are eligible to participate in a survey. These rules act as filters, ensuring that only participants who meet the specified requirements (such as demographics or behavior) are included. Targeting is mandatory for every survey to guarantee data quality and relevance.

4. Survey Quota

Quotas allow survey administrators to control the number of respondents within particular categories or segments, such as age, gender, or location. While quotas are optional, when applied, they help balance the sample distribution and ensure the survey captures responses from the intended audience segments.

Survey Example Walkthrough
To illustrate how surveys, qualifications, and quotas operate together, consider the following example:

Scenario:
A fitness equipment brand wants to understand consumer preferences for purchasing home workout gear.

Survey Title: Home Fitness Equipment Preferences

Target Audience: Adults aged 20–50 who exercise at least twice a week at home.

Number of Respondents (N): 400 respondents
Cost per Interview (CPI): $18
Length of Interview (LOI): 20 minutes
Incidence Rate (IR): 45%

Qualifications:

20–50 years old

Fitness Activity: Exercise at home at least twice per week.

Equipment Ownership: Own or have purchased at least one piece of fitness equipment (e.g., treadmill, dumbbells, resistance bands) in the past 12 months.

Quotas:

Workout Preference (40%)::

Cardio-focused (e.g., treadmill, stationary bike)

Strength-focused (e.g., weights, resistance training)

Purchase Intent (60%):

Planning to buy new equipment in the next 6 months

Not planning to buy but interested in upgrades

The goal is to collect responses from 400 qualified respondents who meet the specified criteria and align with quota distribution. For instance, once 160 cardio-focused participants (40% of 400) have completed the survey, no additional cardio-focused responses are accepted.
This ensures proportional representation across workout types and purchasing intent. The survey closes when quotas are filled, regardless of whether the full sample size is reached.

Practical Guide to Handling Survey Inventory

This section explains the process of managing survey inventory, including how to fetch active surveys, retrieve qualification and quota details, and understand how these components interact.

Step 1: Fetching the Survey Inventory

Use the Get Available Surveys API endpoint to retrieve a list of all currently active surveys. The inventory updates in real time—new surveys are added as they launch, while paused or closed surveys are removed. For accuracy, it is recommended to refresh the inventory every 5 minutes.

To obtain details for a specific survey, use the Get Available Surveys By Id endpoint.

Survey Availability

If a survey appears in the Get Available Surveys response, it is currently live and available. If it no longer appears, the survey may have ended or been paused. Because survey statuses can change frequently, systems should be designed to handle such updates dynamically.

For tracking surveys that are paused or closed, the Get Available Surveys By Id endpoint provides more detailed status information.

Step 2: Survey Qualifications

Survey qualifications define the eligibility requirements for participation. After retrieving the survey inventory, use the Get Available Surveys By Id API to fetch qualifications. This data specifies the demographic or behavioral attributes needed for a respondent to qualify.

Step 3: Survey Quotas

While qualifications determine who is eligible for a survey, quotas control how many respondents are required from each subgroup.

Quota Response Example

A qualification might specify respondents aged 18–36.

A quota can refine this by requiring 10 respondents from the 18–25 group and 15 respondents from the 26–36 group.

        {
          "id": 57,
          "quotaName": "ELECTRONICS",
          "title": "ELECTRONICS_PURCHASE",
          "quotaN": 3,
          "hardStop": true,
          "clk": 12,
          "cmp": 5,
          "hardStopType": 1,
          "quotaStatus": "Open",
          "RemainingN": 2,
          "targeting": {
            "POPULAR_ELECTRONICS_STORES_US": [
              {
                "OptionId": 10,
                "OptionText": "Best Buy"
              },
              {
                "OptionId": 11,
                "OptionText": "Walmart"
              },
              {
                "OptionId": 12,
                "OptionText": "Target"
              },
              {
                "OptionId": 13,
                "OptionText": "Apple Store"
              }
            ]
          }
        }

Understanding Quota Properties

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

Field	Type	Description
quotaN	Integer	The target number of completions required to fill this quota.
RemainingN	Integer	The number of completions still outstanding before the quota is met.
quotaStatus	`"Open"` / `"Closed"`	Indicates whether the quota is still accepting respondents (`Open`) or no longer available (`Closed`).
hardStop	Boolean (`true` / `false`)	Defines whether the quota enforces a strict cutoff. If `true`, qualified respondents are rejected once the limit is reached; if `false`, additional respondents may still be allowed.
hardStopType	Integer (`0` or `1`)	Determines how the hard stop is measured: `0` = based on completions, `1` = based on survey starts.
targeting	Object	Contains the specific qualification rules applied to this quota segment.

Survey Exclusions

The excluded_surveys field identifies surveys that are restricted to prevent respondent duplication. This mechanism ensures that individuals who have already taken part in related surveys are not eligible for the current one, thereby protecting data quality.

How to Interpret Exclusions

If a respondent has participated in any survey listed under excluded_surveys and their outcome matches a status defined in the excluded_status field, they are disqualified from entering the current survey. This automated check ensures respondents cannot appear multiple times across linked surveys.

Example of Survey Exclusion

{
  "surveyId": 4820194,
  "language": "ENGLISH",
  "reContact": false,
  "surveyLiveURL": "https://www.example.com/screener?survey=gh73KsQ9&supplierId=7&pid=",
  "actualIR": 0,
  "actualLOI": 0,
  "excluded_surveys": [4721188, 4795501, 4820193],
  "excluded_status": [
    "Client Completes",
    "Client Fails",
    "Client OverQuota",
    "Client Quality Termination"
  ]
}

In this example, surveys 4721188, 4795501, and 4820193 are flagged in the excluded_surveys list. Any respondent who previously participated in one of these surveys and received a status of "Client Completes", "Client Fails", "Client OverQuota", or "Client Quality Termination" will be automatically disqualified from survey 4820194.

Survey Exclusion Clarifications

This exclusion logic ensures that respondents cannot qualify for multiple related surveys, maintaining the integrity and uniqueness of collected data.

Respondent Path: From First Click to Final Redirect

The respondent journey describes the complete flow a participant follows, beginning when they enter from the supplier platform and ending when they are redirected back after the survey is finished. This process ensures respondents are properly routed, tracked, and identified at every stage.

Overview of the Respondent Flow

The typical journey of a respondent can be represented as:

Supplier Platform → Our Platform → Client Survey → Our Platform → Supplier Platform

This flow is divided into three distinct stages:

Survey Entry Phase: The respondent starts on your platform (the Supplier) and is redirected to our platform, where eligibility checks or routing logic may be applied.

Survey Participation Phase: The respondent engages with the survey, which may be hosted either on our platform or directly within a client’s questionnaire system.

Survey Completion Phase: Once the survey is finished (or terminated early), the respondent is redirected back to our platform. From there, they are returned to the Supplier platform with the appropriate status code or outcome.

Identifying Respondents

Each respondent is tracked using a unique Panelist ID (PID), which persists across multiple sessions and surveys. This ensures respondents can be consistently recognized regardless of when or how often they participate.

For example: A user with PID 78421 enters a health & wellness survey today.

If the same user is routed to a consumer electronics survey a month later, the PID remains unchanged (78421), allowing consistent tracking across both surveys

Passing Session Identifiers
If you need to track sessions beyond the persistent PID, you can use an optional session parameter called trackId.

The trackId is appended as a query string when directing the respondent to our platform.

Upon survey completion or termination, the same trackId value is returned to your platform through the Redirect URL, allowing you to reconcile sessions at a more granular level.

Example Redirect URL with trackId:
https://supplier-platform.com/complete?pid=78421&trackId=session_2025_01

In this example:

pid=78421 identifies the respondent.

trackId=session_2025_01 provides an additional session-level identifier, which can be used for internal analytics, troubleshooting, or fraud detection.

Initiating a Survey: Routing Respondents

To begin a survey, respondents are directed from your platform to ours using a unique surveyLiveURL. This URL is essential for ensuring each respondent is sent to the correct survey.

Here is an example of what a surveyLiveURL might look like when you call the "Get Available Surveys" API endpoint:

Example Response

...
{
"surveyId": 12345,
"surveyName": "Consumer Habits Study - US",
"Status": "Live",
"Country": "United States",
"Language": "ENGLISH",
"N": 500,
"remainingN": 450,
"CPI": 2.50,
"LOI": 15,
"IR": 20,
"reContact": false,
"surveyLiveURL": "https://www.our-platform.com/live/survey-entry?surveyId=a1b2c3d4&supplierId=YOUR_SUPPLIER_ID&pid="
...
}
...

Breaking Down the Survey Link

Each part of the surveyLiveURL serves a specific purpose in ensuring the participant is routed correctly:

Base Path (Landing Page):
https://www.example.com/screener? → The entry point where respondents first arrive before beginning the survey.

Survey Identifier (survey):
A secure, encoded string that maps the participant to the correct survey.

Supplier Identifier (supplierId):
Used to record the origin of traffic and attribute respondents back to your platform.

Panelist Identifier (pid):
A unique ID you assign to each respondent. This value must remain consistent across all surveys for tracking continuity.

Optional Session Tracking (trackId):
If you want to track session-specific data, you can append a trackId parameter to the link. This value will be returned in the Redirect URL after the survey ends.

Together, these parameters guarantee that respondents are seamlessly directed, properly identified, and tracked throughout the survey lifecycle.

Survey Participation Phase (In-Survey)

After arriving on our platform, respondents first go through a series of pre-survey validations. These checks confirm eligibility, prevent duplication, and ensure data quality before the participant can proceed further.

Once validations are complete, respondents are seamlessly redirected to the designated Client Survey or Questionnaire. Here, they provide their responses as per the survey requirements.

At the end of the survey session, respondents are automatically returned to our platform for final processing. This step ensures their status (complete, terminate, overquota, etc.) is properly recorded. Immediately after, they are redirected back to your platform using the predefined redirect URL, closing the loop of the respondent journey.

Survey Completion & Redirect Phase

At the conclusion of the client survey, respondents are directed back to our platform for final status recording. This step ensures their outcome—whether completed, terminated, or overquota—is accurately logged.

Following this processing, respondents are seamlessly redirected to your platform through the predefined Redirect URL you provide. This link is crucial for ensuring respondents return to the correct location, along with any required tracking information or identifiers passed through the URL.

By using the Redirect URL, the respondent’s journey is completed smoothly while maintaining consistency and data integrity between both platforms.

Managing Redirects Based on Survey Outcomes

When a respondent completes or exits a survey, they need to be routed back to your platform. This is handled through Redirect URLs, which map each type of survey outcome to the appropriate return page on your system.

These Redirect URLs not only bring participants back but also allow your platform to capture any required data and determine the next steps based on the outcome of the survey session.

Types of Redirect URLs

To ensure accurate handling of all possible outcomes, our platform supports different categories of Redirect URLs. Each one corresponds to a specific transaction status:

Redirect Type	When It’s Triggered	Transaction Status
Completion	The respondent successfully completes the survey.	Client Completes
Termination	The respondent is screened out or terminated during the survey by the client.	Client Fails
Over Quota	The respondent qualifies but the quota for their group is already full.	Client OverQuota
Quality Termination	The respondent is flagged and removed due to poor quality responses.	Client Quality Termination
Screener Exit	The respondent does not meet initial screener criteria or exits during qualification.	Screener Dropouts, Screener Terminates, Screener OverQuota, Screener Quality Termination

By configuring these Redirect URLs, you can ensure that every respondent is routed appropriately after their survey attempt, keeping the flow seamless while maintaining accurate tracking of participation outcomes.

Passing Profiling Data Through Redirect URLs

To reduce redundancy and avoid asking respondents the same demographic or background questions repeatedly, profiling data can be appended directly to the Redirect URL. This ensures that key respondent details are automatically captured and reused for future surveys.

How Profiling Data is Added
Data is passed in the following format: &{QuestionKey}={AnswerOptionID}. Each parameter represents a specific profiling question and its corresponding selected answer.

Example:
Appending details such as age, gender, and income level:

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

Multiple-Answer Example:
For questions that allow multiple responses, values can be added as comma-separated IDs:

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

This approach streamlines the respondent experience while ensuring that your platform maintains consistent profiling records.

Securing Redirect URLs with Hashing

To safeguard redirect links from manipulation or fraud, we use Redirect URL Hashing (also known as URL signing). This process validates the integrity of the URL before respondents are redirected.

Steps in URL Hashing:

URL Assembly: Construct the full redirect URL with all required parameters.

Hash Generation: Create a hash value using a secret key and a secure hashing algorithm(e.g., SHA1, SHA256).

Hash Attachment: Append the generated hash value as an additional parameter to the URL.

Validation at Redirect: When the respondent is redirected, the hash is verified to confirm the URL has not been tampered with.

This ensures a secure, tamper-proof redirect process that maintains both data quality and respondent trust.

Supported Hashing Algorithms

Our platform supports multiple hashing algorithms to secure Redirect URLs and prevent tampering:

MD5

SHA1

SHA256

SHA3-256

How to Generate a Hash (Example with SHA1)

Below is a step-by-step guide for generating a hash using the SHA1 algorithm (similar logic applies to MD5, SHA256, and SHA3-256).

Prerequisites

Hashing Algorithm: SHA1

Secret Key: A private string known only to you and our system (e.g., your_secret_key).

Hashing Approach: Combine the entire URL with the secret key, then generate a hash.

Steps for Creating a Secure URL

Original URL Example:

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

Concatenate with Secret Key:

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

Generate the Hash Value:

Apply the SHA1 hashing algorithm to the concatenated string.

Example output:

5baa61e4c9b93f3f0682250b6cf8331b7ee68fd8

Append Hash to URL:

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

Result

The final Redirect URL now includes a cryptographic hash, ensuring that:

The URL has not been altered during transmission.

Only requests with a valid hash (generated using the shared secret) will be accepted.

Example Code Walkthrough (SHA1)

Below is a simple JavaScript example showing how to generate a secure hash by combining a URL with a secret key.

Sample Output

With the secret key set to your_secret_key, the resulting URL could look like:

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

This same process applies to MD5, SHA1, and SHA3-256 hashing algorithms.

Generating a Hash Using SHA256

When using SHA256, we recommend applying an HMAC (Hash-based Message Authentication Code) with the secret key to improve security. Instead of hashing the entire URL, we only hash the pathname and query string.

Steps

Identify the portion of the URL to hash (pathname + query string).
Example:

/path?param1=value1&param2=value2

Use the secret key with HMAC-SHA256 to generate a hash.

Attach the resulting hash to the original URL.

JavaScript Example

Sample Output

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

Transaction Statuses

Every survey attempt by a respondent is assigned a transaction status. This status helps identify how the respondent’s participation concluded and enables accurate tracking of outcomes.

Status	Description	ID
Screener Dropouts	The respondent exited before completing the screener on our platform.	0
Client Completes	The respondent successfully finished the client’s survey.	1
Client Fails	The respondent was terminated from the survey by the client.	2
Client OverQuota	The respondent could not continue because the survey’s quota was already filled.	3
Client Quality Termination	The respondent was removed due to failing quality checks.	4
Screener Terminates	The respondent was disqualified during the pre-survey screener.	5
Client Dropouts	The respondent abandoned the survey partway through the client’s interface.	6
Screener OverQuota	The screening process quota was exceeded, preventing further participation.	7
Screener Quality Termination	The respondent was disqualified during screening for quality-related reasons.	8

Overview - API Workflow

This section provides a structured overview of how the API operates to manage surveys, from listing available surveys to returning respondents to your platform. The goal is to ensure respondents are efficiently matched with the right surveys and routed through the process seamlessly.

Fetch Survey Inventory

Call the Get Available Surveys endpoint to retrieve a list of all currently active surveys.

Access Survey Details

For a specific survey, use the Get Available Surveys By Id endpoint to review its qualification rules and quota settings.

Match Respondents

Using the provided qualifications, your system determines which survey best fits each respondent.

Route Respondents

Once matched, direct the respondent to the survey via the provided entry link (surveyLiveURL) with their unique identifier (PID) appended.

Survey Participation

Respondents complete the survey following the defined structure and flow.

Redirect Back to Platform

After completion, respondents are redirected back to your platform using the configured redirect URL.

Guides

Global Definitions#

Qualifications#

Managing Survey Inventory#

Practical Guide to Handling Survey Inventory#

Step 1: Fetching the Survey Inventory#

Survey Availability#

Step 2: Survey Qualifications#

Step 3: Survey Quotas#

Survey Exclusions#

Respondent Path: From First Click to Final Redirect#

Overview of the Respondent Flow#

Initiating a Survey: Routing Respondents#

Example Response#

Breaking Down the Survey Link#

Survey Participation Phase (In-Survey)#

Survey Completion & Redirect Phase#

Managing Redirects Based on Survey Outcomes#

Types of Redirect URLs#

Passing Profiling Data Through Redirect URLs#

Securing Redirect URLs with Hashing#

Supported Hashing Algorithms#

How to Generate a Hash (Example with SHA1)#

Prerequisites#

Steps for Creating a Secure URL#

Result#

Transaction Statuses#

Overview - API Workflow#