Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

Code Block
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.

Now available on Production - you
Warning
Note

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

Note

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.

Warning

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

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

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

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

Timestamp in milliseconds since Unix Epoch

Timestamp of when this attribute was created


mod_on

UTC

Timestamp

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

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

Code Block
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

Code Block
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

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

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


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

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