Skip to end of metadata
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 13 Next »

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

Now available on Production - you should only use the response from the production environment when using this API to map.


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.


As custom qualification criteria is created on the fly and used usually just once, you may not realize much benefit from this specific endpoint.  



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

access-token

string

Yes

Token used to identify the authenticity of the user


Query String Parameters


Parameter

Required

Description

localization

Yes

Define the Country & Language combination for which you need the attribute's question/answer text returned

classNoWill 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_startNoWill return attributes that have been created or modified after the specified date. Very useful if running a nightly cron to check for updates
pageNoRequired in case of pagination. The endpoint will return a max of 25 entries per page


Response Header Parameters


Parameter

Description

total_count

Total number of objects returned in the API response

total_pages

Number of pages in the response

dateThe UTC timestamp at which call was made


Response Parameters    


Parameter

Type

Description

Nullable

text

string

The text of the question asked to the respondent


descstringA description of the question that is asked of the respondent
catstringCategory 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 created
mod_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.

condition_codes Array

ParameterTypeDescriptionNullable
idstring

the condition code of the corresponding text. This will match the requisite condition codes in a survey's qualifications/quotas


textstringThe 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
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
{
    "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

GET /suppliers/v2/attributes/1034?survey_localization=en_US
{
    "apiStatus": "success",
    "msg": "Attributes fetched successfully for Qualification code",
    "version": "2.0",
	"qual_attributes": [
      {
         "text":"The company I work for employs approximately %1034% people",
         "cat":"B2B",
         "desc":"Company Size (Employees)",
         "type":1,
         "class":2,
         "condition_codes":[
        	{"id":"111","text":"1 to 5"},
	        {"id":"112","text":"6 to 9"},
	        {"id":"113","text":"10 to 19"},
	        {"id":"114","text":"20 to 24"},
	        ...
	        {"id":"125","text":"50,000+"},
	        {"id":"999","text":"Don't know"}
         ], 
         "crtd_on": 1487871678958,
         "mod_on": 1487871678958
      }
     ]
}

Example 3: Singlepunch - alt

GET /suppliers/v2/attributes/1040?survey_localization=en_US
{
    "apiStatus": "success",
    "msg": "Attributes fetched successfully for Qualification code",
    "version": "2.0",
	"qual_attributes": [
	 {
       "text":"Are you registered in any of the following US political parties?",
       "cat":"Politics",
       "desc":"Political Party Affiliation",
       "type":1,
       "class":2,
       "condition_codes":[
	      {"id":"111","text":"Democratic Party"},
	      {"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
     }
    ]
}

HTTP Response Codes


Response

Status

Description

200

OK


400Bad RequestSee Error Messages
404Not FoundQuestions not found

5xx

Internal Server Error

Please Report to support@purespectrum.com

Error Messages


Response

Description

1001

Missing localization parameter

1002No results match your search
1003Invalid date
1004Invalid page number
1005Invalid Class

9999

Unknown Error - Please Report to support@purespectrum.com

  • No labels