Get Surveys V2

Get Surveys - GET /surveys - https://api.spectrumsurveys.com/suppliers/v2/surveys

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

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
    }
 ]
}