Quota Level Complete (QLC)

Overview

QLC (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.

Enabling QLC on a survey

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/:SURVEY_ID 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

The quota_id is also compatible with the update survey status API:
Update status of transaction

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.

If you need help with QLC codes, please contact PureSpectrum support at support@purespectrum.com

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:

 {
    "ps_api_response_code": 1014,
    "ps_api_response_message": "QLC can only be turned on if there are quotas. Please set QLC to false, or add quotas in order to launch this survey."
}

Enabling supplier level QLC (SQLC) on a survey

This extends the functionality in QLC for a survey by allowing you to specify a supplier level QLC when setting up Quotas By Supplier (Managing Quotas by supplier).

This is useful in scenarios where a quota in your system may correspond to a supplier level quota in PureSpectrum.

Functionally the setup is similar as above, differing only in that:

a supplier level quota ID must be provided

the respondent’s redirect/query string parameters specify the SQLC params

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

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_supplier_id request body parameter.

Example create survey request body:

{
    "survey_title": "Flo Test Survey QLC supplier",
    "survey_category_code": 231,
    "survey_localization": "en_GB",
    "completes_required": 1000,
    "expected_ir": 60,
    "expected_loi": 60,
    "offer_price": 4.5,
    "incl_excl": 0,
    "live_url": "https://example.com/",
    "test_url": "https://test-example.com/",
    "field_time": 10,
    "billing_id": "PS_123456",
    "qualifications": [
        {
            "qualification_code": 211,
            "condition_codes": [
                "111"
            ]
        }
    ],
    "quotas": [
        {
            "buyer_quota_id": "QMales",
            
            "buyer_quota_supplier_id": "QMales",
            
            "required_count": 500,
            "criteria": [
                {
                    "qualification_code": 211,
                    "condition_codes": [
                        "111"
                    ]
                }
            ]
        }
    ]
}

In the example above, the buyer_quota_supplier_id is set to QMales.

Redirecting Respondents With sQLC 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%%]&sqlc=true. 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=QMales&sqlc=true&ps_hash=bfd084d77e2b84bc81dc24c26cac56de4f26589c

Quota Level Complete (QLC)

Enabling QLC on a survey#

Enabling supplier level QLC (SQLC) on a survey#

Redirecting Respondents With sQLC Codes#

Enabling QLC on a survey

Enabling supplier level QLC (SQLC) on a survey

Redirecting Respondents With sQLC Codes