R4I Supply API — Reference

R4I Supplier APIs provide a simple and quick way to pull down survey inventory available to supplier and match with user's profile.

With this API, suppliers can get updated list of survey inventory, real time statistics for each survey and targeting questions to match with user's profile.

Authentication

Every request must include partner secret key in header

Header:

Authorization: Bearer R4I_TEST_xxxxxxxxxxxxxxxx

All endpoints below use POST method. Request and response bodies are JSON. The documented parameters are required/optional as indicated.

Base URLs

Use the appropriate base URL for your environment

SANDBOX https://api.research4insights.com/sandbox/v1/
PRODUCTION https://api.research4insights.com/production/v1/

Allocated Surveys

List active projects (surveys) assigned to the partner with counts and detailed metadata.

POST
POST /allocated_survey

Headers

Header Value Required
Authorization Bearer R4I_TEST_xxxxxxxxxxxxxx Required
Content-Type application/json Required

Parameters

Field Type Required Description
page integer Optional Pagination page (default 1)
per_page integer Optional survey per page (default 10)

Code Samples

curl --location 'api.research4insights.com/sandbox/v1/allocated_survey' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer R4I_TEST_xxxxxxxxxxxxxx' \
--data '{
  "page": 1,
  "per_page": 10
}'
<?php
$ch = curl_init("https://api.research4insights.com/sandbox/v1/allocated_survey");
curl_setopt_array($ch, [
  CURLOPT_POST => true,
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer R4I_TEST_xxxxxxxxxxxxxx",
    "Content-Type: application/json"
  ],
  CURLOPT_POSTFIELDS => json_encode([
    "page" => 1,
    "per_page" => 10
  ])
]);
$response = curl_exec($ch);
curl_close($ch);
echo $response;
?>
const fetch = require('node-fetch');

(async () => {
  const response = await fetch('https://api.research4insights.com/sandbox/v1/allocated_survey', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer R4I_TEST_xxxxxxxxxxxxxx',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      page: 1,
      per_page: 10
    })
  });
  
  const data = await response.json();
  console.log(data);
})();
{
  "status": "success",
  "message": "Request processed successfully",
  "data": {
    "success": true,
    "TotalCount": 30,
    "data": [
      {
        "survey_id": "PROJ-94AECB65",
        "name": "Healthcare Consumer Study 1",
        "industry": "Healthcare",
        "segment": "B2B",
        "CPI": {
          "value": 6,
          "currency": "USD"
        },
        "survey_limit": {
          "Australia": 163,
          "Canada": 338,
          "USA": 132
        },
        "IR": 40,
        "LOI": 26,
        "PII": "No",
        "status": "Active",
        
        "country": ["Australia", "Canada", "USA"],
        "description": "This survey targets participants in the healthcare industry to collect insights on market behavior."
      },
      {
        "survey_id": "PROJ-309A3048",
        "name": "Travel Consumer Study 2",
        "industry": "Travel",
        "segment": "B2B",
        "CPI": {
          "value": 3,
          "currency": "USD"
        },
        "survey_limit": {
          "India": 472,
          "UK": 405
        },
        "IR": 40,
        "LOI": 25,
        "PII": "Yes",
        "status": "Active",
        
        "country": ["India", "UK"],
        "description": "This survey targets participants in the travel industry to collect insights on market behavior."
      },
      {
        "survey_id": "PROJ-CC744B47",
        "name": "Automotive Consumer Study 3",
        "industry": "Automotive",
        "segment": "B2C",
        "CPI": {
          "value": 4,
          "currency": "USD"
        },
        "survey_limit": {
          "USA": 407,
          "UK": 274,
          "Australia": 76
        },
        "IR": 11,
        "LOI": 15,
        "PII": "Yes",
        "status": "Active",
        
        "country": ["USA", "UK", "Australia"],
        "description": "This survey targets participants in the automotive industry to collect insights on market behavior."
      },
      {
        "survey_id": "PROJ-892024AB",
        "name": "Real Estate Consumer Study 4",
        "industry": "Real Estate",
        "segment": "B2C",
        "CPI": {
          "value": 2,
          "currency": "USD"
        },
        "survey_limit": {
          "USA": 113,
          "Australia": 231
        },
        "IR": 61,
        "LOI": 19,
        "PII": "No",
        "status": "Active",
        
        "country": ["USA", "Australia"],
        "description": "This survey targets participants in the real estate industry to collect insights on market behavior."
      },
      {
        "survey_id": "PROJ-A07F612B",
        "name": "Energy Consumer Study 5",
        "industry": "Energy",
        "segment": "B2C",
        "CPI": {
          "value": 3,
          "currency": "USD"
        },
        "survey_limit": {
          "UK": 206,
          "USA": 306
        },
        "IR": 33,
        "LOI": 25,
        "PII": "No",
        "status": "Active",
        
        "country": ["UK", "USA"],
        "description": "This survey targets participants in the energy industry to collect insights on market behavior."
      }
    ]
  }
}

