Create Group Multi-Country surveys (in a single API)

Owned by Claudio Baldi
Last updated: Aug 22, 2024
21 min read

Group Multi-Country survey allows to replicate the group multi-country feature available via UI. This version allows to send one payload and create a multi markets project.

image-20240502-111732.png

Context:

This API extends “Create Multi-Country surveys API” and allow to create a Group Multi-Country study with just a single request. The single payload contains the parameters for all the countries / languages for the survey and the system will create the project.

NOTE:

  • Multi-Country and Group Multi-Country feature are different and each feature has their rules and property.

  • Make sure the Group Multi-Country feature is activate to your account

  • 2 surveys with the same localization cannot be added.

    • Ex.: for localization we define the combination between Language and Country (en-US)

Rules:

  1. survey_localizations

    1. It is an array of locales.

    2. minimum requirement of 2 locales (validation added).

  2. quotas

    1. It is an array of quotas that will be common to all locales.

  3. qualifications

    1. It is an array of qualifications that will be common to all locales.

  4. surveys (OPTIONAL)- used to declare specific locale overrides.

    1. It is an array of objects which contains individual locale overrides.

    2. survey_localization (MANDATORY) - single locale declared in survey_localizations above.

    3. completes_required (MANDATORY) - single locale complete.

    4. quotas - Array of quotas for this specific locale

      1. This quota will override any quota specified in the common quotas section if it exists.

    5. qualifications - Array of qualifications for this specific locale

      1. This qualification will override any qualification specified in the common qualifications section if it exists.

    6. live_url - will override common live URL.

    7. expected_loi - will override common LOI.

    8. any other field from common survey details can be overridden here.

  5. If surveys are not provided then the completes will be equally distributed to all single locales.

Request:

Create a Group Multi-Country Survey with

  • Localized in

    • US - English Speakers

    • US - Spanish Speakers

  • 100 completes per market,

  • LOI = 10

  • Field time = 10

  • IR = 10

Include Qualification and Quota

API call:

POST {{BASE_URL}}/buyers/v2/projects

($basepath is the base path with the api version. All Buy API calls will require access-token parameter in the header)

Payload:

{ "survey_title": "test MC", "survey_category_code": 211, "completes_required": 100, "field_time": 10, "live_url": "http://localhost:5000/emulated_surveys", "expected_loi": 10, "expected_ir": 10, "survey_localizations": [ "en_US", "es_US" ], "surveys": [ { "survey_localization": "es_US", "completes_required": 51, "quotas": [ { "required_count": 50, "criteria": [ { "qualification_code": 215, "condition_codes": [ "111" ] } ] } ], "qualifications": [ { "exclude": true, "condition_codes": [ "112" ], "qualification_code": 215 } ], "survey_title": "test MC child 1" }, { "survey_localization": "en_US", "completes_required": 49, "field_time": 9, "live_url": "http://localhost:5000/emulated_surveys", "survey_title": "test MC child 2", "expected_loi": 9, "expected_ir": 9, "quotas": [], "qualifications": [ { "exclude": true, "condition_codes": [ "111" ], "qualification_code": 1000 } ] } ], "quotas": [ { "buyer_quota_id": "b5880136-3de3-4e88-85f9-cb1db5bc6ca1", "ps_quota_id": "29ddd3f6-ae1e-40b5-a2ca-e2cb9a880ac5", "required_count": 50, "criteria": [ { "qualification_code": 211, "condition_codes": [ "111" ] } ] } ], "qualifications": [ { "condition_codes": [ "111" ], "qualification_code": 211 }, { "range_sets": [ { "from": 18, "to": 99, "units": 311 } ], "qualification_code": 212 } ] }

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": "test MC", "survey_category_code": 211, "completes_required": 100, "field_time": 10, "buyer_message": null, "live_url": "http://localhost:5000/emulated_surveys", "billing_id": "PS14437", "test_url": null, "expected_loi": 10, "expected_ir": 10, "ps_survey_id": 14437, "buyer_surveygroup_ref": null, "buyer_surveygroup_refs": [], "test_ps_survey_entry_link": "http://localhost:3000/#/start-survey?survey_id=14437&ps_redirect_test=1&bsec=a70mx8&supplier_id=23", "survey_localizations": [ "es_US", "en_US" ], "uniqueLinks": false, "quotas": [], "qualifications": [], "is_feot_enabled": false, "feot": {}, "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": "2024-02-26T18:05:00.451Z", "project_last_complete_date": null, "is_dq_enable": false, "mc_count": 0, "tc_count": 0, "basic_token": { "enable": false, "value": null }, "is_pure_price_rate_card_enable": true, "dq_settings": { "purescore_filter_enabled": true, "fp_device_check": true, "fp_fraud_check": true }, "product": "" }

 

