Surveys & Streams
List Surveys & Streams
GET
/
v2
/
surveys
List Surveys & Streams
curl --request GET \
--url https://api.researchdesk.com/v2/surveys \
--header 'Authorization: <authorization>'import requests
url = "https://api.researchdesk.com/v2/surveys"
headers = {"Authorization": "<authorization>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {Authorization: '<authorization>'}};
fetch('https://api.researchdesk.com/v2/surveys', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.researchdesk.com/v2/surveys",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"Authorization: <authorization>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.researchdesk.com/v2/surveys"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("Authorization", "<authorization>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://api.researchdesk.com/v2/surveys")
.header("Authorization", "<authorization>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.researchdesk.com/v2/surveys")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["Authorization"] = '<authorization>'
response = http.request(request)
puts response.read_body{
"Status": 0,
"Message": "Success",
"Data": [
{
"SurveyName": "US Gen Pop Survey - Short",
"SurveyNumber": 2634,
"ProjectUd": "db02d54e-9b65-4a49-bb22-cfeec3a3fb62",
"SurveyUd": "d6cee0a1-3c4c-4252-b502-d3dae24db9ff",
"SurveyStatus": "Live",
"SurveyLanguage": "en",
"SurveyCountry": "US",
"PII": false,
"EstimatedLOI": 2,
"EstimatedIR": 100,
"DeviceCompatibility": [
{
"device_id": 1,
"device_name": "Desktop"
},
{
"device_id": 2,
"device_name": "Mobile"
},
{
"device_id": 3,
"device_name": "Tablet"
}
],
"SampleExclusions": [
"63099002-c17f-4fda-b8c8-29d7f33c625c",
"550d11c7-1b0e-4276-a96a-72004ad0bac9"
],
"SampleExclusionsRules": {
"Statuses": [
"Complete",
"Abandon"
],
"LookbackDays": 90
},
"Streams": [
{
"StreamId": 850,
"StreamUd": "f1789d2b-ac7c-415b-bcb5-8b285e60e698",
"StreamName": "US Gen Pop - Census Rep",
"StreamStatus": "Live",
"CalculationType": "Completes",
"Entrants": 0,
"ExpectedStreamCompletes": 0,
"ActualStreamCompletes": 0,
"Expected": 0,
"Actual": 0,
"ActualIR": 0,
"ActualLOI": 0,
"CPI": 0,
"DaysInField": 1,
"Conversion": 0,
"Remaining": 0,
"QualificationsLastChangedTimestamp": "2024-06-18 17:41:22",
"QuotasLastChangedTimestamp": "2024-06-18 17:41:22",
"B2B": false,
"Recontact": false
},
{
"StreamId": 853,
"StreamUd": "1ff36ea1-8181-406c-8c2c-45fc44f4f3f5",
"StreamName": "High Income, Employed",
"StreamStatus": "Live",
"CalculationType": "Completes",
"Entrants": 0,
"ExpectedStreamCompletes": 8,
"ActualStreamCompletes": 0,
"Expected": 8,
"Actual": 0,
"ActualIR": 0,
"ActualLOI": 0,
"CPI": 0,
"DaysInField": 5,
"Conversion": 0,
"Remaining": 8,
"QualificationsLastChangedTimestamp": "2024-06-18 17:41:22",
"QuotasLastChangedTimestamp": "2024-06-18 17:41:22",
"B2B": false,
"Recontact": false
}
]
}
]
}Returns the Surveys and Streams allocated to you (your “supplier allocations”). A Stream represents a sample plan, each with its own qualifications and quotas; multiple Streams may route into one Survey.
In that example, only respondents with
Query String Parameters
| Parameter | Description | Required | Example |
|---|---|---|---|
status | Filter Surveys by status. Values: Draft, Live, Paused. | No | ?status=Live |
Key Response Fields
| Field | Description |
|---|---|
SurveyNumber | Survey identifier. Use SurveyNumber and StreamId in any communication with our team about projects and performance. |
ProjectUd | UD for the parent project. Use this value for any Research Defender PREDUPE implementation. |
CalculationType | Whether targets are counted per Completes or Survey Starts. Completes are respondents who qualified and finished end to end; Survey Starts are respondents who entered the client survey. |
Expected / Actual | Required vs. achieved Completes (or Survey Starts) for the supplier. Use these rather than the deprecated ExpectedStreamCompletes / ActualStreamCompletes. |
Remaining | Completes (or Survey Starts) still needed. Use this as the main indicator of whether more respondents are needed. When Remaining = 0, pause sample to the quota cell. |
QualificationsLastChangedTimestamp | Updated when a Stream’s qualifications change; use it to prompt a refresh. |
QuotasLastChangedTimestamp | Updated when a Stream’s quotas change (including when a quota closes). Not updated on every increment. |
B2B | Derived field indicating whether the Stream seeks B2B respondents. |
Recontact | true when the Stream is a recontact. Only PIDs from Get Stream Lists are eligible. |
SampleExclusions | ProjectUd values for projects whose previous respondents should be excluded. |
SampleExclusionsRules | When present, Statuses and LookbackDays scope that exclusion. null means every status and a 1-year lookback. |
Sample exclusion rules
SampleExclusionsRules tells you which respondent statuses count toward exclusion and how far back prior participation is considered. It does not change the project list in SampleExclusions. Rules can only loosen the default (every status, 365 days). Suppliers that ignore the object keep the previous behavior.
| Field | Type | Description |
|---|---|---|
Statuses | Array of strings | Completion statuses that count toward exclusion. A prior participation in any other status is not excluded. |
LookbackDays | Integer | Days back prior participation is considered. Older participation does not count. |
| Status | Meaning | Redirect link |
|---|---|---|
Complete | Respondent completed the survey | SurveyCompleteLink |
OverQuota | Respondent was over quota | SurveyOverquotaLink |
Security | Respondent failed a security check | SecurityFraudTermLink |
Terminate | Respondent was screened out | SurveyTermLink |
Abandon | Respondent abandoned the survey | No redirect — the session ended without a terminal event |
{
"SampleExclusions": [
"9c9482e1-f8c0-4fef-9bf8-2379c8132c97",
"0a299797-efa5-46f2-861e-4d0c0c4209de"
],
"SampleExclusionsRules": {
"Statuses": ["Complete", "Abandon"],
"LookbackDays": 90
}
}
Complete or Abandon from the listed projects within the last 90 days are excluded. A Security, Terminate, or OverQuota from one of those projects is not blocked.
The same object is returned on Get Survey and Get Survey by Stream.
Poll this endpoint every 2–3 minutes during fieldwork to detect status, allocation, and quota changes.
Headers
Your obfuscated Supply API key (GUID), provided by Rep Data.
Query Parameters
Filter Surveys by status (Draft, Live, Paused).
Was this page helpful?
List Surveys & Streams
curl --request GET \
--url https://api.researchdesk.com/v2/surveys \
--header 'Authorization: <authorization>'import requests
url = "https://api.researchdesk.com/v2/surveys"
headers = {"Authorization": "<authorization>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {Authorization: '<authorization>'}};
fetch('https://api.researchdesk.com/v2/surveys', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.researchdesk.com/v2/surveys",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"Authorization: <authorization>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.researchdesk.com/v2/surveys"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("Authorization", "<authorization>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://api.researchdesk.com/v2/surveys")
.header("Authorization", "<authorization>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.researchdesk.com/v2/surveys")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["Authorization"] = '<authorization>'
response = http.request(request)
puts response.read_body{
"Status": 0,
"Message": "Success",
"Data": [
{
"SurveyName": "US Gen Pop Survey - Short",
"SurveyNumber": 2634,
"ProjectUd": "db02d54e-9b65-4a49-bb22-cfeec3a3fb62",
"SurveyUd": "d6cee0a1-3c4c-4252-b502-d3dae24db9ff",
"SurveyStatus": "Live",
"SurveyLanguage": "en",
"SurveyCountry": "US",
"PII": false,
"EstimatedLOI": 2,
"EstimatedIR": 100,
"DeviceCompatibility": [
{
"device_id": 1,
"device_name": "Desktop"
},
{
"device_id": 2,
"device_name": "Mobile"
},
{
"device_id": 3,
"device_name": "Tablet"
}
],
"SampleExclusions": [
"63099002-c17f-4fda-b8c8-29d7f33c625c",
"550d11c7-1b0e-4276-a96a-72004ad0bac9"
],
"SampleExclusionsRules": {
"Statuses": [
"Complete",
"Abandon"
],
"LookbackDays": 90
},
"Streams": [
{
"StreamId": 850,
"StreamUd": "f1789d2b-ac7c-415b-bcb5-8b285e60e698",
"StreamName": "US Gen Pop - Census Rep",
"StreamStatus": "Live",
"CalculationType": "Completes",
"Entrants": 0,
"ExpectedStreamCompletes": 0,
"ActualStreamCompletes": 0,
"Expected": 0,
"Actual": 0,
"ActualIR": 0,
"ActualLOI": 0,
"CPI": 0,
"DaysInField": 1,
"Conversion": 0,
"Remaining": 0,
"QualificationsLastChangedTimestamp": "2024-06-18 17:41:22",
"QuotasLastChangedTimestamp": "2024-06-18 17:41:22",
"B2B": false,
"Recontact": false
},
{
"StreamId": 853,
"StreamUd": "1ff36ea1-8181-406c-8c2c-45fc44f4f3f5",
"StreamName": "High Income, Employed",
"StreamStatus": "Live",
"CalculationType": "Completes",
"Entrants": 0,
"ExpectedStreamCompletes": 8,
"ActualStreamCompletes": 0,
"Expected": 8,
"Actual": 0,
"ActualIR": 0,
"ActualLOI": 0,
"CPI": 0,
"DaysInField": 5,
"Conversion": 0,
"Remaining": 8,
"QualificationsLastChangedTimestamp": "2024-06-18 17:41:22",
"QuotasLastChangedTimestamp": "2024-06-18 17:41:22",
"B2B": false,
"Recontact": false
}
]
}
]
}