Get Survey By ID

Retrieve detailed information for a specific survey using its unique survey ID.

POST
POST /get_survey_by_id

Headers

Header Value Required
Authorization Bearer R4I_TEST_xxxxxxxxxxxxxx Required
Content-Type application/json Required

Parameters

Field Type Required Description
survey_id string Required Unique survey identifier (e.g., R4I-32AB91CD)

Code Samples

curl --location 'https://api.research4insights.com/sandbox/v1/get_survey_by_id' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer R4I_TEST_xxxxxxxxxxxxxx' \
--data '{
  "survey_id": "R4I-32AB91CD"
}'
<?php
$ch = curl_init("https://api.research4insights.com/sandbox/v1/get_survey_by_id");
curl_setopt_array($ch, [
  CURLOPT_POST => true,
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer R4I_TEST_xxxxxxxxxxxxxx",
    "Content-Type: application/json"
  ],
  CURLOPT_POSTFIELDS => json_encode([
    "survey_id" => "R4I-32AB91CD"
  ])
]);
$response = curl_exec($ch);
curl_close($ch);
echo $response;
?>
const fetch = require('node-fetch');

(async () => {
  const response = await fetch('https://api.research4insights.com/sandbox/v1/get_survey_by_id', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer R4I_TEST_xxxxxxxxxxxxxx',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      survey_id: "R4I-32AB91CD"
    })
  });
  
  const data = await response.json();
  console.log(data);
})();
{
  "status": "success",
  "message": "Request processed successfully",
  "data": {
    "success": true,
    "TotalCount": 1,
    "data": [
      {
        "survey_id": "R4I-32AB91CD",
        "name": "Healthcare Consumer Study",
        "industry": "Healthcare",
        "segment": "B2C",
        "CPI": {
          "value": 6,
          "currency": "USD"
        },
        "survey_limit": {
          "Australia": 456,
          "UK": 279,
          "India": 333
        },
        "IR": 27,
        "LOI": 24,
        "PII": "No",
        "status": "Active",
        "target_audience": [
                    {
                        "QuestionId": 1,
                        "QuestionKey": "AGE_RANGE",
                        "QuestionText": "What is your age range?",
                        "QuestionType": "Numeric Range",
                        "QuestionCategory": "Demographic",
                        "Options": [
                            {
                                "OptionId": 1,
                                "OptionText": "23 - 35"
                            }
                        ]
                    },
                    {
                        "QuestionId": 2,
                        "QuestionKey": "DEVICE_TYPE",
                        "QuestionText": "Which device(s) do you use most frequently?",
                        "QuestionType": "Multiple Choice",
                        "QuestionCategory": "Technology",
                        "Options": [
                            {
                                "OptionId": 1,
                                "OptionText": "Mobile"
                            },
                            {
                                "OptionId": 2,
                                "OptionText": "Desktop"
                            },
                            {
                                "OptionId": 3,
                                "OptionText": "Tablet"
                            }
                        ]
                    },
                    {
                        "QuestionId": 3,
                        "QuestionKey": "ETHNICITY",
                        "QuestionText": "What is your ethnicity?",
                        "QuestionType": "Single Choice",
                        "QuestionCategory": "Demographic",
                        "Options": [
                            {
                                "OptionId": 1,
                                "OptionText": "Asian"
                            },
                            {
                                "OptionId": 2,
                                "OptionText": "White"
                            }
                        ]
                    },
                    {
                        "QuestionId": 4,
                        "QuestionKey": "GENDER",
                        "QuestionText": "What is your gender?",
                        "QuestionType": "Single Choice",
                        "QuestionCategory": "Demographic",
                        "Options": [
                            {
                                "OptionId": 1,
                                "OptionText": "Male"
                            }
                        ]
                    },
                    {
                        "QuestionId": 5,
                        "QuestionKey": "ZIPCODES",
                        "QuestionText": "What is your zipcode?",
                        "QuestionType": "Numeric Open Ended",
                        "QuestionCategory": "Geographic",
                        "Options": [
                            {
                                "OptionId": 1,
                                "OptionText": "777171"
                            }
                        ]
                    }
                ],
        "country": ["Australia", "UK", "India"],
        "description": "This survey targets participants in the healthcare industry to collect insights on market behavior."
      }
    ]
  }
}

