Overview

sQLC extends the functionality in https://purespectrum.atlassian.net/wiki/spaces/PBA/pages/849707035 by allowing you to specify a Supplier Level QLC when setting up Quotas By Supplier (https://purespectrum.atlassian.net/wiki/spaces/PBA/pages/855736417). This is useful in scenarios where a quota in your system may correspond to a supplier level quota in PureSpectrum.

Functionally, the setup similar. 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.

Use

Enabling sQLC on a survey via Buy API

This is the same process as in https://purespectrum.atlassian.net/wiki/spaces/PBA/pages/849707035

To enable sQLC 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 sQLC

If sQLC 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_supplier_quota_id

Example:

"quotas": [
        {
    "buyer_quota_id": "qb30",
    "required_count": 200,
    "suppliers": [
        {
            "supplier_ref_id": "1",
            "buyer_quota_supplier_id": 1,
            "current_target": 50
        },
        {
            "supplier_ref_id": "2",
            "buyer_quota_supplier_id": 3,
            "current_target": 150
        },
        {
            "supplier_ref_id": "3",
            "buyer_quota_supplier_id": 5,
            "current_target": 150
        },
        {
            "supplier_ref_id": "4",
            "buyer_quota_supplier_id": 7,
            "current_target": 150
        }        
    ],
    "criteria": [
        {
            "qualification_code": 214,
            "condition_codes": [
                "112"
            ]
        }
    ]
}
]

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

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.

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 Supplier Level QLC (sQLC) for a Survey