...
...
...
...
...
...
...
...
...
| Code Block |
|---|
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.
| Info |
|---|
We will limit the max time that someone may pass, is |
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.
| Note |
|---|
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
| Info |
|---|
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 https://purespectrum.atlassian.net/wiki/spaces/PA/pages/33613201 |
Sample API Request
| Code Block |
|---|
GET /suppliers/v2/surveys/ Host: api.spectrumsurveys.com access-token: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx |
...
| Code Block |
|---|
{
"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
}
]
} |