Get Surveys - GET /surveys - https://api.spectrumsurveys.com/suppliers/v2/surveys
How 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 if that survey was taken in the exclusion_period. |
survey_grouping.survey_ids | Array | If a respondent has previously taken any of these surveys, they will be excluded if that survey was taken in the exclusion_period. |
survey_grouping.exclusion_period | Number | This is the number of days for which a respondent is disqualified from taking another survey in the same survey group. |
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 https://purespectrum.atlassian.net/wiki/spaces/PA/pages/33613201 |
Sample API Request
GET /suppliers/v2/surveys/ Host: api.spectrumsurveys.com access-token: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Sample 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
}
]
}