Get Survey By Date

Retrieve all surveys created or active on a specific date.

POST
POST /survey_by_date

Headers

Header Value Required
Authorization Bearer R4I_TEST_xxxxxxxxxxxxxx Required
Content-Type application/json Required

Parameters

Field Type Required Description
date string Required Date in YYYY-MM-DD format (e.g., 2023-08-12)

Code Samples

curl --location 'https://api.research4insights.com/sandbox/v1/survey_by_date' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer R4I_TEST_xxxxxxxxxxxxxx' \
--data '{
  "date": "2025-10-23"
}'
<?php
$ch = curl_init("https://api.research4insights.com/sandbox/v1/survey_by_date");
curl_setopt_array($ch, [
  CURLOPT_POST => true,
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer R4I_TEST_xxxxxxxxxxxxxx",
    "Content-Type: application/json"
  ],
  CURLOPT_POSTFIELDS => json_encode([
    "date" => "2025-10-23"
  ])
]);
$response = curl_exec($ch);
curl_close($ch);
echo $response;
?>
const fetch = require('node-fetch');

(async () => {
  const response = await fetch('https://api.research4insights.com/sandbox/v1/survey_by_date', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer R4I_TEST_xxxxxxxxxxxxxx',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      date: "2025-10-23"
    })
  });
  
  const data = await response.json();
  console.log(data);
})();
{
  "status": "success",
  "message": "Request processed successfully",
  "data": {
    "success": true,
    "total": 2,
    "data": [
      {
        "survey_id": "PROJ-A87CE45F",
        "name": "Retail Study 3",
        "CPI": "USD 6",
        "survey_limit": {
          "India": 372,
          "USA": 356
        },
        "industry": "Retail",
        "segment": "B2B",
        "IR": 22,
        "LOI": 19,
        "PII": "No",
        "status": "Active",
       
        "country": "Germany",
        "date": "2025-10-23",
        "description": "Survey about retail consumers conducted on 2025-10-23"
      },
      {
        "survey_id": "PROJ-881DB947",
        "name": "Education Study 4",
        "CPI": "USD 5",
        "survey_limit": {
          "India": 456,
          "USA": 265
        },
        "industry": "Education",
        "segment": "B2C",
        "IR": 40,
        "LOI": 11,
        "PII": "Yes",
        "status": "Active",
        
        "country": "Germany",
        "date": "2025-10-23",
        "description": "Survey about education consumers conducted on 2025-10-23"
      }
    ]
  }
}
Usage Notes
  • Returns all surveys that were active or created on the specified date
  • Date format must be YYYY-MM-DD
  • Response includes both survey metadata and targeting information
  • Useful for daily reporting and monitoring new survey launches

Get Industries

Retrieve the complete list of available industry categories for survey classification.

POST
POST /get_industries

Headers

Header Value Required
Authorization Bearer R4I_TEST_xxxxxxxxxxxxxx Required
Content-Type application/json Required

Parameters

This endpoint does not require any request body parameters.

Code Samples

curl --location --request POST 'https://api.research4insights.com/sandbox/v1/get_industries' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer R4I_TEST_xxxxxxxxxxxxxx'
<?php
$ch = curl_init("https://api.research4insights.com/sandbox/v1/get_industries");
curl_setopt_array($ch, [
  CURLOPT_POST => true,
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer R4I_TEST_xxxxxxxxxxxxxx",
    "Content-Type: application/json"
  ]
]);
$response = curl_exec($ch);
curl_close($ch);
echo $response;
?>
const fetch = require('node-fetch');

