Survey reconciliation

Description

This endpoint can be used to reconcile transaction ID’s for both Closed or Live / Paused surveys.

Brief overview, workflow, and examples below will help demonstrate how the different options work:

Live or paused: Use this option to reconcile the surveys in LIVE or PAUSED state, by rejecting or accepting transactions while data collection is happening, also commonly known as “Live Reconciliation”. When using this API endpoint, post specific transaction ID’s to be accepted or rejected. Rejections in a LIVE survey, means the survey can reopen to other respondents to fulfill survey quota goals.

Closed: In a CLOSED survey only accepted transaction ID’s need to be sent via the API endpoint, transaction ID’s omitted from the API call, which have been previously marked as complete, will be automatically rejected by PureSpectrum. It’s not possible to reopen a closed survey, and as such, posting accepted transaction ID’s to a closed survey may end up in some shortfall.

We recommend reconciling live or paused surveys where possible, particularly as posting rejections at this stage means other respondents will be allowed in, allowing fulfilment of survey goals. Where more robust quality checks are required, reconciling once a survey is closed is completely acceptable, but it’s important to be aware of the limitations.

NOTE: a transaction ID can only be reconciled once, either by acceptance or rejection.

Thresholds

Only a maximum number of rejections, as a percentage of the completes per survey are allowed. Attempting to reject more than the threshold, will result in an error and will require intervention by PureSpectrum to understand the high level of rejections. For more information on your thresholds, please reach out to your account manager.

It’s possible to hit the threshold through incorrect use of the reconciliation API, and the examples below will help in understanding how to best use the API endpoints in various survey states.

Threshold examples:

Within threshold:

Survey has 20 completes

You wish to accept 16 of the transactions and reject 4

4 transactions of 20 is within expected limits

Closed survey reconciliation:

Send the 16 ID's being accepted, the remaining 4 are auto rejected

Live/Paused survey reconciliation:

Send the 4 trasnaction ID's being rejected, using the reject flag

This reconcilation request will be accepted

If successful, the API will respond with a status of 1, the description as “Pending” (as reconciliations are handled asynchronously), and an adjustment ID. Below is a truncated sample of a successful response:

{
    "status": 1,
    "statusDescription": "Pending",
    "adjustment_id": "505c120f-3560-4c89-9706-811bf998abcd",
…

You should store the adjustment ID, as it can be used to check the status of the reconciliation request later. Steps on how to do this are detailed at the bottom of this page, with links to the relevant documentation.

Exceeding threshold:

Survey has 20 completes

You wish to accept only 4 of the transactions, and reject 16

16 transactions of 20 exceeds expected limits

Closed survey reconciliation:

Send the 4 ID’s being accepted, the remaining 16 are auto rejected.

Live/Paused survey reconciliation:

Send the 16 ID’s being rejected, using the reject flag

This reconciliation request will be rejected

Exceeded threshold response:

The error in this particular instance, states the threshold has been hit

ps_api_response_message": "The number of total rejects, for this survey exceeds our threshold of XX% and can't be processed. Please upload a new file or contact PureSpectrum for assistance”

Reconciliation of closed surveys

In order to reconcile in a closed survey, use this endpoint as is by sending only accepted transaction ID’s

When using this endpoint to reconcile a closed survey, only send the transactions being accepted in the payload. Any transactions not included in the payload, which have been previously marked as complete, will be considered rejections.

You can't reconcile test transaction IDs, only real completes can be reconciled.
Transactions can only be reconciled once, and can’t be reconciled again.

Reconciliation of live / paused surveys

In order to reconcile transactions in open surveys (live / paused), pass the operationType=LIVE_RECONCILIATION query parameter to the endpoint.

To accept or reject the transactions in the payload, you need to additionally use the reconStatus query param, where:

● 1 means you accept the current transaction status
● 2 means you are changing the current transaction status into a new one

When reconciling a Live or Paused survey the query params above are required. We have provided examples of what the URL should look like below:

Accepting the transactions in the payload (typically used to accept completes): https://staging.spectrumsurveys.com/buyers/v2/adjustments/surveys/{SURVEY_ID}?operationType=LIVE_RECONCILIATION&reconStatus=1

Changing the status of the transactions in the payload (typically used to reject transactions): https://staging.spectrumsurveys.com/buyers/v2/adjustments/surveys/{SURVEY_ID}?operationType=LIVE_RECONCILIATION&reconStatus=2

In live reconciliation, it is possible to add an additional field (change_reason) that allows you to add the reason for the reconciliation, for each transaction.
If included, the reason value should be one of these options:
● Suspected Fraud
● Respondent Quality (speeding, straightlining, text response...)
● Ghost Completes
● Client Rejected
● Duplicate Respondent

Other variations are also accepted and recorded as Respondent Quality.

Checking the status of a reconciliation request

After posting a reconciliation, it’s possible to check the status of the request via the API. This verifies that the reconciliation was accepted, and then successfully processed by PureSpectrum, or whether there was an error during the process.

Please refer to the following pages of our API Reference for more information:

● Get status of a reconciliation request
● Get reconciliation status for an adjustment ID

application/json

Bodyapplication/json

Examples

SuccessExample 1Example 2Success

{
    "status": 1,
    "statusDescription": "Pending",
    "adjustment_id": "505c120f-3560-4c89-9706-811bf998abcd",
    "summary": {
        "currentCompletes": 0,
        "previouslyRejectedCompletes": 0,
        "rejectingCompletesInCurrentUpload": 0,
        "acceptingCompletesInCurrentUpload": 1,
        "resultingCompletes": 1,
        "totalRawCompletes": 1,
        "totalRejects": 0,
        "rejectPercentage": "0.00",
        "eligible": 1,
        "completes": 0,
        "rejected": 0,
        "test": 0,
        "alreadyReconciled": 0,
        "invalid": 0,
        "transactions": 1,
        "surveyStatus": [
            {
                "id": 1176671,
                "st": 44,
                "modelType": "surveys"
            }
        ],
        "summaryPerSurvey": [
            {
                "surveyId": 1176671,
                "currentCompletes": 0,
                "previouslyRejectedCompletes": 0,
                "rejectingCompletesInCurrentUpload": 0,
                "acceptingCompletesInCurrentUpload": 1,
                "resultingCompletes": 1,
                "totalRawCompletes": 1,
                "totalRejects": 0,
                "rejectPercentage": "0.00",
                "eligible": 1,
                "completes": 0,
                "rejected": 0,
                "test": 0,
                "alreadyReconciled": 0,
                "invalid": 0,
                "transactions": 1,
                "surveyStatus": [
                    {
                        "id": 1176671,
                        "st": 44,
                        "modelType": "surveys"
                    }
                ],
                "validCap": true
            }
        ],
        "validCap": true,
        "invoiced": 0,
        "isApiUser": true
    }
}

Description

Reconciliation of closed surveys

Reconciliation of live / paused surveys

Checking the status of a reconciliation request

Request

Request Code Samples

Responses

Survey reconciliation

Description#

Reconciliation of closed surveys#

Reconciliation of live / paused surveys#

Checking the status of a reconciliation request#

Request

Request Code Samples

Responses

Description

Reconciliation of closed surveys

Reconciliation of live / paused surveys

Checking the status of a reconciliation request