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: https://purespectrum.atlassian.net/wiki/spaces/PA/pages/1717895181
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. |
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
Core Profile Points:
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:
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