(async () => {
  const response = await fetch('https://api.research4insights.com/sandbox/v1/get_industries', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer R4I_TEST_xxxxxxxxxxxxxx',
      'Content-Type': 'application/json'
    }
  });
  
  const data = await response.json();
  console.log(data);
})();
{
  "status": "success",
  "message": "Request processed successfully",
  "data": {
    "success": true,
    "total": 10,
    "data": [
      {
        "id": 1,
        "name": "Healthcare"
      },
      {
        "id": 2,
        "name": "Finance"
      },
      {
        "id": 3,
        "name": "Technology"
      },
      {
        "id": 4,
        "name": "Retail"
      },
      {
        "id": 5,
        "name": "Education"
      }
    ]
  }
}
Usage Notes
  • This endpoint returns a list of available industry categories
  • The list is consistent across all API environments
  • Use these industry IDs when creating new surveys or filtering existing ones
  • Industry names are standardized for consistent categorization

Common Use Cases

Survey Filtering

Use industry IDs to filter allocated surveys by specific industry categories.

Reporting & Analytics

Categorize survey performance and statistics by industry type.

Get Redirects

Retrieve configured redirect URLs which you shared with us

POST
POST /get_redirects

Parameters

Field Type Required Description
supplier_id string Required Supplier identifier
email string Required Contact email of the supplier[Email id which shared with Research4insights for api requrest]

Code Samples

curl --location 'http://api.research4insights.com/sandbox/v1/get_redirects' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer R4I_TEST_xxxxxxxxxxxxxx' \
--data '{
  "supplier_id": "R4I-S-2543-ABV38",
  "email": "test@partner.com"
}'
{
  "status": "success",
  "message": "Request processed successfully",
  "data": {
    "redirects": {
      "success": "https://partner.com/survey/index?status=C&uid={uid}&hmac={hmac}",
      "terminate": "https://partner.com/survey/index?&status=T&uid={uid}&hmac={hmac}",
      "quotafull": "https://partner.com/survey/index?&status=Q&uid={uid}&hmac={hmac}",
      "security_check": "https://partner.com/survey/index?&status=S&uid={uid}&hmac={hmac}"
    }
  }
}

Add Participant

Register a new participant in the R4I system with detailed demographic information.

POST
POST /add_participant

Headers

Header Value Required
Authorization Bearer R4I_TEST_xxxxxxxxxxxxxx Required
Content-Type application/json Required

Parameters

Field Type Required Description
pid string Opional Unique participant identifier [Autogenerated & Predefined both allowed]For predefined: YourBrandShortName-uniqueNumber, Ex: R4I-24939,R4I-dfjkejd,ABJ-h3h4k,TYC-h4g3k2
supplier_id string Required Supplier identifier
participant_name string Optional Full name of the participant
email string Optional Email address
phone string Optional Phone number
age number Optional Age of participant
country string Optional Country of residence
zipcode string Optional Postal/ZIP code
gender string Optional Gender (Male, Female, Other)
device string Optional Primary device (Mobile, Desktop, Tablet)
ethnicity string Optional Ethnic background
qualification string Optional Education level
employment_status string Optional Employment status
income_range string Optional Income range bracket accept only in USD like Ex: 500-1200

Code Samples

curl --location 'https://api.research4insights.com/sandbox/v1/add_participant' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer R4I_TEST_xxxxxxxxxxxxxx' \
--data '{
  "pid": "MY-6jh7gh7gh",
  "supplier_id": "R4I-S-25AD-3876",
  "participant_name": "Edward Patrick",
  "email": "",
  "phone": "",
  "age": 28,
  "country": "USA",
  "zipcode": "236789",
  "gender": "Male",
  "device": "Mobile",
  "ethnicity": "Asian",
  "qualification": "Graduation",
  "employment_status": "Private Job",
  "income_range": "500-1200"
}'
{
  "status": "success",
  "message": "Request processed successfully",
  "data": {
    "success": true,
    "message": "Participant added successfully",
    "pid": "MY-6jh7gh7gh"
  }
}

View Participants

Retrieve a paginated list of participants with their demographic information.

POST
POST /view_participants

Parameters

Field Type Required Description
page number Optional Page number for pagination
per_page number Optional Number of items per page
supplier_id string Required Supplier identifier (format: R4I-S-XXXX-XXXX)

Code Samples

