/
Template API
Template API
Claudio Baldi
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:
GET <SERVER_BASE_URL>/buyers/v2/templates?UI=0Response:
[
{
"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:
GET <SERVER_BASE_URL>/buyers/v2/templates?UI=1Response:
[
{
"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:
POST - <SERVER_BASE_URL>/buyers/v2/surveysRequest:
{
"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:
{
"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.
POST - <SERVER_BASE_URL>/buyers/v2/surveysRequest:
{
"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:
{
"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
POST <SERVER_BASE_URL>/buyers/v2/surveysRequest:
{
"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:
{
"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.
PUT <SERVER_BASE_URL>/buyers/v2/surveys/7134Same request and response payload as POST survey API
PUT survey API - When in payload buyer passes a template he does not have access to.
PUT <SERVER_BASE_URL>/buyers/v2/surveys/7134Same request and response payload as POST survey API
PUT survey API - When the buyer passes the correct template Id in the payload
PUT <SERVER_BASE_URL>/buyers/v2/surveys/7134Same 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
PUT <SERVER_BASE_URL>/buyers/v2/surveys/7134Same request payload as POST survey API
Response
{
"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
PUT <SERVER_BASE_URL>/buyers/v2/surveys/7135Same request and response payload as POST survey API
{
"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
POST <SERVER_BASE_URL>/buyers/v2/surveys
Request Payload:
{
"template_id": 5
}
Response:
{
"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
PUT <SERVER_BASE_URL>/buyers/v2/surveys/survey_id
Request Payload:
{
"template_id": 5
}
Response:
{
"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
Related content
Grouping Suppliers Together
Grouping Suppliers Together
Read with this
Create Multi-Country surveys
Create Multi-Country surveys
More like this
Buy API Overview
Buy API Overview
Read with this
Registering Completes
Registering Completes
Read with this
Survey with Age, Income, Gender Qualifications and Quotas
Survey with Age, Income, Gender Qualifications and Quotas
Read with this
Authorization & Connection
Authorization & Connection
Read with this