Create Attributes

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

GET /attributes - http://api.spectrumsurveys.com/buyers/v1/attributes/:buyer_attribute_id

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.

Implementation

For trusted enterprise buyers that choose to integrate into the PureSpectrum Buy API - we offer the ability to create custom targeting attributes, based on your targeting library. Before creating survey, qualification, or quota that will require custom targeting, your integration should call this API to create a new qualification within the PureSpectrum library. We will return a qualification id that corresponds to your new attribute, as well as condition id's that correspond to you answer id's. Once you map these values internally, you may then create a survey with these new targets!

Some suppliers are able to dynamically consume, store, and screen respondents using a supply API endpoint. Creating good targeting questions will increase conversion & the overall respondent experience.

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
A condition code may have different text across different 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.

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)
tags	string	Comma separated list of tags that are searchable via Question Library UI	if no tags are present, api will returned “tags”:undefined
localizations	enum	Contains the question text and their respective answer text and ID's
localization	string	Lists the type of language code the answer needs to be in
respID	string	This needs to be included in the text and acts as a container for answers block
answers	array	Its acts a container for range of "buyer_answer_id's" and corresponding "answer_text's"
buyer_answer_id	string	It is the "answer_id" to the question raised by buyer
answer_test	string	It is the "answer_text" to the question raised by buyer
condition_codes	array	Contains the condition codes and condition code texts

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 Buy API Request

POST /buyers/v1/attributes/
Host: api.spectrumsurveys.com
access-token: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

{
   "buyer_attribute_id":"ABC123",
   "desc":"Pet Food Preferences",
   "category":"Pets",
   "type":1,  //singlepunch
   "tags":"tag1,tag2",
   "localizations":[
   {
       "localization" : "en_US",
       "text": "Do you purchase dry or wet Dog Food?%%respID%%"
       "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?%%respID%%"
       "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"
             }
        ]
   }
}

Sample API Response

{
   "ps_qualification_code" : 1110
   "buyer_attribute_id" : "ABC123",
   "desc" : "Pet Food Preferences",
   "Category" : "Pets",
   "type":1,
   "tags":"tag1,tag2",
   "localizations":[
   {
       "localization" : "en_US",
       "text": "Do you purchase dry or wet Dog Food?%%respID%%"
       "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?%%respID%%"
       "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"
             }
        ]
   }

  ]
}

Example 2 : The GET Request/Response

GET /buyers/v1/attributes/ABC123
Host: api.spectrumsurveys.com
access-token: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

{
   "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?%%respID%%"
       "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?%%respID%%"
       "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"
             }
        ]
   }
  ]
}

In the GET /attributes/:buyer_attribute_id - You may append the query string parameter: survey_localization=[%%survey_localization%%] in order to limit the result of the GET request to your desired localization

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 for GET call

Response	Description
1001	Invalid buyer attribute id.
1003	Localization doesn't exist for this question.
9999	Unknown Error - Please Report to support@purespectrum.com

Error Messages for POST call

Response	Description
1001	Invalid buyer attribute id.
1002	Resp_ID is missing in the Question text.
1003	Localization doesn't exist for this question.
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.
1009	Description is already used. Please use a new one.
9999	Unknown Error - Please Report to support@purespectrum.com