curl --location 'https://api.research4insights.com/sandbox/v1/view_participants' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer R4I_TEST_xxxxxxxxxxxxxx' \
--data '{
  "page": 1,
  "per_page": 10,
  "supplier_id": "R4I-S-25SD-3445"
}'
{
  "status": "success",
  "message": "Request processed successfully",
  "data": {
    "page": 1,
    "per_page": 10,
    "total": 2,
    "data": [
      {
        "pid": "hyrtyvudsk",
        "participant_name": "Edward Patrick",
        "email": "",
        "phone": "",
        "country": "United States",
        "zipcode": "236789",
        "ethnicity": "Asian",
        "device": "Mobile",
        "age": "28",
        "gender": "Male",
        "qualification": "Graduation",
        "employment_status": "Private Job",
        "income_range": "500-1200"
      }
    ]
  }
}

Generate Survey URL (Direct Link)

Create a survey link directly using survey_id and supplier_id without adding a participant first.

POST
POST /generate_survey_url

Headers

Header Value Required
Authorization Bearer R4I_TEST_xxxxxxxxxxxxxx Required
Content-Type application/json Required

Parameters

Field Type Required Description
survey_id string Required Unique survey identifier (e.g., PROJ-D3423423)
supplier_id string Required Supplier identifier in format (e.g., R4I-S-DF25-AS8)

Code Samples

curl --location 'https://api.research4insights.com/sandbox/v1/generate_survey_url' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer R4I_TEST_TKG74JJ29KLT009ATML21' \
--data '{
  "survey_id": "PROJ-32AB91CD",
  "supplier_id": "R4I-S-25DF-AS8"
}'
<?php
$ch = curl_init("https://api.research4insights.com/sandbox/v1/generate_survey_url");
curl_setopt_array($ch, [
  CURLOPT_POST => true,
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer R4I_TEST_TKG74JJ29KLT009ATML21",
    "Content-Type: application/json"
  ],
  CURLOPT_POSTFIELDS => json_encode([
    "survey_id" => "PROJ-32AB91CD",
    "supplier_id" => "R4I-S-25ER-DF8"
  ])
]);
$response = curl_exec($ch);
curl_close($ch);
echo $response;
?>
const fetch = require('node-fetch');

(async () => {
  const response = await fetch('https://api.research4insights.com/sandbox/v1/generate_survey_url', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer R4I_TEST_TKG74JJ29KLT009ATML21',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      survey_id: "PROJ-32AB91CD",
      supplier_id: "R4I-S-25FF-RT18"
    })
  });
  
  const data = await response.json();
  console.log(data);
})();
{
  "status": "success",
  "message": "Survey link generated successfully",
  "data": {
    "survey_link": "https://openion.research4insights.com/survey/letdosurvey?sid=UFJPSi0zMkFCOTFDRHwzOA==&security_code=NCqpMJuL&PID=[%%pid%%]"
  }
}

Response Fields

Field Type Description
data.survey_link string Generated survey URL containing the encoded survey_id and supplier_id combination. The PID will be replaced dynamically by respondent’s participant ID.
data.security_code string Unique security code generated for this survey session. Do not modify.
Usage Instructions
  • This API is used when you want to generate survey links directly without using the Add Participant API.
  • Replace [%%pid%%] in the link with your panelist’s PID or tracking ID when sending the survey.
  • Each generated URL contains a unique security_code for validation.
  • Example final URL: https://openion.research4insights.com/survey/letdosurvey?sid=UFJPSi0zMkFCOTFDRHwzOA==&security_code=NCqpMJuL&PID=PANEL123

Survey Stats

Retrieve aggregate performance statistics for all surveys by supplier.

POST
POST /survey_stats

Parameters

Field Type Required Description
supplier_id string Required Supplier identifier

Code Samples

curl --location 'http://api.research4insights.com/sandbox/v1/survey_stats' \
--header 'Authorization: Bearer R4I_TEST_xxxxxxxxxxxxxx' \
--header 'Content-Type: application/json' \
--data '{
  "supplier_id": "R4I-S-25-38"
}'
{
  "status": "success",
  "message": "Request processed successfully",
  "data": {
    "isVerified": false,
    "clicks": 2,
    "surveyStarts": 2,
    "completes": 1,
    "fails": 0,
    "overQuota": 0,
    "qualityTerms": 0,
    "preSurveyTerminates": 0,
    "preSurveyOverQuota": 0,
    "preSurveyQualityTermination": 0,
    "averageLOI": 0.12,
    "revenue": 0,
    "Conversion": 50
  }
}

