Skip to end of metadata
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 80 Next » 

GET suppliers/v2/surveys/:survey_id

 https://api.spectrumsurveys.com/suppliers/v2/surveys/:survey_id

ORDER OF OPERATIONS

 Please read the Respondent Order of Operations in order to understand the PureSpectrum targeting flow.

It is possible for a respondent to belong to more than one quota. If they belong to any quota where currently_open=0, they will be terminated for improper targeting.

HEADER

Parameter

Type

Required

Description

access-token

String

Yes

Token used to identify the authenticity of the user.

Note: If there are no quotas or qualifications in the survey, then the Response will return the default quota for age 18-99:

We will be releasing new functionality for “Guaranteed Allocations” that will help supplier’s understand if some portion of completes are guaranteed (exclusive) to the supplier. Find documentation here: Guaranteed Allocations

RESPONSE PARAMETERS

Qualifications:    

Parameter

Type

Description

survey_id

Number

This is the PureSpectrum survey ID

survey_status

Number

Indicates the Survey's current status. 11 for draft, 22 for live, 33 for paused, 44 for closed

surveyLocalization

String

2 letter code for language, followed by underscore, followed by 2 letter code for country (according to ISO 3166). Only one localization per survey is allowed.
(Apologies for the use of camelCase instead of snake_case for the Parameter key)

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

(1-100)

This is the Incidence Rate of the performance period. Divide by 100 to get the percentage. E.G. 60% is returned as 60 by IR. IR is defined as Completes/(Completes+Buyer_Terminations+Buyer_Drop+Buyer_OverQuota)

loi

Integer

(1-120)

This is the Median LOI of the performance period.

qualifications

Array of Objects

This array contains all qualification codes upon which certain condition codes are applied. If a qualification code is absent, PureSpectrum will not check this particular qualification for each respondent. A qualification's absence also means that no quota will be applied on that qualification code.

qualification_code

Number

Purespectrum code for the qualification.

condition_codes

Array of Strings

This array is part of the qualification hash, referring to it's preceding qualification_code. If more than one condition code is present, handle the additional condition codes as an OR operator. For example, if for race (qualification 214), condition codes "111","112","114" are present, the respondent may either be White, Hispanic, or Asian to qualify for the survey.

range_sets

Object

Contains the from, to, and units if the question type is "range"

from

Number

Specifies the starting point for the range

to

Number

Specifies the ending point for the range

units

Number

Specifies the unit type according to Quotas & Qualifications V2#units table found on the bottom of this page

quotas

Array

Array containing the quota objects of a survey. If no quotas have been specified by the buyer, then we will display a default quota for ages 18-99.

quota_id

String

This is the internal PureSpectrum ID for the quota.

criteria

Array

Contains the targeting criteria objects of an individual quota

quantities

Object

Contains completes needed, achieved, remaining, & open_quantity. open_quantity is the amount that indicates the number of completes currently available to be filled in this quota

currently_open

Number

Number of completes currently available in the quota. If the value is 0, any respondent matching this quota will be rejected.

achieved

Number

Quantity within this quota ID that your supply has completed

remaining

Number

Theoretical Number of completes remaining for your supply

crtd_on

UTC Timestamp in milliseconds since Unix Epoch

Timestamp of when this quota id was created (milliseconds since Unix Epoch)

mod_on

UTC Timestamp in milliseconds since Unix Epoch

Timestamp of when this quota id was last modified. This would only change if the quota is locked/unlocked, or the quantity is changed. If a quota's criteria are modified, this quota is closed and a new one is created. (milliseconds since Unix Epoch)

field_end_date

UTC Timestamp in milliseconds since Unix Epoch

Timestamp of when this survey is scheduled to end fielding. The survey may stay open past fielding at the buyer's discretion.

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_message

String

The buyer may choose to add a custom message to their survey. This message is present here, limited to 500 characters. If no message is present, this will display as the empty string ""

pii

bool

Indicates whether the survey requires PII. True for yes, False for no.

