Get Attributes By Qualification Code

GET /attributes - https://api.spectrumsurveys.com/suppliers/v2/attributes/:qualification_code?format=true&localization=:localization

Call this API to view the respondent's question text, condition codes, and condition code texts for unfamiliar qualification codes/condition codes. Survey_localization is a required Query String parameter.

You should only use the response from the production environment when using this API to map. Qualifications may be different in staging.

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, this API endpoint is for you. The goal of this endpoint is not for mapping, but rather for direct creation of question/answers within your profiling mechanism.

When importing a new survey, qualification, or quota into your survey inventory via API - take into consideration if any of the qualifications or the qualification's condition codes are unknown within your system. If so, fail the survey import and call the GET /attributes endpoint with the qualification and survey localization. Parse the response and create this new qualification within your system.

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

HEADER Parameters

Parameter	Type	Required	Description

Parameter	Type	Required	Description
access-token	string	Yes	Token used to identify the authenticity of the user.

Query String Parameters

Parameter	Type	Required	Description

Parameter	Type	Required	Description
localization	string	Yes	Define the Country & Language combination for which you need the attribute's question/answer text returned
format	bool	Yes	Boolean field, set to true. This flag was previously used for compatibility, failure to include will exclude qualifications.

Response Parameters

Parameter	Type	Description	Nullable

Parameter	Type	Description
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

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/1031?survey_localization=en_US&format=true
Host: api.spectrumsurveys.com
access-token: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Sample API Response

Example 1: Simple MultiPunch

GET /suppliers/v2/attributes/1031?survey_localization=en_US&format=true
{
  "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

Example 3: Singlepunch - alt

HTTP Response Codes

Response	Status	Description

Response	Status	Description
200	OK
400	Bad Request	See Error Messages
404	Not Found	Qualification code doesn't exist in database
5xx	Internal Server Error	Please Report to support@purespectrum.com

Error Messages

Response	Description

Response	Description
1001	Missing localization parameter
1002	Qualification doesn't exist in localization code
1003	Invalid Localization code
9999	Unknown Error - Please Report to support@purespectrum.com