Get Attributes By Qualification Code

GET /attributes - https://api.spectrumsurveys.com/suppliers/v2/attributes/:qualification_code?format=true&localization=:localization

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.

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

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

Parameter

Type

Required

Description

access-token

string

Yes

Token used to identify the authenticity of the user.



Query String Parameters

Parameter

Type

Required

Description

Parameter

Type

Required

Description

localization

string

Yes

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

format

bool

Yes

Boolean field, set to true. This flag was previously used for compatibility, failure to include will exclude qualifications.



Response Parameters    

Parameter

Type

Description

Nullable

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)





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/1031?survey_localization=en_US&format=true Host: api.spectrumsurveys.com access-token: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx



Sample API Response

Example 1: Simple MultiPunch

GET /suppliers/v2/attributes/1031?survey_localization=en_US&format=true { "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

Qualification code doesn't exist in database

5xx

Internal Server Error

Please Report to support@purespectrum.com

Error Messages

Response

Description

Response

Description

1001

Missing localization parameter

1002

Qualification doesn't exist in localization code

1003

Invalid Localization code

9999

Unknown Error - Please Report to support@purespectrum.com