price_type

Number

NOTE: Not currently live on production and all responses will contain the same value

This number indicates the pricing methodology used by the survey.

1-priced according to the rates you have provided via price card or formulas

2-priced according to preferred rate card negotiated with buyer

3-priced according to operator override //this is a price that has been manually modified by a PureSpectrum employee

4-programmatic direct //details to come

5-priced according to API response //details to come

buyer_id

Number

This is the buyer's company ID that will be useful in determining your performance with different buyers in the marketplace. If applicable, the buyer id will be displayed. In all other cases, the buyer id will be NULL.

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. If there are no survey grouping id's present, this will return an empty object.

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.

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

Response Codes & Answers

Reference the API endpoint to view questions/qualifications for each country. To view different countries, change the localization code: http://api.spectrumsurveys.com/suppliers/v2/attributes?localization=en_US&format=true&page=1

In the US, if a survey is targeting on CBSA, MSA, or County, the api response will return a list of valid zipcodes instead of the specific codes.

Core Profile Points:

The new condition code 113 - "Prefer not to say“ for the qualification 211 - “Gender” has been releases on the 30th of September 2024 for all the countries.

Qualification

Qualification Code

Conditions

Conditions Code

US-en

USeng Label (Same as generic)

US-en Sort Order

CA-en

CA-en Label

CA-en Sort Order

gender

211

y

y

Gender

Male

111

y

y

Male

1

Female

112

y

y

Female

2

Prefer not to say

113

y

y

Prefer not to say

age

212

y

y

Age

houseHoldIncome

213

y

y

Income

race

244

White

111

y

Black or African American

112

y

Asian

113

y

Native Hawaiian or Other Pacific Islander

114

y

American Indian or Alaska Native

115

y

Other Race

116

y

hispanic origin

245

Yes

111

y

No

112

y

employments

215

y

Unemployed

111

y

y

Unemployed

1

a Student

112

y

y

a Student

2

Part-Time

113

y

y

Part-time

3

Full Time

114

y

y

Full-time

4

Retired

115

y

y

Retired

5

 Contract, Freelance or Temporary Employee

116

y

 Contract, Freelance or Temporary Employee

6

None of the above

117

y

None of the above

7

educations

216

y

y

Some high school

111

y

y

Some High School

1

High School Graduate

112

y

y

High School Diploma

2

Some College

113

y

y

Some University

3

Bachelor's Degree

114

y

y

University Degree

4

Master's Degree

115

y

Some Postgraduate

117

y

Some Postgraduate

5

Graduate/Post Graduate Degree

118

y

Post Graduate Degree

6

Doctorate Degree

116

y

Prefer not to answer

119

y

Prefer not to answer

7

relationships

217

y

Single

111

y

y

 Single

1

Engaged

112

y

Engaged

2

Living with a Partner

113

y

y

Living with a Partner

3

Married

114

y

y

Married

4

Divorced

115

y

y

Divorced

5

Widowed

116

y

y

Widowed

6

Prefer not to answer

117

y

Prefer not to answer

7

device

219

y

y

Desktop

111

y

y

Desktop

1

Mobile

112

y

y

Mobile

2

Tablet

113

y

y

Tablet

3

Location-Nationally Representative

222

y

regions

223

y

Northeast

1

y

Midwest

2

y

South

3

y

West

4

y

divisions

224

y

New England

1

y

Middle Atlantic

2

y

East North Central

3

y

West North Central

4

y

South Atlantic

5

y

East South Central

6

y

West South Central

7

y

Mountain

8

y

Pacific

9

y

states

225

y

Use spreadsheet for name and codes

y

msa

226

y

No need to map - Uses zipcodes with qual code 229

y

cbsa

227

y

No need to map - Uses zipcodes with qual code 229

y

county

228

y

No need to map - Uses zipcodes with qual code 229

y

zipcodes

229

y

Use real zipcodes

y

dma

231

Use spreadsheet for name and codes - attached below

y

