Page Comparison

...

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

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

...

Access to creating attributes is limited to select Buyers where this feature needs to be enabled and access is granted to specific users within that organization. Contact your Account Manager for more details on getting access.

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

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

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

• Make sure your account and API users are given the access required to create attributes.

• 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

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	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)

classinteger

1 = Core profiling question

2 = Extended profiling question

3 = Custom profiling question

condition_codesarray

contains the condition codes and condition code texts

crtd_onUTC Timestamp in milliseconds since Unix EpochTimestamp of when this attribute was createdmod_onUTC Timestamp in milliseconds since Unix EpochTimestamp 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.

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

Sample Buy API Request

GETPOST /suppliersbuyers/v2v1/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

{
   "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",
   "Descdesc" : "Pet Food Preferences",
   "Category" : "Pets",
   "Typetype":1,
   "tags":"tag1,tag2",
   "localizations":[
   {
       "localization" : "en_usUS",
       "Q_text": "Do you purchase dry or wet Dog Food?%%respID%%"
       "answers":[
             {
                "Buyerbuyer_Answeranswer_IDid" : "DEF456-1",
				"ps_cond_code":"111"
                "Answer_Texttext" : "Dry Food"
             },
             {
                 "buyer_answer_id" : "DEF456-2",
                 "ps_cond_code":"112"
                 "text" : "Wet Food"
             },
			 {
                 "Buyerbuyer_Answeranswer_IDid" : "DEF457DEF456-99",
                 "Answer_Textps_cond_code":"113"
                 "text" : "WetFoodNot Sure/Doesn't Apply"
             }....
        ]

   },
 }  {
   

Example 2 : The attribute API Response

GET /buyers/v1/attributes/  { "localization" : "Qen_IDCA",
: 1110      "localizationstext":[ "Do you purchase dry or {wet Dog Food?%%respID%%"
       "answers":[
             {
                " buyer_Answeranswer_IDid" : "DEF456-1",
                "PSps_C_IDcond_code":"111"
                "text" : 111"Dry Food"
             },
             {
                 " buyer_Answeranswer_IDid" : "DEF456-2",
                 " PS_C_ID" : 111ps_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 /suppliersbuyers/v2v1/attributes/1040?survey_localization=en_USABC123
Host: api.spectrumsurveys.com
access-token: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

{
   "textps_qualification_code" :"Are you registered in any of the following US political parties? 1110
   "buyer_attribute_id" : "ABC123",
   "desc" : "Pet Food Preferences",
   "catCategory" : "PoliticsPets",
   "desctype":"Political Party Affiliation",1,
   "localizations":[
   {
       "localization" : "en_US",
       "type":1,text": "Do you purchase dry or wet Dog Food?%%respID%%"
       "class":2,answers":[
             {
                "conditionbuyer_answer_codesid":[
	{"id : "DEF456-1",
				"ps_cond_code":"111",
                "text" : "DemocraticDry Party"Food"
             },
	{"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
}
             {
                 "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"
             }
        ]
   }
  ]
}

HTTP Response Codes

Error Messages for GET call

Error Messages for POST call