Quotas & Qualifications V2

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.

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:

Qualification	Qualification Code	Conditions	Conditions Code	USeng	CAeng	CAeng Label	CAeng Sort Order
gender	211			y	y	Gender
		Male	111	y	y	Male	1
		Female	112	y	y	Female	2
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
Children	218			y	y
		No Children	111	y	y	No Children	1
		Have Children	112	y	y	Have Children	2
device	219			y	y
		Desktop	111	y	y	Desktop	1
		Mobile	112	y	y	Mobile	2
		Tablet	113	y	y	Tablet	3
Kids Gender	220			y	y
		Boy	111	y	y	Boy	1
		Girl	112	y	y	Girl	2
Kids Age	230	(This in conjunction with Kids Age Unit indicates the age of the kid)		y
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		y
Canadian postalcode FSA	232	Uses only the first 3 of the respondents postal code			n
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

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,
    "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”:“111”}]
       			 }
            ],
            "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”:“111”}]
       			 }
            ],
            "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”:“111”}]
       			 }
            ],
            "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”:“111”},{"from":45,"to":54,“units”:“111”}]
       			 }
            ],
            "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”:“111”}]
       			 }
            ],
            "quantities":{
           		"currently_open":100,
                "remaining":100,
                "achieved":0
            },
            "crtd_on":124411231313,
            "mod_on":11321334733
        }