child age and gender

232

Use spreadsheet for name and codes

y

y

provinces

233

y

Alberta

1

y

British Columbia

2

y

Manitoba

3

y

New Brunswick

4

y

Newfoundland and Labrador

5

y

Nova Scotia

7

y

Northwest Territory

6

y

Nunavut

8

y

Ontario

9

y

Prince Edward Island

10

y

Quebec

11

y

Saskatchewan

12

y

Yukon

13

y

US, Location tables attached:

Child Age & Gender Table:

Units

 Age

Years

311

Months

312

Currency

Dollars

321

Euro

322

GBP

323

Aus Dollar

324

Sample Request

GET /suppliers/v2/surveys/:survey_id HTTP/1.1
Host: api.spectrumsurveys.com
access-token: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Sample Response

{
  "apiStatus": "success",
  "msg": "Survey Quota and Qualification fetched successfully ",
  "version": "2.0",
  "survey": {
    "cpi": 16.5,
    "survey_grouping": 
		"survey_ids": [
                317764,
                317771,
                318380,
                318388
            ],
            "exclusion_period": 30,
    "supplier_completes": {
      "needed": 12,
      "achieved": 1,
      "remaining": 11
    },
    "price_type": 1,
    "pii": false,
    "buyer_message": "",
    "survey_performance": {
      "overall": {
        "ir": 4,
        "loi": 16
      },
      "last_block": {
        "ir": 4,
        "loi": 16
      }
    },
    "survey_id": 1983,
    "purescore":1,
    "last_complete_date": 1487891732857,
    "survey_name": "Huntsville",
    "surveyLocalization": "en_US",
    "survey_status": 22,
    "buyer_id": 2,
    "field_end_date": 1488908564000,
    "crtd_on": 1487871678958,
    "mod_on": 1488303824981,
    "qualifications": [
      {
        "qualification_code": 212,
        "range_sets": [
          {
            "from": 25,
            "to": 49,
            "units": 311
          }
        ]
      },
      {
        "condition_codes": [
          "111",
          "114",
          "117"
        ],
        "qualification_code": 214
      },
      {
        "condition_codes": [
          "35601",
          "35602",
          "35603",
          "35609",
          "35611",
          "35612",
          "35613",
          "35614",
          "35615",
          "35619",
          "35620",
          "35621",
          "35622",
          "35640",
          "35647",
          "35649",
          "35670",
          "35671",
          "35673",
          "35699",
          "35739",
          "35741",
          "35742",
          "35748",
          "35749",
          "35750",
          "35754",
          "35756",
          "35757",
          "35758",
          "35759",
          "35760",
          "35761",
          "35762",
          "35763",
          "35767",
          "35773",
          "35775",
          "35801",
          "35802",
          "35803",
          "35804",
          "35805",
          "35806",
          "35807",
          "35808",
          "35809",
          "35810",
          "35811",
          "35812",
          "35813",
          "35814",
          "35815",
          "35816",
          "35824",
          "35893",
          "35894",
          "35895",
          "35896",
          "35897",
          "35898",
          "35899"
        ],
        "qualification_code": 229
      }
    ],
    "quotas": [
      {
        "quota_id": "15c752f4-a585-4858-8734-f76a843f70df",
        "quantities": {
          "currently_open": 96,
          "remaining": 96,
          "achieved": 4
        },
        "criteria": [
          {
            "qualification_code": 212,
            "range_sets": [
              {
                "units": 311,
                "to": 49,
                "from": 25
              }
            ]
          }
        ],
        "crtd_on": 1487860208025,
        "mod_on": 1487984044985
      }
    ]
  }
}

