Get Attributes By Mod On Date

Get Surveys - GET /attributes - https://api.spectrumsurveys.com/suppliers/v2/attributes?format=true&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.

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

Make sure that you are including the parameter format=true in all requests

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.

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

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

Query String Parameters

Parameter	Required	Description

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
format	Yes	Boolean field, set to true. This flag was previously used for compatibility, failure to include will exclude qualifications.

Response Header Parameters

Parameter	Description

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

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?survey_localization=en_US&mod_on_start=20170729&page=3&class=2&format=true
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&format=true
{
    "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

Example 3: Singlepunch - alt

HTTP Response Codes

Response	Status	Description

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

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