Metrics Explained

Metric Description
clicks Number of survey links clicked
surveyStarts Number of surveys started
completes Number of surveys completed
fails Number of survey failures
overQuota Number of over quota terminations
qualityTerms Number of quality terminations
averageLOI Average length of interview in minutes
Conversion Conversion rate percentage

Survey Stats By ID

Retrieve detailed participation statistics for a specific survey project.

POST
POST /survey_stats_by_id

Parameters

Field Type Required Description
supplier_id string Required Supplier identifier
project_id string Required Project/survey identifier
page number Required Page number for pagination
per_page number Required Number of items per page

Code Samples

curl --location 'http://api.research4insights.com/sandbox/v1/survey_stats_by_id' \
--header 'Authorization: Bearer R4I_TEST_xxxxxxxxxxxxxx' \
--header 'Content-Type: application/json' \
--data '{
  "supplier_id": "R4I-S-25-38",
  "project_id": "R4I-2342342",
  "page": 1,
  "per_page": 10
}'
{
  "status": "success",
  "message": "Request processed successfully",
  "data": {
    "total": 1,
    "page": 1,
    "per_page": 10,
    "data": [
      {
        "participant_id": "hyrtyvudsk",
        "project": "R4I-2342342",
        "status": "complete",
        "token": "gsdfas342fdf45df2df45f4j23fg7fw454f",
        "cpi": "0",
        "ip": "41.24.12.142",
        "start_time": "2025-10-26 00:30:18",
        "end_time": "2025-10-26 00:30:25",
        "click_at": "2025-10-26 00:02:14",
        "verified": false
      }
    ]
  }
}

Survey Stats By Participant

Retrieve survey participation history for a specific participant.

POST
POST /survey_stats_by_participant

Parameters

Field Type Required Description
supplier_id string Required Supplier identifier
participant_id string Required Participant identifier
page number Required Page number for pagination
per_page number Required Number of items per page

Code Samples

curl --location 'http://api.research4insights.com/sandbox/v1/survey_stats_by_participant' \
--header 'Authorization: Bearer R4I_TEST_xxxxxxxxxxxxxx' \
--header 'Content-Type: application/json' \
--data '{
  "supplier_id": "R4I-S-25-38",
  "participant_id": "hyrtyvudsk",
  "page": 1,
  "per_page": 10
}'
{
  "status": "success",
  "message": "Request processed successfully",
  "data": {
    "total": 1,
    "page": 1,
    "per_page": 10,
    "data": [
      {
        "participant_id": "hyrtyvudsk",
        "project": "R4I-2342342",
        "status": "complete",
        "token": "gsdfas342fdf45df2df45f4j23fg7fw454f",
        "cpi": "0",
        "ip": "41.24.12.142",
        "start_time": "2025-10-26 00:30:18",
        "end_time": "2025-10-26 00:30:25",
        "click_at": "2025-10-26 00:02:14",
        "verified": false
      }
    ]
  }
}

Response Fields

Field Description
participant_id Unique identifier for the participant
project Survey/project identifier
status Completion status (complete, terminate, etc.)
token Unique session token
cpi Cost per interview for the survey
ip IP address of the participant
start_time Survey start timestamp
end_time Survey end timestamp
click_at Initial click timestamp
verified Whether the response was verified

Errors & Response Codes

All responses use HTTP status codes alongside the JSON structure.

HTTP apiStatus/msg Meaning / Action
200 success Request processed successfully. Check result for data.
400 error Bad request — missing/invalid parameters. Validate request body.
401 error Unauthorized — API key missing or invalid. Verify Authorization header and key.
403 error Forbidden — partner not allowed to access resource.
404 error Not found — resource (pid/participant) not available.
429 error Rate limit exceeded. Back off then retry.
500 error Server error. Retry after short delay and contact support if persistent.

Example Error Response

{
  "apiStatus": "error",
  "msg": "Invalid API key",
  "result": null
}

Support

Get help with API integration and troubleshooting

For sandbox credentials, production key requests, or technical support, contact: