Global Definitions

This section outlines essential terms that define various survey components, including events, actions, and attributes such as countries, languages, and survey classifications.

Name	Description	Definition Key
Countries	A collection of country names paired with their respective two-letter codes.	country
Language	The list of languages available for surveys.	language
Categories	The categories that surveys belong to, help in classifying them.	categories
Survey Statuses	Statuses that indicate the state of a survey.	surveyStatus
Device Types	The types of devices on which surveys can be accessed or completed.	devicetype
Question type	Various formats of questions can be used in surveys.	questionType

Qualifications

Qualifications, also referred to as Questions and Answers, play a crucial role in integration. They are key to Survey Targeting and Respondent Management.

These Questions and Answers help ensure accurate targeting and quota management for surveys. Proper mapping of these values on your platform is essential; otherwise, respondents who don’t meet the survey qualifications may be terminated.

We provide multiple methods for retrieving questions and their corresponding answers, as outlined below.

Question Model

Example :

        {
            "questionKey": "STANDARD_CAR_USE",
            "questionId": 2825,
            "questionText": "Do you drive a car regularly?",
            "questionType": "Single Punch",
            "questionCategory": [
                "Automotive"
            ]
         }

Model Properties

Property	Description
questionId	Unique numerical identifier for the question.
questionText	The question presented to respondents.
questionKey	The primary identifier for the question, used across the platform.
questionType	The type of answer for the question..
language	The language in which the question is presented.
questionCategory	The category assigned to the question..

Answer Model

Example :

"questionOptions": [
                {
                    "OptionText": "Yes, I own a car/cars",
                    "id": 1,
                    "Order": 1
                },
                {
                    "OptionText": "Yes, I have access to a car/cars",
                    "id": 2,
                    "Order": 2
                },
                {
                    "OptionText": "Yes, I lease/have a company car",
                    "id": 3,
                    "Order": 3
                },
                {
                    "OptionText": "No, I don't have access to a car",
                    "id": 4,
                    "Order": 4
                }
            ]

Details of the model properties

Property	Description
id	A unique numerical identifier for the answer.
OptionText	The response option available for selection.
Order	The sequence in which answer choices are displayed (in ascending order).

Please note: Open-ended and numeric questions do not have predefined answer options, as respondents provide their own responses..

Managing Survey Inventory

This section explains how the inventory-based approach helps efficiently manage available survey data. It also outlines the steps required to integrate and effectively use survey information on the platform.

Core Concepts of Our Survey Workflow

1. Project Id

The Project ID serves as the "parent" entity for a survey. It is associated with multiple surveys within the system, allowing several surveys to be grouped under a single project.

2. Survey Attributes

The survey is the core unit on the platform, where essential details like pricing, sample size, and other parameters are defined. Key survey attributes include:

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

IR (Incidence Rate) - Estimated incidence rate for the survey..

N (Sample Size) - The number of respondents needed.

Country - The location where the survey is conducted.

Language - The language in which the survey is available.

3. Survey Qualifications (Targeting)

Surveys have specific qualifications that define who can participate. These criteria act as filters, ensuring that only eligible respondents are included.These qualifications are mandatory for all surveys.

4. Survey Quota

Quotas are used to control the number of respondents within specific survey segments. While not mandatory, quotas help regulate sample distribution and ensure that the survey reaches the desired demographic.

Survey Example

Scenario:
A popular streaming service wants to understand user preferences for new original content.

Survey Title: Streaming Service Content Preferences

Target Audience: Adults aged 18-55 who have used a streaming service in the past month.

Survey Details:

Sample Size (N): 500 respondents
Cost per Interview (CPI): $15
Length of Interview (LOI): 25 minutes
Estimated Incidence Rate (IR): 40%

Qualifications:

Age: 18-55 years old

Streaming Service Usage: Have used a streaming service (e.g., Netflix, Hulu, Disney+, etc.) to watch movies or TV shows in the past month.

Content Consumption: Watched at least one original series or film on a streaming service in the last 3 months.

Quotas:

Genre Preference (30%):

Science Fiction

Drama

Format Preference(70%):

Limited Series (1-2 seasons)

Ongoing Series (3+ seasons)

In this case, The goal is to collect responses from 500 qualified respondents, all of whom must meet the specified qualifications and fall within the designated quota limits.
If 150 Science Fiction fans (30% of 500) complete the survey, no more Science Fiction fans are accepted, even if the total sample size isn't reached. This ensures a balanced representation of preferences. The survey closes when all quotas are met, even if the full 500 haven't participated.