Request:

Update the Group Multi-Country survey.

API call:

PUT - {{BASE_URL}}/buyers/v2/projects/{parent_survey_id}

($basepath is the base path with the api version. All Buy API calls will require access-token parameter in the header)

Payload:

{ "survey_title": "test MC", "survey_category_code": 211, "completes_required": 101, "field_time": 10, "live_url": "http://localhost:5000/emulated_surveys", "expected_loi": 10, "expected_ir": 10, "survey_localizations": [ "en_US", "fr_CA" ], "surveys": [ { "survey_localization": "fr_CA", "completes_required": 52, "quotas": [ { "required_count": 50, "criteria": [ { "qualification_code": 219, "condition_codes": [ "111" ] } ] }, { "required_count": 50, "criteria": [ { "qualification_code": 211, "condition_codes": [ "112" ] } ] } ], "qualifications": [ { "condition_codes": [ "111" ], "qualification_code": 219 }, { "condition_codes": [ "112" ], "qualification_code": 211 } ], "survey_title": "test MC child 1" }, { "survey_localization": "en_US", "completes_required": 49, "field_time": 9, "live_url": "http://localhost:5000/emulated_surveys", "survey_title": "test MC child 2", "expected_loi": 9, "expected_ir": 9, "quotas": [], "qualifications": [ { "condition_codes": [ "111" ], "qualification_code": 1000 } ] } ], "quotas": [ { "buyer_quota_id": "b5880136-3de3-4e88-85f9-cb1db5bc6ca1", "ps_quota_id": "29ddd3f6-ae1e-40b5-a2ca-e2cb9a880ac5", "required_count": 50, "criteria": [ { "qualification_code": 211, "condition_codes": [ "111" ] } ] } ], "qualifications": [ { "condition_codes": [ "111" ], "qualification_code": 211 }, { "range_sets": [ { "from": 18, "to": 99, "units": 311 } ], "qualification_code": 212 } ] }

Response:

{ "survey_title": "test MC", "survey_category_code": 211, "completes_required": 101, "field_time": 10, "live_url": "http://localhost:5000/emulated_surveys", "expected_loi": 10, "expected_ir": 10, "survey_localizations": [ "en_US", "fr_CA" ], "surveys": [ { "survey_localization": "fr_CA", "completes_required": 52, "quotas": [ { "required_count": 50, "criteria": [ { "qualification_code": 219, "condition_codes": [ "111" ] } ] }, { "required_count": 50, "criteria": [ { "qualification_code": 211, "condition_codes": [ "112" ] } ] } ], "qualifications": [ { "condition_codes": [ "111" ], "qualification_code": 219 }, { "condition_codes": [ "112" ], "qualification_code": 211 } ], "survey_title": "test MC child 1" }, { "survey_localization": "en_US", "completes_required": 49, "field_time": 9, "live_url": "http://localhost:5000/emulated_surveys", "survey_title": "test MC child 2", "expected_loi": 9, "expected_ir": 9, "quotas": [], "qualifications": [ { "condition_codes": [ "111" ], "qualification_code": 1000 } ] } ], "quotas": [ { "buyer_quota_id": "b5880136-3de3-4e88-85f9-cb1db5bc6ca1", "ps_quota_id": "29ddd3f6-ae1e-40b5-a2ca-e2cb9a880ac5", "required_count": 50, "criteria": [ { "qualification_code": 211, "condition_codes": [ "111" ] } ] } ], "qualifications": [ { "condition_codes": [ "111" ], "qualification_code": 211 }, { "range_sets": [ { "from": 18, "to": 99, "units": 311 } ], "qualification_code": 212 } ] }

Request:

GET survey by ID - If it's an MC single-view project then the response will have survey_localizations

API call:

GET {{BASE_URL}}/buyers/v2/survey/{{SURVEY_ID}}

($basepath is the base path with the api version. All Buy API calls will require access-token parameter in the header)

Payload:

[]

Response:

"survey_localizations": [ "en_US", "fr_CA" ]