Overview

QLC (aka Quota Level Complete) allows a respondent to be re-allocated to a different quota cell on survey complete. This is useful in Least-Fill Quota scenarios, where a respondent may qualify for one quota cell in PureSpectrum, but qualifies for different quota cell(s) in the survey.

Upon redirect, if QLC is enabled, PureSpectrum will reallocate the respondent session to the quotas indicated in the respondent’s URL Query String Parameters.

Use

Enabling QLC on a survey via Buy API

To enable QLC on a survey via Buy API, you must pass in the following request body parameters in either the POST /surveys or PUT /surveys/:surveyId endpoints:

"qlc": {
  "enable": true,
  "multiple_quotas": { 
    "enable": true
    } 
}

There are additional options for:

"count_by_quota": false, "compensate_by_quota": false

It is important that these are either omitted from the request entirely, or set to false.

The option for “qlc.multiple_quotas.enable” should be set to true, if “qlc.enable” is set to true.

By default, qlc.enable is set to false. In order for QLC to be enabled, your survey must have at least one buyer defined quota.

Setting up identifiers for the quotas used in QLC

If QLC is enabled, the query string parameters of the respondent redirect are checked to determine which quota cells should be (re)allocated. The identifiers in the query string parameter are the same identifiers used in the buyer_quota_id

Example:

"quotas": [
        {
            "buyer_quota_id": "1",
            "ps_quota_id": "9e90fb74-3f5b-4d0f-92d3-3c920aa1e40e",
            "required_count": 300,
            "criteria": [
                {
                    "qualification_code": 211,
                    "condition_codes": [
                        "111"
                    ]
                }
            ]
        }
    ]

In the example above, the “buyer_quota_id” is set to “1”.

Redirecting Respondents With QLC Codes

Once enabled, respondents completing the survey will be checked for the appropriate query string parameters, and their statistics will be appropriately reallocated. Appended to their query string, should be &quota_id=[%%buyer_quota_id%%]. In this case, [%%buyer_quota_id%%] would correspond to the buyer_quota_id specified when setting up the survey.

Example

https://spectrumsurveys.com/surveydone?st=21&transaction_id=abc123&quota_id=1,3,44&ps_hash=bfd084d77e2b84bc81dc24c26cac56de4f26589c

Important Considerations

If qlc.enable is set to false, none of the other options can be set to true.
QLC may not be changed after a survey is live.
Regardless of what is sent in the request payload, you will always receive a response object for qlc.
QLC is an advanced feature, and should not be used without first consulting PureSpectrum support.

Request

POST (or PUT) $apihost/$basepath/surveys

($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)

Parameters:

Body:

{
    "live_url": "https://yoursurvey.com/survey123",
    "test_url": "https://yoursurvey.com/survey123/test=1",
    "survey_title": "Test Survey",
    "survey_category_code": 231,
    "survey_localization": "en_US",
    "completes_required": 3,
    "expected_ir": 10,
    "expected_loi": 10,
    "offer_price": 10,
    "field_time": 99,
    "qualifications": [
        {
            "qualification_code": 211,
            "condition_codes": [
                "111",
                "112"
            ]
        }
    ],
    "quotas": [
        {
            "buyer_quota_id": "1",
            "required_count": 3,
            "criteria": [
                {
                    "qualification_code": 211,
                    "condition_codes": [
                        "111"
                    ]
                }
            ]
        },
         {
            "buyer_quota_id": "2",
            "required_count": 3,
            "criteria": [
                {
                    "qualification_code": 211,
                    "condition_codes": [
                        "112"
                    ]
                }
            ]
        }
    ],
    "qlc": {
        "enable": true,
        "multiple_quotas": {
            "enable": true
        }
    }
}

Result

Response Code

201 if POST, 200 if PUT

Response Body

Error Handling

In the event a request enables QLC, but there are no quotas, the API will respond with HTTP status 400, and error code:

PureSpectrum Buyer API

Enabling QLC for a Survey