Create Attributes

Get Surveys - POST /attributes - http://api.spectrumsurveys.com/buyers/v1/attributes

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.

Not yet available, api specs subject to change

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
access-token	string	Yes	Token used to identify the authenticity of the user.

Query String Parameters

Parameter	Type	Required	Description
localization	string	Yes	Define the Country & Language combination for which you need the attribute's question/answer text returned

Response Parameters

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
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
Host: api.spectrumsurveys.com
access-token: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Sample API Response

Example 1: The attribute API POST request

POST /buyers/v1/attributes/
{
   "buyer_attribute_id":"ABC123",
   "desc":"Pet Food Preferences",
   "category":"Pets",
   "type":1,  //singlepunch
   "localizations":[
   {
       "localization" : "en_US",
       "text": "Do you purchase dry or wet Dog Food?"
       "answers":[
             {
                "buyer_answer_id" : "DEF456-1",
                "text" : "Dry Food"
             },
             {
                 "buyer_answer_id" : "DEF456-2",
                 "text" : "Wet Food"
             },
			 {
                 "buyer_answer_id" : "DEF456-99",
                 "text" : "Not Sure/Doesn't Apply"
             }
        ]
   },
   {
       "localization" : "en_CA",
       "text": "Do you purchase dry or wet Dog Food?"
       "answers":[
             {
                "buyer_answer_id" : "DEF456-1",
                "text" : "Dry Food"
             },
             {
                 "buyer_answer_id" : "DEF456-2",
                 "text" : "Wet Food"
             },
			 {
                 "buyer_answer_id" : "DEF456-99",
                 "text" : "Not Sure/Doesn't Apply"
             }
        ]
   }
}

Example 2 : The attribute API Response

GET /buyers/v1/attributes/
{
   "ps_qualification_code" : 1110
   "buyer_attribute_id" : "ABC123",
   "desc" : "Pet Food Preferences",
   "Category" : "Pets",
   "type":1,
   "localizations":[
   {
       "localization" : "en_US",
       "text": "Do you purchase dry or wet Dog Food?"
       "answers":[
             {
                "buyer_answer_id" : "DEF456-1",
				"ps_cond_code":"111"
                "text" : "Dry Food"
             },
             {
                 "buyer_answer_id" : "DEF456-2",
                 "ps_cond_code":"112"
                 "text" : "Wet Food"
             },
			 {
                 "buyer_answer_id" : "DEF456-99",
                 "ps_cond_code":"113"
                 "text" : "Not Sure/Doesn't Apply"
             }
        ]
   },
   {
       "localization" : "en_CA",
       "text": "Do you purchase dry or wet Dog Food?"
       "answers":[
             {
                "buyer_answer_id" : "DEF456-1",
                "ps_cond_code":"111"
                "text" : "Dry Food"
             },
             {
                 "buyer_answer_id" : "DEF456-2",
                 "ps_cond_code":"112"
                 "text" : "Wet Food"
             },
			 {
                 "buyer_answer_id" : "DEF456-99",
                 "ps_cond_code":"113"
                 "text" : "Not Sure/Doesn't Apply"
             }
        ]
   }

  ]
}

HTTP Response Codes

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
1001	Missing localization parameter.
1002	Resp_ID is missing in the Question text.
1003	Category is Invalid. Please check the documentation.
1004	Type can only take values of 1, 2 or 3.
1005	Survey Localization is Invalid.
1006	Buyer attribute ID is already used. Please use a new one. Use PUT to edit the attributes.
1007	Invalid Survey Localization code.
1008	Invalid JSON. Please check your request format.
9999	Unknown Error - Please Report to support@purespectrum.com