...
Context:
Buyers can now select the template via API. The Template API allows a buyer to create a survey based on a template without specifying other settings. Buyers can use the API and add the template ID to use during the survey creation.
Functional:
Allow buyers to use a template via API
Buyers need only to specify the ID of the template
Buyers can check the list of template-id via API
The API returns
Title
Template ID
Template name
Folder name
Any template survey created via API template can be managed via UI.
Any survey created via API template will have the template selected.
Note:
Buyer account must have the template feature activated
Buyers can use only the accessible templates
Own templates: Created by the buyer
Default templates: Created by PS Product team and accessible to any buyer
Shared templates: Created by PS Support and accessible to a specific buyer
Buyers can select only one template.
API Specification:
GET templates API for API users:
| Code Block |
|---|
GET <SERVER_BASE_URL>/buyers/v2/templates?UI=0 |
Response:
| Code Block |
|---|
[
{
"folder": "CA-en",
"templates": [
{
"id": 26,
"name": "Province qual",
"title": "Template - Non US countries"
}
]
},
{
"folder": "Austria-German",
"templates": [
{
"id": 30,
"name": "Age, Education, Postal codes",
"title": "Austria - German"
}
]
}
]
|
GET templates API for UI users:
| Code Block |
|---|
GET <SERVER_BASE_URL>/buyers/v2/templates?UI=1 |
Response:
| Code Block |
|---|
[
{
"folder": "CA-en",
"templates": [
{
"id": 26,
"name": "Province qual",
"title": "Template - Non US countries",
"owner": 145,
"shared_with": [
145
],
"isOwner": true,
"is_service_buyer": false
}
]
},
{
"folder": "Austria-German",
"templates": [
{
"id": 30,
"name": "Age, Education, Postal codes",
"title": "Austria - German",
"owner": 145,
"shared_with": [
145
],
"isOwner": true,
"is_service_buyer": false
}
]
}
]
|
POST survey API - When in payload buyer passes a template-id, but the template feature is not enabled for him:
| Code Block |
|---|
POST - <SERVER_BASE_URL>/buyers/v2/surveys |
Request:
| Code Block |
|---|
{
"survey_title": "Some survey check - FOLDER 4 ",
"click_balancing": 0,
"estimated_clicks": 0,
"survey_category_code": 232,
"survey_localization": "en_US",
"completes_required": 20,
"expected_ir": 50,
"expected_loi": 5,
"field_time": 23,
"source": "platform",
"buyer_user_id": 51,
"buyer_company": 145,
"template_id": 100,
"qualifications": [
{
"qualification_name": "Gender",
"qualification_code": 211,
"condition_codes": [
"111"
],
"condition_names": [
{
"111": "Male"
}
]
},
{
"qualification_name": "Age",
"qualification_code": 212,
"range_sets": [
{
"from": 18,
"to": 99,
"units": 311
}
]
}
],
"quotas": [
{
"buyer_quota_id": "6FLMpfWu9rzNmW9",
"required_count": 10,
"flexible": {
"enable": true,
"value": 0
},
"criteria": [
{
"qualification_name": "Gender",
"qualification_code": 211,
"condition_codes": [
"111"
],
"condition_names": [
"Male"
]
}
],
"percentage": 100,
"maximum": 10,
"minimum": 10,
"quota_category": "layered",
"current_target": 10
}
]
}
|
Response - 403 Forbidden:
| Code Block |
|---|
{
"ps_api_response_code": 1018,
"ps_api_response_message": "You do not have the template feature activated. Please ask your PureSpectrum reference to activate it in order to use a template in a survey."
}
|
POST survey API - When in payload buyer passes a template he does not have access to.
| Code Block |
|---|
POST - <SERVER_BASE_URL>/buyers/v2/surveys |
Request:
| Code Block |
|---|
{
"survey_title": "Some survey check - FOLDER 4 ",
"click_balancing": 0,
"estimated_clicks": 0,
"survey_category_code": 232,
"survey_localization": "en_US",
"completes_required": 20,
"expected_ir": 50,
"expected_loi": 5,
"field_time": 23,
"source": "platform",
"buyer_user_id": 51,
"buyer_company": 145,
"template_id": 100,
"qualifications": [
{
"qualification_name": "Gender",
"qualification_code": 211,
"condition_codes": [
"111"
],
"condition_names": [
{
"111": "Male"
}
]
},
{
"qualification_name": "Age",
"qualification_code": 212,
"range_sets": [
{
"from": 18,
"to": 99,
"units": 311
}
]
}
],
"quotas": [
{
"buyer_quota_id": "6FLMpfWu9rzNmW9",
"required_count": 10,
"flexible": {
"enable": true,
"value": 0
},
"criteria": [
{
"qualification_name": "Gender",
"qualification_code": 211,
"condition_codes": [
"111"
],
"condition_names": [
"Male"
]
}
],
"percentage": 100,
"maximum": 10,
"minimum": 10,
"quota_category": "layered",
"current_target": 10
}
]
}
|
Response - 404 Not Found:
| Code Block |
|---|
{
"ps_api_response_code": 1006,
"ps_api_response_message": "Template Id does not exist. Please try a different Template id again."
}
|
POST survey API - When the buyer passes the correct template Id in the payload
| Code Block |
|---|
POST <SERVER_BASE_URL>/buyers/v2/surveys |
Request:
| Code Block |
|---|
{
"survey_title": "Some survey check - FOLDER 4 ",
"click_balancing": 0,
"estimated_clicks": 0,
"survey_category_code": 232,
"survey_localization": "en_US",
"completes_required": 20,
"expected_ir": 50,
"expected_loi": 5,
"field_time": 23,
"source": "platform",
"buyer_user_id": 51,
"buyer_company": 145,
"template_id": 15,
"qualifications": [
{
"qualification_name": "Gender",
"qualification_code": 211,
"condition_codes": [
"111"
],
"condition_names": [
{
"111": "Male"
}
]
},
{
"qualification_name": "Age",
"qualification_code": 212,
"range_sets": [
{
"from": 18,
"to": 99,
"units": 311
}
]
}
],
"quotas": [
{
"buyer_quota_id": "6FLMpfWu9rzNmW9",
"required_count": 10,
"flexible": {
"enable": true,
"value": 0
},
"criteria": [
{
"qualification_name": "Gender",
"qualification_code": 211,
"condition_codes": [
"111"
],
"condition_names": [
"Male"
]
}
],
"percentage": 100,
"maximum": 10,
"minimum": 10,
"quota_category": "layered",
"current_target": 10
}
]
}
|
Response:
| Code Block |
|---|
{
"qbp": {
"enable": false
},
"qlc": {
"enable": false,
"multiple_quotas": {
"enable": false,
"count_by_quota": false,
"compensate_by_quota": false
}
},
"soft_launch": {
"enable": false
},
"unique_links": {
"enable": false
},
"click_balancing": 0,
"estimated_clicks": 0,
"survey_external_id": "",
"ps_survey_status": 11,
"offer_price": null,
"incl_excl": 0,
"quota_throttling": false,
"url_transform": false,
"subscriber_emails": [],
"survey_title": "Some survey check - FOLDER 4 ",
"survey_category_code": 232,
"completes_required": 20,
"field_time": 23,
"buyer_message": null,
"live_url": null,
"billing_id": null,
"test_url": null,
"expected_loi": 5,
"expected_ir": 50,
"ps_survey_id": 7224,
"buyer_surveygroup_ref": null,
"buyer_surveygroup_refs": [],
"test_ps_survey_entry_link": "<SERVER_BASE_URL>/#/start-survey?survey_id=7224&ps_redirect_test=1&bsec=a70mx8&supplier_id=23",
"survey_localization": "en_US",
"uniqueLinks": false,
"quotas": [
{
"buyer_quota_id": "6FLMpfWu9rzNmW9",
"quota_title": "",
"ps_quota_id": "24e108ba-52a2-4cb4-b0de-bfc2ce3d5e0d",
"required_count": 10,
"criteria": [
{
"qualification_code": 211,
"condition_codes": [
"111"
]
}
]
},
{
"buyer_quota_id": "Fb59GnI9McQiChv",
"quota_title": "",
"ps_quota_id": "f449cda3-9057-4a85-b644-e76e98925e6f",
"required_count": 3,
"criteria": [
{
"qualification_code": 212,
"range_sets": [
{
"units": 311,
"to": 24,
"from": 18
}
]
}
]
},
{
"buyer_quota_id": "ktqHNWN4iaHaXb0",
"quota_title": "",
"ps_quota_id": "25063b45-cbd1-41c7-8e65-b20a38735ef0",
"required_count": 4,
"criteria": [
{
"qualification_code": 212,
"range_sets": [
{
"units": 311,
"to": 34,
"from": 25
}
]
}
]
},
{
"buyer_quota_id": "9B8CMbUtjFk2bcF",
"quota_title": "",
"ps_quota_id": "5a95cc5b-113d-4960-b7fe-33b1a04aab13",
"required_count": 4,
"criteria": [
{
"qualification_code": 212,
"range_sets": [
{
"units": 311,
"to": 44,
"from": 35
}
]
}
]
},
{
"buyer_quota_id": "8B6zGN8nZEbZw0h",
"quota_title": "",
"ps_quota_id": "56b866e7-f393-49b8-b8f5-46e5f4d3a641",
"required_count": 4,
"criteria": [
{
"qualification_code": 212,
"range_sets": [
{
"units": 311,
"to": 54,
"from": 45
}
]
}
]
},
{
"buyer_quota_id": "i0CTmg5JSOhdbQm",
"quota_title": "",
"ps_quota_id": "4dbc815d-c2b0-477e-9235-bc6b8d2f1af0",
"required_count": 2,
"criteria": [
{
"qualification_code": 212,
"range_sets": [
{
"units": 311,
"to": 64,
"from": 55
}
]
}
]
},
{
"buyer_quota_id": "nc72SEKeiQzLrmd",
"quota_title": "",
"ps_quota_id": "c51b4d66-26ae-4e3e-b9ea-e63ad8e1b530",
"required_count": 3,
"criteria": [
{
"qualification_code": 212,
"range_sets": [
{
"units": 311,
"to": 99,
"from": 65
}
]
}
]
},
{
"buyer_quota_id": "j9ngS035dctudCj",
"quota_title": "",
"ps_quota_id": "e6370044-d937-4550-8507-0fdd38c41857",
"required_count": 10,
"criteria": [
{
"qualification_code": 215,
"condition_codes": [
"115"
]
}
]
},
{
"buyer_quota_id": "tSXFolsOZNJLL0D",
"quota_title": "",
"ps_quota_id": "f5902189-d91b-4c40-908a-dd1e0d58ec83",
"required_count": 2,
"criteria": [
{
"qualification_code": 215,
"condition_codes": [
"112"
]
}
]
},
{
"buyer_quota_id": "tN68egepVpRMw3c",
"quota_title": "",
"ps_quota_id": "018d5869-51a5-4e05-aeb3-c7acf900adf2",
"required_count": 8,
"criteria": [
{
"qualification_code": 215,
"condition_codes": [
"114",
"113",
"111"
]
}
]
},
{
"buyer_quota_id": "ezMmiczGeC3EaoE",
"quota_title": "",
"ps_quota_id": "42199aa0-b8e6-476f-aa6f-89db722489ec",
"required_count": 8,
"criteria": [
{
"qualification_code": 229,
"condition_codes": [
"91945",
"91950"
]
}
]
},
{
"buyer_quota_id": "FTiTvZ9yTAIqlN1",
"quota_title": "",
"ps_quota_id": "32963ec6-56f3-4645-92d8-cf3d3c7f1e02",
"required_count": 12,
"criteria": [
{
"qualification_code": 229,
"condition_codes": [
"91977",
"91978"
]
}
]
}
],
"qualifications": [
{
"condition_codes": [
"111"
],
"qualification_code": 211
},
{
"range_sets": [
{
"units": 311,
"to": 99,
"from": 18
}
],
"qualification_code": 212
},
{
"condition_codes": [
"114",
"113",
"115",
"112",
"111"
],
"qualification_code": 215
},
{
"condition_codes": [
"91945",
"91950",
"91977",
"91978"
],
"qualification_code": 229
}
],
"is_feot_enabled": false,
"survey_grouping": [],
"blend_id": "sb29b41342ac",
"schedule_launch": {
"enable": false,
"info": {
"date": null,
"hours": null,
"minutes": null,
"timezone": null,
"dateTimeInISO": null
}
},
"price_reco": false,
"project_creation_date": "2022-07-06T05:46:26.670Z",
"project_last_complete_date": null,
"template_id": 15
}
|
PUT survey API - When in payload buyer passes a template id, but template feature is not enabled for him.
| Code Block |
|---|
PUT <SERVER_BASE_URL>/buyers/v2/surveys/7134 |
Same request and response payload as POST survey API
PUT survey API - When in payload buyer passes a template he does not have access to.
| Code Block |
|---|
PUT <SERVER_BASE_URL>/buyers/v2/surveys/7134 |
Same request and response payload as POST survey API
PUT survey API - When the buyer passes the correct template Id in the payload
| Code Block |
|---|
PUT <SERVER_BASE_URL>/buyers/v2/surveys/7134 |
Same request and response payload as POST survey API
PUT survey API - When the buyer passes a different template id than the one used in the survey
| Code Block |
|---|
PUT <SERVER_BASE_URL>/buyers/v2/surveys/7134 |
Same request payload as POST survey API
Response
| Code Block |
|---|
{
"ps_api_response_code": 1014,
"ps_api_response_message": "You can only apply one template to a survey. Please consider creating a new survey to use this template."
}
|
PUT survey API - When the buyer passes the template id but the survey does not use any template
| Code Block |
|---|
PUT <SERVER_BASE_URL>/buyers/v2/surveys/7135 |
Same request and response payload as POST survey API
| Code Block |
|---|
{
"ps_api_response_code": 1014,
"ps_api_response_message": "Template Id cannot be applied. Create a new survey to use this template."
}
|
Inherit the metadata template value if the payload doesn’t have them.
POST survey API
| Code Block |
|---|
POST <SERVER_BASE_URL>/buyers/v2/surveys |
Request Payload:
| Code Block |
|---|
{
"template_id": 5
}
|
Response:
| Code Block |
|---|
{
"qbp": {
"enable": false
},
"qlc": {
"enable": false,
"multiple_quotas": {
"enable": false,
"count_by_quota": false,
"compensate_by_quota": false
}
},
"soft_launch": {
"enable": false
},
"unique_links": {
"enable": false
},
"click_balancing": 0,
"estimated_clicks": 0,
"survey_external_id": "",
"ps_survey_status": 11,
"offer_price": null,
"incl_excl": 0,
"quota_throttling": false,
"url_transform": false,
"subscriber_emails": [],
"survey_title": "Template Update : Pooja",
"survey_category_code": 232,
"completes_required": 100,
"field_time": 5,
"buyer_message": null,
"live_url": null,
"billing_id": null,
"test_url": null,
"expected_loi": 23,
"expected_ir": 34,
"ps_survey_id": 383244,
"buyer_surveygroup_ref": null,
"buyer_surveygroup_refs": [],
"test_ps_survey_entry_link": "https://qa1-api.spectrumsurveys.com/#/start-survey?survey_id=383244&ps_redirect_test=1&bsec=a70mx8&supplier_id=23",
"survey_localization": "en_US",
"uniqueLinks": false,
"quotas": [
{
"buyer_quota_id": "v11eMeGAyRyYday",
"quota_title": "",
"ps_quota_id": "b0a9a463-5a0c-4540-8a0e-101d46abeeb0",
"required_count": 50,
"criteria": [
{
"qualification_code": 229,
"condition_codes": [
"91945",
"91977"
]
}
]
},
{
"buyer_quota_id": "SJFDq4ZrU1F8ml8",
"quota_title": "",
"ps_quota_id": "fcc44770-a1f4-4a4f-8754-010bef62aa94",
"required_count": 50,
"criteria": [
{
"qualification_code": 229,
"condition_codes": [
"91950",
"91978"
]
}
]
}
],
"qualifications": [
{
"range_sets": [
{
"units": 311,
"to": 99,
"from": 18
}
],
"qualification_code": 212
},
{
"condition_codes": [
"91945",
"91950",
"91977",
"91978"
],
"qualification_code": 229
}
],
"is_feot_enabled": false,
"survey_grouping": [],
"blend_id": null,
"schedule_launch": {
"enable": false,
"info": {
"date": null,
"hours": null,
"minutes": null,
"timezone": null,
"dateTimeInISO": null
}
},
"price_reco": false,
"project_creation_date": "2022-07-27T14:37:31.250Z",
"project_last_complete_date": null,
"template_id": 5
} |
UI view of this survey:
...
PUT survey API
| Code Block |
|---|
PUT <SERVER_BASE_URL>/buyers/v2/surveys/survey_id |
Request Payload:
| Code Block |
|---|
{
"template_id": 5
} |
Response:
| Code Block |
|---|
{
"qbp": {
"enable": false
},
"qlc": {
"enable": false,
"multiple_quotas": {
"enable": false,
"count_by_quota": false,
"compensate_by_quota": false
}
},
"soft_launch": {
"enable": false
},
"unique_links": {
"enable": false
},
"click_balancing": 0,
"estimated_clicks": 0,
"survey_external_id": "",
"ps_survey_status": 22,
"offer_price": 10,
"incl_excl": 0,
"quota_throttling": false,
"url_transform": false,
"subscriber_emails": [
"michaelb@purespectrum.net"
],
"survey_title": "Template Update : Pooja",
"survey_category_code": 232,
"completes_required": 400,
"field_time": 5,
"buyer_message": null,
"live_url": "http://b_emulator.purespectrum.net:3000/emulated_surveyss",
"billing_id": "PS383451",
"test_url": "http://b_emulator.purespectrum.net:3000/emulated_surveyss",
"expected_loi": 23,
"expected_ir": 34,
"ps_survey_id": 383451,
"buyer_surveygroup_ref": null,
"buyer_surveygroup_refs": [],
"test_ps_survey_entry_link": "https://qa1-api.spectrumsurveys.com/#/start-survey?survey_id=383451&ps_redirect_test=1&bsec=a70mx8&supplier_id=23",
"survey_localization": "es_US",
"uniqueLinks": false,
"quotas": [
{
"buyer_quota_id": "v11eMeGAyRyYday",
"quota_title": "",
"ps_quota_id": "cef4d8a1-6821-4e87-92c8-d0fbea1db32c",
"required_count": 50,
"criteria": [
{
"qualification_code": 229,
"condition_codes": [
"91945",
"91977"
]
}
]
},
{
"buyer_quota_id": "SJFDq4ZrU1F8ml8",
"quota_title": "",
"ps_quota_id": "8b8827e1-0237-41c1-a470-416370a7a220",
"required_count": 50,
"criteria": [
{
"qualification_code": 229,
"condition_codes": [
"91950",
"91978"
]
}
]
}
],
"qualifications": [
{
"range_sets": [
{
"units": 311,
"to": 99,
"from": 18
}
],
"qualification_code": 212
},
{
"condition_codes": [
"91945",
"91950",
"91977",
"91978"
],
"qualification_code": 229
}
],
"is_feot_enabled": false,
"survey_grouping": [
383451
],
"blend_id": null,
"schedule_launch": {
"enable": false,
"info": {}
},
"price_reco": false,
"project_creation_date": "2022-07-28T13:13:25.349Z",
"project_last_complete_date": null,
"template_id": 5
} |
If the user specifies in the payload these values, they will be overridden in both POST and PUT API.
Values are:
Completes
IR
LOI
Category
Country
Language
Title