Create group multi-country surveys

Description

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-country project.

This API extends Create Multi-Country surveys and allows 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.

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

2 surveys with the same localization cannot be added.

Rules

survey_localizations

It is an array of locales.

minimum requirement of 2 locales (validation added).

quotas

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

qualifications

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

surveys (OPTIONAL) used to declare specific locale overrides.

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

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

completes_required (MANDATORY) - single locale complete.

quotas - Array of quotas for this specific locale

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

qualifications - Array of qualifications for this specific locale

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

live_url - will override common live URL.

expected_loi - will override common LOI.

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

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

Request

Authorization

Add parameter in header

access-token

Example:

access-token: ********************

Body Params application/json

Example

{
    "survey_title": "Test MC",
    "survey_category_code": 211,
    "completes_required": 100,
    "field_time": 10,
    "live_url": "http://example.com/survey",
    "expected_loi": 10,
    "expected_ir": 10,
    "survey_localizations": [
        "en_US",
        "es_US"
    ],
    "surveys": [
        {
            "survey_localization": "es_US",
            "completes_required": 51,
            "survey_title": "Test MC Project 1",
            "quotas": [
                {
                    "buyer_quota_id": "bqID1",
                    "required_count": 50,
                    "criteria": [
                        {
                            "qualification_code": 211,
                            "condition_codes": [
                                "112"
                            ]
                        }
                    ]
                }
            ],
            "qualifications": [
                {
                    "condition_codes": [
                        "112"
                    ],
                    "qualification_code": 211
                }
            ]
        },
        {
            "survey_localization": "en_US",
            "completes_required": 49,
            "field_time": 9,
            "live_url": "http://example.com/survey",
            "survey_title": "Test MC Project 2",
            "expected_loi": 9,
            "expected_ir": 9
        }
    ],
    "quotas": [
        {
            "buyer_quota_id": "bqID2",
            "required_count": 50,
            "criteria": [
                {
                    "qualification_code": 211,
                    "condition_codes": [
                        "111"
                    ]
                }
            ]
        }
    ],
    "qualifications": [
        {
            "condition_codes": [
                "111"
            ],
            "qualification_code": 211
        }
    ]
}

Request Code Samples

Shell

JavaScript

Java

PHP

Python

Ruby

curl --location --request POST 'https://staging.spectrumsurveys.com/buyers/v2/projects' \
--header 'access-token: <api-key>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "survey_title": "Test MC",
    "survey_category_code": 211,
    "completes_required": 100,
    "field_time": 10,
    "live_url": "http://example.com/survey",
    "expected_loi": 10,
    "expected_ir": 10,
    "survey_localizations": [
        "en_US",
        "es_US"
    ],
    "surveys": [
        {
            "survey_localization": "es_US",
            "completes_required": 51,
            "survey_title": "Test MC Project 1",
            "quotas": [
                {
                    "buyer_quota_id": "bqID1",
                    "required_count": 50,
                    "criteria": [
                        {
                            "qualification_code": 211,
                            "condition_codes": [
                                "112"
                            ]
                        }
                    ]
                }
            ],
            "qualifications": [
                {
                    "condition_codes": [
                        "112"
                    ],
                    "qualification_code": 211
                }
            ]
        },
        {
            "survey_localization": "en_US",
            "completes_required": 49,
            "field_time": 9,
            "live_url": "http://example.com/survey",
            "survey_title": "Test MC Project 2",
            "expected_loi": 9,
            "expected_ir": 9
        }
    ],
    "quotas": [
        {
            "buyer_quota_id": "bqID2",
            "required_count": 50,
            "criteria": [
                {
                    "qualification_code": 211,
                    "condition_codes": [
                        "111"
                    ]
                }
            ]
        }
    ],
    "qualifications": [
        {
            "condition_codes": [
                "111"
            ],
            "qualification_code": 211
        }
    ]
}'

Responses

🟢201Created

application/json

Body

Example

{
    "aida": {
        "enabled": false,
        "selected_quota_ids": []
    },
    "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,
    "is_modular_survey": false,
    "live_url": "http://example.com/survey",
    "billing_id": "PS1161691",
    "test_url": null,
    "expected_loi": 10,
    "expected_ir": 10,
    "ps_survey_id": 1161691,
    "buyer_surveygroup_ref": null,
    "buyer_surveygroup_refs": [],
    "test_ps_survey_entry_link": "https://staging.spectrumsurveys.com/#/start-survey?survey_id=1161691&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": "2025-04-30T20:50:55.138Z",
    "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": "",
    "pds_ignore_override": false,
    "supplier_allocation_throttle": true,
    "blend_applied": false
}

🟠400Bad Request

🟠401Unauthorized

Create group multi-country surveys

Description#

Rules#

Request

Request Code Samples

Responses

Description

Rules