Step-by-Step Guide to Survey Inventory Management

This section explains the process of managing survey inventory, including retrieving available surveys, accessing qualification and quota details, and understanding how these elements interact.

Step 1: Retrieving the Survey Inventory

To get a list of currently available surveys, use the "Get Available Surveys" API endpoint. This endpoint provides real-time data on active surveys open for participation. Since surveys can be added or removed frequently, we recommend refreshing the inventory every five minutes to ensure up-to-date information.

If you need details about a specific survey, use the "Get Available Surveys By Id" endpoint.

Checking Active Surveys

When a survey appears in the "Get Available Surveys" response, it means the survey is currently active and open for participation. If a survey is no longer listed in the response, it may have been closed or temporarily paused. Given that survey statuses can change frequently, it’s important to configure your system to handle these updates automatically.

To monitor the status of paused or closed surveys, you can use the "Get Available Surveys By Id" endpoint for further details.

Step 2: Fetching Survey Qualifications

Survey qualifications define the criteria respondents must meet to participate in a survey. Once the survey inventory is retrieved, the next step is to obtain the qualification requirements for each survey. This can be done using the "Get Available Surveys By Id" API, which provides demographic and behavioral criteria for eligibility.

Step 3: Managing Survey Quotas

While qualifications determine who can take part in a survey, quotas control how many respondents from each group are needed. For example, a survey may require respondents aged 18-36, but quotas can specify that 10 respondents should be from the 18-25 age group and 15 from the 26-36 age group.

Example Quota Response

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

{
                "id": 6502,
                "quotaName": "Income",
                "title": "Income",
                "quotaN": 10,
                "hardStop": true,
                "clk": 0,
                "cmp": 0,
                "hardStopType": 0,
                "quotaStatus": "Open",
                "RemainingN": 10,
                "targeting": {
                    "Personal_Income_IN": [
                        {
                            "OptionId": 1,
                            "OptionText": "No Income/Less than Rs.1,00,000"
                        },
                        {
                            "OptionId": 2,
                            "OptionText": "Rs.1,00,001 to Rs.3,00,000"
                        },
                        {
                            "OptionId": 3,
                            "OptionText": "Rs.3,00,001 to Rs.5,00,000"
                        },
                        {
                            "OptionId": 4,
                            "OptionText": "Rs.5,00,001 to Rs.7,00,000"
                        }
                    ]
                }
 }

Quota Properties

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

Field	Value Type	Meaning
quotaN	Integer	Total number of required respondents for this quota.
RemainingN	Integer	Number of respondents still needed to meet the quota.
quotaStatus	“Open" / "Closed"	"Open" indicates that respondents are still eligible to participate, while "Closed" means no additional participants will be accepted.
hardStop	Boolean (true/false)	If true, respondents who qualify but exceed the limit will receive an "OverQuota" rejection in response. If false, extra respondents may still complete the survey.
hardStopType	Integer (0 or 1)	If 0, the quota is based on completions. If 1, it is based on survey starts.
targeting	{object}	Specifies the qualification criteria required for respondents within this quota.

Survey Exclusions

The excluded_surveys field in a survey specifies related surveys designed to prevent respondent duplication. This mechanism ensures that individuals who have previously participated in these associated surveys are not eligible for the current one, thereby maintaining data integrity.

Understanding Exclusions

Respondents with statuses listed in the excluded_status field for surveys identified in the excluded_surveys field should be excluded from the current survey. If such respondents attempt to participate, they will be automatically disqualified to prevent duplication.

Example of Survey Exclusion

{
  "surveyId": 3571129,
  "Language": "ENGLISH",
  "reContact": false,
  "surveyLiveURL": "https://www.example.com/screener?survey=z36mXYbQ&supplierId=2&pid=",
  "actualIR": 0,
  "actualLOI": 0,
  "excluded_surveys": [3792333, 3861802, 3571128],
  "excluded_status": [
    "Client Completes",
    "Client Fails",
    "Client OverQuota",
    "Client Quality Termination"
  ]
}

In this example, the excluded_surveys field lists surveys 3792333, 3861802 and 3571128. 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.

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 3571129. This exclusion ensures that the same respondent does not participate in linked surveys multiple times.

Respondent Workflow: From Survey Entry to Completion

