Overview

Buyers may choose to “Soft Launch” a survey, where they will field a limited number of clicks or completes. This number is significantly less than the total number of completes the project requires, which may cause throttling issues leading to significant clickwaste.

To help you better estimate sample requirements as you send to a new study with “Soft Launch” enabled, we offer 2 features in our Supply API.

Use

If a survey is set up for “Soft Launch”, the API response of the GET /Surveys/:SurveyId endpoint will be different than a normal survey, in that:

The property ”soft_launch” is set to TRUE.
Quotas in the survey will show a ”currenlty_open” value that displays the true number of clicks or completes available in the survey OR quota, taking the soft launch into consideration.

When sending sample to a project that has soft launch enabled, the quotas will reflect the more conservative number, which should help you estimate traffic requirements, and prevent oversampling/clickwaste.

Important Considerations

For existing Supplier API integrations, no additional development should be required to take advantage of this feature. We have designed the system to utilize available counters when communicating restricted quantities.

The ”currently_open” value of each quota will reflect the minimum of:

Completes available in the quota
Completes available in the soft launch

The soft launch is not reflected in the “supplier_completes” object, and is only reflected in the “currently_open” value of the quota.

Request

GET $apihost/$basepath/surveys/:surveyId

($apihost is the environment against which you are testing, and $basepath is the base path with the api version. All Buy API calls will require access-token parameter in the header)

Request:

GET https://api.spectrumsurveys.com/suppliers/v2/surveys/:surveyId

Result

Response Code

200

Response Body

{
    "apiStatus": "success",
    "msg": "Survey Quota and Qualification fetched successfully ",
    "version": "2.0",
    "survey": {
        "survey_grouping": {
            "survey_ids": [
                012345
            ],
            "exclusion_period": 30
        },
        "incl_excl": 0,
        "cpi": 2.50,
        "supplier_completes": {
            "needed": 50,
            "achieved": 5,
            "remaining": 45
        },
        "price_type": 1,
        "pii": false,
        "buyer_message": "",
        "survey_performance": {
            "overall": {
                "ir": 7,
                "loi": 16
            },
            "last_block": {
                "ir": 7,
                "loi": 16
            }
        },
        "survey_id": 123456,
        "last_complete_date": 1587079259955,
        "survey_name": "Exciting New Survey #479329",
        "surveyLocalization": "en_US",
        "survey_status": 33,
        "buyer_id": 163,
        "field_end_date": 1588373966682,
        "crtd_on": 1587077966685,
        "mod_on": 1587079256164,
        "click_balancing": 0,
        "category": "Exciting New",
        "category_code": 232,
        "qualifications": [
            {
                "condition_codes": [
                    "112",
                    "111"
                ],
                "qualification_code": 211
            },
            {
                "qualification_code": 212,
                "range_sets": [
                    {
                        "from": 25,
                        "to": 35,
                        "units": 311
                    },
                    {
                        "from": 18,
                        "to": 24,
                        "units": 311
                    },
                    {
                        "from": 26,
                        "to": 35,
                        "units": 311
                    }
                ]
            },
            {
                "condition_codes": [
                    "112",
                    "113",
                    "111"
                ],
                "qualification_code": 219
            }
        ],
        "quotas": [
              {
                "quota_id": "1d36daca-42c0-4cd4-b1ea-9a2e219237d6",
                "quantities": {
                    "currently_open": 5,
                    "remaining": 50,
                    "achieved": 3
                },
                "criteria": [
                    {
                        "qualification_code": 219,
                        "condition_codes": [
                            "112",
                            "113"
                        ]
                    }
                ],
                "crtd_on": 1587077971121,
                "mod_on": 1587082329823,
                "last_complete_date": 1587082329802
            },
            {
                "quota_id": "1d36daca-42c0-4cd4-b1ea-9a2e219237d5",
                "quantities": {
                    "currently_open": 5,
                    "remaining": 25,
                    "achieved": 1
                },
                "criteria": [
                    {
                        "qualification_code": 219,
                        "condition_codes": [
                            "111"
                        ]
                    }
                ],
                "crtd_on": 1587077971121,
                "mod_on": 1587082329823,
                "last_complete_date": 1587082329802
            }
        ],
        "soft_launch": true
       }
}