Page Comparison

...

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 method API call to check the status of existing surveys you are delivering onsample 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 `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.

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

Timestamp in milliseconds since Unix Epoch
category	String	The category of the survey
category_code	integer	Survey Category Code
last_complete_date	UTC

Timestamp

Timestamp in milliseconds since Unix Epoch
crtd_on	UTC

Timestamp

Timestamp in milliseconds since Unix Epoch
mod_on	UTC

Timestamp

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.

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 HTTP/1.1 Host: api.spectrumsurveys.com Content-Type: application/x-www-form-urlencoded 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
    }
 ]
}

Versions Compared

Old Version 20

New Version Current

Key

How to use the API:

Registered query string param

mod_on query string param

survey_status query string param

HEADER Parameters

Response Parameters

ISO 3166)

Sample API Request