This guide outlines the process of directing respondents through surveys, managing their participation, and ensuring a seamless return to your platform.

Overview of the Respondent Workflow

The respondent's Workflow typically follows this path:

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

The respondent's path includes:

Survey Initiation: The respondent starts on your platform and is directed to our system.

Participation Phase: The respondent engages with the survey hosted on our platform or a client questionnaire.

Completion Phase: After finishing the survey, the respondent returns to your platform via a specified redirect link.

Respondent Identification

Each respondent is assigned a unique Panelist ID (PID) to ensure consistent tracking across all surveys. If you need to pass a session identifier, include it as a trackId parameter in the query string; this value will be returned to your platform through the redirect URL.

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.

Directing Respondent to Surveys (Survey Initiation)

Every survey on our platform has a unique surveyLiveURL that connects participants from your platform to the appropriate survey. This URL is essential for accurate participant routing.

Example of a surveyLiveURL:

...
{
"surveyId": 5158,
"survayName": "Streaming Service Content Preferences",
"N": 10,
"CPI": 10,
"remainingN": 10,
"LOI": 10,
"IR": 10,
"Country": "India",
"Language": "ENGLISH",
"reContact": true,
"surveyLiveURL": "http://ogmr-api.ongraph.com:4000/screener?survey=GYOyWJPb&supplierId=124&pid=",
...
}
...

To direct respondents to specific surveys, use the surveyLiveURL provided for each survey. This URL contains essential parameters:

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

The initial page where respondents begin the survey.

Survey Identifier (survey)

A unique code identifying the survey.

Supplier Identifier (supplierId):

Tracks the source of the respondent.

Respondent ID (pid):

The unique identifier for each respondent.

Session ID (trackId):

An optional parameter for session tracking.

These parameters ensure accurate routing and tracking throughout the survey process.

Engaging with the Client Survey (Participation Phase)

Upon arrival at our platform, participants undergo pre-survey validations. Once validated, they proceed to the designated client survey or questionnaire. After completing the survey, participants are promptly redirected back to our platform for final processing and then returned to your platform via the specified Redirect URL.

Redirecting Respondent to Your Platform (Survey Completion)

Upon survey completion, respondents are redirected back to your platform using a predefined redirect URL. This URL facilitates the seamless return of respondents and the transfer of any necessary data.

By following this workflow, you can effectively manage respondents' survey experiences from start to finish.

Redirect URLs: Guiding Respondent Based on Survey Outcomes

Upon survey completion, participants are redirected to your platform using specific Redirect URLs corresponding to their survey outcomes. These URLs should be configured to capture necessary data and guide participants appropriately based on their results.

Categories of Redirect URLs:

Our platform offers various Redirect URLs based on survey outcomes:

Category	Description	Transaction Statuses
Successful Completion	For respondents who complete the survey.	Client Completes
Survey Termination	For respondents terminated mid-survey by the client.	Client Fails
Quota Exceeded	For respondents exceeding the survey's quota.	Client OverQuota
Quality	For respondents disqualified due to quality issues.	Client Quality Termination
Screener Exit	For respondents not meeting qualifications or facing screener issues.	Screener Dropouts, Screener Terminates, Screener OverQuota, Screener Quality Termination

By implementing these Redirect URLs, you can effectively manage respondent routing based on their survey participation outcomes, ensuring they are accurately directed back to your platform.

Sending Respondent Profiling Data into Survey URLs

To enhance the survey experience and avoid repetitive questions, you can send respondent profiling information directly into the survey URL. This is achieved by appending data in the format: &{QuestionKey}={AnswerOptionID}. This method ensures that each respondent's profile is captured once and utilized for future surveys.

Example:

Suppose you want to include key profiling details such as age, gender, and personal income level in the survey URL:

https://www.example.com/screener?survey=z36mXYbQ&supplierId=2&pid=Panelist_1&AGE=30&GENDER=2&STANDARD_URBAN_RURAL=2

Note: For questions allowing multiple answers, you can pass comma-separated AnswerOptionIDs as shown below:

https://www.example.com/screener?survey=z36mXYbQ&supplierId=2&pid=TESTPID&AGE=30&GENDER=2&AILMENTS_2_PAIN=5,6,7

This approach enables your platform to efficiently record and reuse respondent profile data, streamlining their participation in future surveys.

Secure Redirect URL Hashing

To enhance security and prevent tampering during the redirection process, we implement URL Hashing, also known as URL signing. This technique maintains the integrity of redirect URLs by appending a hash value, ensuring that the URL remains unaltered during redirection.