Quota Examples

    "quotas":[
        //example quota on single age range
		{
            "quota_id": "123",
            "criteria":[{
                    “qualification_code”: 212,
            		"range_sets":[{"from":13,"to":18,“units”:“311”}]
       			 }
            ],
            "quantities":{
                "currently_open":100,
                "remaining":100,
                "achieved":0
            },
            "crtd_on":124411231313,
            "mod_on":11321334733
        },
        //example quota with a single condition on Race
		{
            "quota_id": "123",
            "criteria":[{
                    “qualification_code”: 214,
            		"condition_codes":["111"]
       			 }
            ],
            "quantities":{
                "currently_open":100,
                "remaining":100,
                "achieved":0
            },
            "crtd_on":124411231313,
            "mod_on":11321334733
        },
        //example quota with OR condition on Race
		{
            "quota_id": "123",
            "criteria":[{
                    “qualification_code”: 214,
            		"condition_codes":["111","112","114"]
       			 }
            ],
            "quantities":{
                "currently_open":100,
                "remaining":100,
                "achieved":0
            },
            "crtd_on":124411231313,
            "mod_on":11321334733
        },
        //example quota with nested conditions for gender and age
		{
            "quota_id": "123",
            "criteria":[{
                    “qualification_code”: 211,
            		"condition_codes":["111"]
       			 },
				 {
                    “qualification_code”: 212,
            		"range_sets":[{"from":13,"to":18,“units”:“311”}]
       			 }
            ],
            "quantities":{
           		"currently_open":100,
                "remaining":100,
                "achieved":0
            },
            "crtd_on":124411231313,
            "mod_on":11321334733
        },
		//example quota showing temporary exclusion - currently_open=0, remaining=0, achieved=0
		{
            "quota_id": "123",
            "criteria":[{
                    “qualification_code”: 211,
            		"condition_codes":["111"]
       			 },
				 {
                    “qualification_code”: 212,
            		"range_sets":[{"from":13,"to":18,“units”:“311”}]
       			 }
            ],
            "quantities":{
            	"currently_open":0,
                "remaining": 0,
                "achieved":0
            },
            "crtd_on":124411231313,
            "mod_on":11321334733
        }
    ],
	"crtd_on":124411231313,
	"mod_on":11321334733
	}


	//example locked quota
	{
            "quota_id": "123",
            "criteria":[{
                    “qualification_code”: 211,
            		"condition_codes":["111"]
       			 },
				 {
                    “qualification_code”: 212,
            		"range_sets":[{"from":13,"to":18,“units”:“311”}]
       			 }
            ],
            "quantities":{
           		"currently_open":0,
                "remaining": 100,
                "achieved":0
            },
            "crtd_on":124411231313,
            "mod_on":11321334733
        }
    ],
	"crtd_on":124411231313,
	"mod_on":11321334733
	}


//unusual quotas
        //example quota with multiple age range
		{
            "quota_id": "123",
            "criteria":[{
                    “qualification_code”: 212,
            		"range_sets":[{"from":13,"to":18,“units”:“311”},{"from":45,"to":54,“units”:“311”}]
       			 }
            ],
            "quantities":{
                "currently_open":100,
                "remaining":100,
                "achieved":0
            },
            "crtd_on":124411231313,
            "mod_on":11321334733
        }

]

Advanced Targeting Example with Movie Theater Frequency Question

 "qualifications": [{
        "qualification_code":1021, //looking for movie goers
        "range_sets":[{
				"from":6,"to":99, //seen more than 6 movies in theaters, in the last 90 days
				"period":90 //always in days
        }
	]


//nested quotas example
		{
            "quota_id": "123",  //looking for movie goers that have seen more than 6 movies in the last 90 days, and are 18-24 years old.
            "criteria":[{
                    "qualification_code":1021, //looking for movie goers
        			"range_sets":[{
						"from":6,"to":99, //seen more than 6 movies in theaters, in the last 90 days
						"period":90 //always in days
       			 },
				 {
                    “qualification_code”: 212,
            		"range_sets":[{"from":18,"to":24,“units”:“311”}]
       			 }
            ],
            "quantities":{
           		"currently_open":100,
                "remaining":100,
                "achieved":0
            },
            "crtd_on":124411231313,
            "mod_on":11321334733
        }

  • No labels