Get Surveys - GET /attributes - https://api.spectrumsurveys.com/suppliers/v2/attributes?localization=:localization&mod_on_start=:YYYYMMDD&class=:class
Call this API to view all qualifications that were created or modified since a specified date. Survey_localization is a required Query String parameter. mod_on_start & class are optional parameters. Data is paginated if there are more than 50 items.
Now available on Production - you should only use the response from the production environment when using this API to map.
Implementation
As the PureSpectrum platform continues to expand its Respondent targeting library, it is important that you are able to import foreign targeting attributes & profile your respondents before sending them into a survey. Your ability to do so will greatly improve conversion, reduce time to termination, and provide you with better population data about your supply.
If your system supports the ability to route or screen respondents on the fly on qualifications for which you are missing for this respondent, you should use the endpoint Get Attributes By Qualification Code. If you would prefer to periodically import new/updated profiling targets, then it would make more sense to use this one.
As custom qualification criteria is created on the fly and used usually just once, you may not realize much benefit from this specific endpoint.
You may also consider using this to download a list of questions by class that you can use to map, for example questions in class=1(Core) or class=2(Extended)
Considerations
- Qualifications are shared across surveyLocalizations on PureSpectrum. For example, we use the same code for b2b employment in the US/English, that we use in Japanese Japan.
- Condition codes when appropriate are also shared across localizations
- Even though the codes may be the same, we represent these questions/answers using the appropriate language/localization
- We only currently support 3 question types in this api call: Singlepunch, Singlepunch-alt, & Multipunch.
- singlepunch is presented as a dropdown. Singlepunch-alt and Multipunch are shown in push-button form
Request Header Parameters
Parameter | Type | Required | Description |
---|---|---|---|
access-token | string | Yes | Token used to identify the authenticity of the user |
Query String Parameters
Parameter | Required | Description |
---|---|---|
localization | Yes | Define the Country & Language combination for which you need the attribute's question/answer text returned |
class | No | Will return targeting attributes that correspond to the defined class. 1=core, 2=extended, 3=custom. It won't make much sense to use class=3. |
mod_on_start | No | Will return attributes that have been created or modified after the specified date. Very useful if running a nightly cron to check for updates |
page | No | Required in case of pagination. The endpoint will return a max of 25 entries per page |
Response Header Parameters
Parameter | Description |
---|---|
total_count | Total number of objects returned in the API response |
total_pages | Number of pages in the response |
date | The UTC timestamp at which call was made |
Response Parameters
Parameter | Type | Description | Nullable |
---|---|---|---|
text | string | The text of the question asked to the respondent | |
desc | string | A description of the question that is asked of the respondent | |
cat | string | Category name of the question that is asked of the respondent | |
type | integer | 1=singlepunch (only one selection is allowed, presented in dropdown form) 2=singlepunch-alt (only one selection is allowed - presented in push button form) 3=multipunch (multiple selections are allowed, presented in push button form) 4=range (not currently supported) | |
class | integer | 1 = Core profiling question 2 = Extended profiling question 3 = Custom profiling question | |
condition_codes | array | contains the condition codes and condition code texts | |
crtd_on | UTC Timestamp in milliseconds since Unix Epoch | Timestamp of when this attribute was created | |
mod_on | UTC Timestamp in milliseconds since Unix Epoch | Timestamp of when this attribute was modified. This may include a change in text, addition or modification of condition codes. In case the mod_on has changed since your last sync, delete the qualification in your system and recreate it to prevent inconsistencies. |
condition_codes Array
Parameter | Type | Description | Nullable |
---|---|---|---|
id | string | the condition code of the corresponding text. This will match the requisite condition codes in a survey's qualifications/quotas | |
text | string | The text of the answer presented to the respondent |
Sample API Request
GET /suppliers/v2/attributes?survey_localization=en_US&mod_on_start=20170729&page=3&class=2 Host: api.spectrumsurveys.com access-token: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Sample API Response (Pending Update)
Example 1: Simple MultiPunch
GET /suppliers/v2/attributes/1031?survey_localization=en_US { "apiStatus": "success", "msg": "Attributes fetched successfully for Qualification code", "version": "2.0", "qual_attributes": [ { "text":"Which of the following pets do you own?", "cat":"Pets", "desc":"Pet Ownership", "type":3, "class":2, "condition_codes":[ {"id":"111","text":"Dog"}, {"id":"112","text":"Cat"}, {"id":"113","text":"Rabbit"}, {"id":"114","text":"Snake/Lizard"}, {"id":"115","text":"Fish"}, {"id":"116","text":"Small Birds"}, {"id":"117","text":"Large Birds"}, {"id":"118","text":"Horse/Equine"}, {"id":"119","text":"Ferrets"}, {"id":"120","text":"Hamster or other Rodent"}, {"id":"121","text":"Turtle"}, {"id":"122","text":"Exotic Pets"}, {"id":"999","text":"None of the Above"} ], "crtd_on": 1487871678958, "mod_on": 1487871678958 } ] }
Example 2: Singlepunch - in context dropdown. This will render as The company I work for employs approximately (dropdown) people
GET /suppliers/v2/attributes/1034?survey_localization=en_US { "apiStatus": "success", "msg": "Attributes fetched successfully for Qualification code", "version": "2.0", "qual_attributes": [ { "text":"The company I work for employs approximately %1034% people", "cat":"B2B", "desc":"Company Size (Employees)", "type":1, "class":2, "condition_codes":[ {"id":"111","text":"1 to 5"}, {"id":"112","text":"6 to 9"}, {"id":"113","text":"10 to 19"}, {"id":"114","text":"20 to 24"}, ... {"id":"125","text":"50,000+"}, {"id":"999","text":"Don't know"} ], "crtd_on": 1487871678958, "mod_on": 1487871678958 } ] }
Example 3: Singlepunch - alt
GET /suppliers/v2/attributes/1040?survey_localization=en_US { "apiStatus": "success", "msg": "Attributes fetched successfully for Qualification code", "version": "2.0", "qual_attributes": [ { "text":"Are you registered in any of the following US political parties?", "cat":"Politics", "desc":"Political Party Affiliation", "type":1, "class":2, "condition_codes":[ {"id":"111","text":"Democratic Party"}, {"id":"112","text":"Republican Party"}, {"id":"113","text":"Independent"}, {"id":"114","text":"Constitution Party"}, ... {"id":"117","text":"Other"}, {"id":"118","text":"I am not registered with a political party"} ], "crtd_on": 1487871678958, "mod_on": 1487871678958 } ] }
HTTP Response Codes
Response | Status | Description |
---|---|---|
200 | OK | |
400 | Bad Request | See Error Messages |
404 | Not Found | Questions not found |
5xx | Internal Server Error | Please Report to support@purespectrum.com |
Error Messages
Response | Description |
---|---|
1001 | Missing localization parameter |
1002 | No results match your search |
1003 | Invalid date |
1004 | Invalid page number |
1005 | Invalid Class |
9999 | Unknown Error - Please Report to support@purespectrum.com |