Redirects URL Hashing Works

Construct the Complete URL: Begin by forming the full redirect URL intended for the respondent.

Calculate the Hash Value: Generate a hash using a shared secret key and a chosen hashing algorithm (e.g., SHA1, SHA256). This hash is derived from the complete URL.

Append the Hash to the URL: TAttach the computed hash value to the redirect URL as a query parameter.

Redirect the Respondent: Direct the respondent to the secured URL with the appended hash.

Supported Hashing Algorithms

We currently support the following hashing algorithms:

MD5

SHA1

SHA256

SHA3-256

Generating a Hash Using MD5

Prerequisites

Encryption Type: MD5

Secret Key: A confidential string known only to your platform and ours (e.g., 'secret_key').

Hashing Method:The hash is generated by concatenating the complete URL with the secret key and applying the SHA1 algorithm.

Steps for Hashing the URL

Example URL:

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

Concatenate URL and Secret Key:

Merge the complete URL with the secret key.

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

Generate the MD5 Hash:

Apply the SHA1 algorithm to the concatenated string to produce the hash.

Append the Hash to the URL:

Add the generated hash as a query parameter to the original URL.

Example Implementation in JavaScript:

Example Output

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

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

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

Generating a Hash Using SHA256

Prerequisites

Encryption Type: SHA256

Secret Key: A confidential string known only to your platform and ours (e.g., 'secret_key').

Hashing Method: The hash is generated by applying HMAC-SHA256 to the URL's pathname and query string, using the secret key.

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 secret key to compute the HMAC-SHA256 hash of the extracted URL parts.

Append the Hash Value to the URL:

Add the generated hash as a query parameter to the original URL.

Example Implementation in JavaScript:

Example Output

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

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

By implementing URL Hashing, you can ensure that redirect URLs are protected against unauthorized modifications, thereby enhancing the security of the redirection process.

Transaction Statuses

Each respondent's survey engagement is assigned a specific status that reflects the result of their participation.

Status	Description	ID
Screener Dropouts	The respondent exited the survey during the initial screening phase on our platform.	0
Client Completes	The respondent successfully finished the client's survey.	1
Client Fails	The respondent's survey attempt was terminated by the client.	2
Client OverQuota	The respondent could not proceed because the quota was reached.	3
Client Quality Termination	The respondent was disqualified due to quality issues identified by the client.	4
Screener Terminates	The respondent didn't meet the criteria during screening.	5
Client Dropouts	The respondent left the survey partway through on the client's interface.	6
Screener OverQuota	The respondent couldn't participate because the screening phase exceeded its quota.	7
Screener Quality Termination	The respondent was disqualified during screening due to quality concerns.	8

API Workflow Overview

This guide walks you through the steps of using the API to manage your survey pool effectively. It ensures that surveys are matched with the right respondents and that participants are guided seamlessly through the process.

Access Survey Inventory

Start by using the "Get Available Surveys" endpoint to fetch a list of all surveys currently available.

Fetch Survey Details

For each survey, use the "Get Available Surveys By Id" endpoint to gather specific information, such as qualification criteria and quota details.

Match Respondents to Surveys

Based on the survey requirements, the system will determine the most suitable survey for each respondent.

Route Respondents to Surveys

Once a match is made, direct the respondent to the survey using the survey entry link (surveyLiveURL), with their unique respondent ID (PID) included.

Survey Participation

The respondent will complete the survey following the provided instructions and flow.

Redirect After Completion

After finishing the survey, the respondent will be redirected back to your platform using the specified redirect URL

Guides

Global Definitions#

Qualifications#

Managing Survey Inventory#

Step-by-Step Guide to Survey Inventory Management#

Step 1: Retrieving the Survey Inventory#

Checking Active Surveys#

Step 2: Fetching Survey Qualifications#

Step 3: Managing Survey Quotas#

Survey Exclusions#

Respondent Workflow: From Survey Entry to Completion#

Overview of the Respondent Workflow#

Directing Respondent to Surveys (Survey Initiation)#

Engaging with the Client Survey (Participation Phase)#

Redirecting Respondent to Your Platform (Survey Completion)#

Redirect URLs: Guiding Respondent Based on Survey Outcomes#

Sending Respondent Profiling Data into Survey URLs#

Supported Hashing Algorithms#

Transaction Statuses#

API Workflow Overview#