Get Surveys V2
- David Boyajian
- Colleen Koster
- Claudio Baldi
Get Surveys - GET /surveys - https://api.spectrumsurveys.com/suppliers/v2/surveysHow to use the API:
Call this API to view surveys that your Supplier account has an allocation for. You are expected to Register Intent & send sample to these surveys.
You also can use this API call to check the status of existing surveys you are delivering sample to, including current LOI, IR, & CPI.
Registered query string param
The "reg" query string parameter can be used to filter the surveys returned in the response.
"false" - Returns only surveys where the Supplier has not registered intent
"true" - Returns only surveys where the Supplier has registered intent
"both" - Returns all surveys (default)
Examples:
/surveys?reg=false
/surveys?reg=true
/surveys?reg=both
mod_on query string param
The “mod_on” query string parameter can be used to filter the surveys returned in the response, so that you only get surveys that have been modified since the timestamp you submit.
We will limit the max time that someone may pass, is survey_status is anything other than 22. This is to prevent our system from aggregating results that are too large.
Examples:
/surveys?mod_on=1700630207049
survey_status query string param
The “survey_status” query string parameter can be used to filter the surveys returned in the response, so that you receive surveys in a specific status.
If the parameter is missing, the default value is LIVE surveys only (status=22).
If you use this parameter for any status other than LIVE surveys (e.g. 22), then you must pass in a mod_on that is newer than the max timestamp.
22 - Returns LIVE surveys
33 - Returns PAUSED surveys
44 - Returns CLOSED surveys
You may string together statuses, comma separated
Examples:
/surveys?mod_on=1700630207049&survey_status=33,44
HEADER Parameters
Parameter | Type | Required | Description |
|---|---|---|---|
access-token | string | Yes | Token used to identify the authenticity of the user. |
Response Parameters
Parameter | Type | Description |
|---|---|---|
survey_id | integer | Survey ID |
survey_name | String | Name of survey |
survey_status | String | 11 for draft, 22 for live, 33 for paused, 44 for closed |
supplier_completes | Object | Contains completes needed, achieved, and remaining |
survey_performance | Object | Contains Overall & Last Block IR & LOI |
overall | Object | This performance corresponds to IR & LOI since survey start |
last_block | Object | This performance corresponds to IR & LOI in the last block |
ir | Integer | Conversion rate |
loi | Integer | Loi in minutes |
cpi | Integer | Cpi value |
field_end_date | UTC Timestamp in milliseconds since Unix Epoch | |
category | String | The category of the survey |
category_code | integer | Survey Category Code |
last_complete_date | UTC Timestamp in milliseconds since Unix Epoch | |
crtd_on | UTC Timestamp in milliseconds since Unix Epoch | |
mod_on | UTC Timestamp in milliseconds since Unix Epoch | |
click_balancing | Boolean | Indicates whether the survey is click balancing or not. “1" for yes, “0" for no. When “click_balancing” = “1”, the survey is counting clicks rather than completes and the numbers shown in the API response are reflective the number of clicks needed, achieved, remaining, etc. |
buyer_id | Integer or Null | |
surveyLocalization | string | 2 letter code for language, followed by underscore, followed by 2 letter code for country (according to ISO 3166) |
survey_grouping | Object | If a respondent has previously taken any of these surveys, they will be excluded. |
survey_grouping.survey_ids | Array | If a respondent has previously taken any of these surveys, they will be excluded. |
survey_grouping.exclusion_period | Number | This field may be ignored. |
purescore | Number | 0 indcates that a survey will accept any respondent, regardless of PureScore. 1 indicates that a survey will accept only respondents with a passing PureScore. If a respondent has ever failed with ps_rstatus=42, avoid sending them to surveys with PureScore = 1. See Minimizing Clickwaste with ps_rstatus |
Sample API Request
GET /suppliers/v2/surveys/
Host: api.spectrumsurveys.com
access-token: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxSample API Response
{
"apiStatus": "success",
"msg": "Surveys fetched successfully ",
"version": "2.0",
"surveys": [
{
"cpi": 10.3,
"survey_grouping": {},
"supplier_completes": {
"needed": 24,
"achieved": 0,
"remaining": 24
},
"survey_performance": {
"overall": {
"ir": 8,
"loi": 32
},
"last_block": {
"ir": 8,
"loi": 32
}
},
"survey_id": 1854,
"purescore":1,
"last_complete_date": null,
"survey_name": "Media and Entertainment Survey #1854",
"surveyLocalization": "en_US",
"survey_status": 22,
"buyer_id": 2,
"field_end_date": 1487886077000,
"crtd_on": 1487281277070,
"mod_on": 1488314397116,
"category": "Media and Entertainment",
"category_code": 224
},
{
"cpi": 16.5,
"survey_grouping": [],
"supplier_completes": {
"needed": 12,
"achieved": 1,
"remaining": 11
},
"survey_performance": {
"overall": {
"ir": 4,
"loi": 16
},
"last_block": {
"ir": 4,
"loi": 16
}
},
"survey_id": 1983,
"last_complete_date": 1487891732857,
"survey_name": "Media and Entertainment Survey #1983",
"surveyLocalization": "en_US",
"survey_status": 22,
"buyer_id": 2,
"field_end_date": 1488908564000,
"crtd_on": 1487871678958,
"mod_on": 1488303824981,
"category": "Media and Entertainment",
"category_code": 224
},
{
"cpi": 1.50,
"survey_grouping": {
"survey_ids": [
2825,
2834,
2944,
2947
],
"exclusion_period": 90
},
"supplier_completes": {
"needed": 300,
"achieved": 0,
"remaining": 126
},
"survey_performance": {
"overall": {
"ir": 44,
"loi": 10
},
"last_block": {
"ir": 5,
"loi": 11
}
},
"survey_id": 2836,
"purescore": 1,
"last_complete_date": null,
"survey_name": "Shopping and Retail Survey #2836",
"surveyLocalization": "en_US",
"survey_status": 22,
"buyer_id": 91,
"field_end_date": 1493657003000,
"crtd_on": 1492215861550,
"mod_on": 1492793063411,
"category": "Shopping and Retail",
"category_code": 228
}
]
}