Versions Compared

Version Old Version 22 New Version 23
Changes made by

Claudio Baldi

Claudio Baldi

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

PRODUCTION API END POINTS:

...

  • If included, the reason value should be added in "change_reason" and these are the options:

    • Suspected Fraud

    • Respondent Quality (speeding, straightlining, text response...)

    • Ghost Completes

    • Client Rejected

    • Duplicate Respondent

  • Any other variation is accepted and is recorded as Respondent Quality.

Example Single Survey Call:

Buyer API Endpoint:

Code Block
Change to Complete
POST:
{url}/adjustments/surveys/:surveyId?operationType=LIVE_RECONCILIATION&reconStatus=1

Change to Buyer_Reconciliation_Reject
POST:
{url}/adjustments/surveys/:surveyId?operationType=LIVE_RECONCILIATION&reconStatus=2

REQUEST PAYLOAD($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 Payload:

Code Block
languagejson
[
    {
        "transaction_id": "7lNK5AGrSL3bk5tV4gw0Tr",
        "change_reason": "Suspected Fraud" // optional
    },
    {
        "transaction_id": "7dTdSUUWkR9DBs7rUi5jdT"
    },
    {
        "transaction_id": "5EmEbeX9mEblEpwP6yHG1K"
    },
    {
        "transaction_id": "6HkYQWFMcIcDOTxfnIi6op"
    }
]

...

Response:
Response Code:
 Tip
CODE: 200 OK202 ACCEPTED
Response Code (deprecated):
 Tip
CODE: 200 OK
Response Body
 Code Block
languagejson
{
    "adjustment_id": "b43ce6a3-9578-4ba6-8cc5-a4add094a352",
    "summary": {
        "currentCompletes": 16,
        "previouslyRejectedCompletes": 0,
        "rejectingCompletesInCurrentUpload": 4,
        "acceptingCompletesInCurrentUpload": 0,
        "resultingCompletes": 16,
        "totalRawCompletes": 20,
        "totalRejects": 4,
        "rejectPercentage": "22.50",
        "desiredStatus": {33},
        "eligible": 4,
        "rejected": 4,
        "completed": 0,
        "test": 0,
        "transactions": 4,
        "transactionsWithDesiredStatus": 0,
        "summaryPerSurvey": [
            {
                "surveyId": 38226312,
                "currentCompletes": 16,
                "previouslyRejectedCompletes": 0,
                "rejectingCompletesInCurrentUpload": 4,
                "acceptingCompletesInCurrentUpload": 0,
                "resultingCompletes": 16,
                "totalRawCompletes": 20,
                "totalRejects": 4,
                "rejectPercentage": "22.50",
                "desiredStatus": 33,
                "eligible": 4,
                "rejected": 4,
                "completed": 0,
                "test": 0,
                "transactions": 4,
                "transactionsWithDesiredStatus": 0,
                "validCap": true
            }
        ],
        "validCap": true,
        "invoiced": 0,
        "isApiUser": true
    }
}
 Note
NOTE: If one or more transaction_id/s (TXs) passed are ineligible or already reconciled, the system will start the reconciliation process and those TXs will be skipped.
Response explanation:
  •  "eligible": are the transactions that are eligible and the status changed within the process 
  • "rejected": are the transactions that changed from Complete to Buyer_Reconciliation_Reject
  • "completed”: are the transactions that changed from Buyer_* to Complete
  • "test": are the transactions captured via the button test (available in UI)
  • "transactions": total completes uploaded
  • "transactionsWithDesiredStatus": are the transactions that already have the status requested with this reconciliation process. 
 Note
NOTE: to get the transactions not eligible to reconcile or not reconciled withing the recon process you can use this formula
transactions - eligible = not eligible / not reconciled
Errors Codes:
All transactions are invalid or belong to another survey
  • The reconciliation process will not start
...
 Code Block
{
    "ps_api_response_code": 9999,
    "ps_api_response_message": "Unable to find surveys associated with submitted transactions"
}
Some, but not all, transactions are invalid or belong to another survey
  • The reconciliation process will not start
...
 Code Block
{
    "ps_api_response_code": 9999,
    "ps_api_response_message": "Some transactions belongs to another survey, Please check the request"
}
All transactions are ineligible for reconciliation
  • The reconciliation process will not start
...
 Code Block
{
    "ps_api_response_code": 9999,
    "ps_api_response_message": "File contain transactions that are ineligible for reconciliation. You may only reconcile completes in a closed survey, or completes from a prior month calendar or the survey has been already reconciled"
}
The total TX rejects allowed is reached. The limit set at the moment is 50%
  • The reconciliation process will not start
...
 Code Block
{
    "ps_api_response_code": 9999,
    "ps_api_response_message": "The number of total rejects, for this survey exceeds our threshold of 50% and can't be processed. Please upload a new file or contact PureSpectrum for assistance"
}
DESCRIPTION: 
STAGING API and Payload:
1 - Reconciliation Single Survey: 
Buyer API endPoint - Change the transaction to Buyer_Reconciliation_Reject:
 Code Block
Single survey: 
POST : https://staging.spectrumsurveys.com/buyers/v2/adjustments/surveys/{surveyId}?operationType=LIVE_RECONCILIATION&reconStatus=2
API: POST
Access-token: Buyer account
($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 Payload:
 Code Block
languagejson
[
    {
        "transaction_id": "7lNK5AGrSL3bk5tV4gw0Tr"
        "change_reason": "Respondent Quality" // optional
    },
    {
        "transaction_id": "7dTdSUUWkR9DBs7rUi5jdT"
    },
    {
        "transaction_id": "5EmEbeX9mEblEpwP6yHG1K"
    },
    {
        "transaction_id": "6HkYQWFMcIcDOTxfnIi6op"
    }
]
...
_id": "6HkYQWFMcIcDOTxfnIi6op"
    }
]
Response Code:
 Tip
CODE: 202 ACCEPTED
Response Code (deprecated):
 Tip
CODE: 200 OK
Response Body:
 Code Block
languagejson
{
    "adjustment_id": "b43ce6a3-9578-4ba6-8cc5-a4add094a352",
    "summary": {
        "currentCompletes": 16,
        "previouslyRejectedCompletes": 0,
        "rejectingCompletesInCurrentUpload": 4,
        "acceptingCompletesInCurrentUpload": 0,
        "resultingCompletes": 16,
        "totalRawCompletes": 20,
        "totalRejects": 4,
        "rejectPercentage": "22.50",
        "desiredStatus": {33},
        "eligible": 4,
        "rejected": 4,
        "completed": 0,
        "test": 0,
        "transactions": 4,
        "transactionsWithDesiredStatus": 0,
        "summaryPerSurvey": [
            {
                "surveyId": 38226312,
                "currentCompletes": 16,
                "previouslyRejectedCompletes": 0,
                "rejectingCompletesInCurrentUpload": 4,
                "acceptingCompletesInCurrentUpload": 0,
                "resultingCompletes": 16,
                "totalRawCompletes": 20,
                "totalRejects": 4,
                "rejectPercentage": "22.50",
                "desiredStatus": 33,
                "eligible": 4,
                "rejected": 4,
                "completed": 0,
                "test": 0,
                "transactions": 4,
                "transactionsWithDesiredStatus": 0,
                "validCap": true
            }
        ],
        "validCap": true,
        "invoiced": 0,
        "isApiUser": true
    }
}
...
Buyer API endPoint - Change the transaction to Buyer_Reconciliation_Reject:
 Code Block
Multiple Survey: 
POST : https://staging.spectrumsurveys.com/buyers/v2/adjustments?operationType=LIVE_RECONCILIATION&reconStatus=2
API:POST
Access-token:Buyer account
Request Payload:
 Code Block
languagejson
[
    {
        "transaction_id": "7by1JwD0oLzX1iip0liui4",
        "change_reason": "Suspected Fraud" // optional
    },
    {
        "transaction_id": "7Er50MDCnV0b0bc91S8Qr1",
        "change_reason": "Respondent Quality" // optional
    },
    {
        "transaction_id": "41JBHVbfHas8kzAwYhGW9l",
        "change_reason": "Ghost Completes" // optional
    },
    {
        "transaction_id": "7mwVC728181yok8mKgDzQv",
        "change_reason": "Client Rejected" // optional
    },
    {
        "transaction_id": "21NJOoeCB4mXoMZXg77bNo",
        "change_reason": "Duplicate Respondent" // optional
    },
    {
        "transaction_id": "5j2UOEpgsMlXoLix0qtU0W"
    }
]
Response Code:
 Tip
CODE: 202 ACCEPTED
Response Code (deprecated):
 Tip
CODE: 200 OK
Response Body:
 Code Block
languagejson
{
    "adjustment_id": "b43ce6a3-9578-4ba6-8cc5-a4add094a352",
    "summary": {
        "currentCompletes": 16,
        "previouslyRejectedCompletes": 0,
        "rejectingCompletesInCurrentUpload": 4,
        "acceptingCompletesInCurrentUpload": 0,
        "resultingCompletes": 16,
        "totalRawCompletes": 20,
        "totalRejects": 4,
        "rejectPercentage": "22.50",
        "desiredStatus": {33},
        "eligible": 4,
        "rejected": 4,
        "completed": 0,
        "test": 0,
        "transactions": 4,
        "transactionsWithDesiredStatus": 0,
        "summaryPerSurvey": [
            {
                "surveyId": 38226312,
                "currentCompletes": 16,
                "previouslyRejectedCompletes": 0,
                "rejectingCompletesInCurrentUpload": 4,
                "acceptingCompletesInCurrentUpload": 0,
                "resultingCompletes": 16,
                "totalRawCompletes": 20,
                "totalRejects": 4,
                "rejectPercentage": "22.50",
                "desiredStatus": 33,
                "eligible": 4,
                "rejected": 4,
                "completed": 0,
                "test": 0,
                "transactions": 4,
                "transactionsWithDesiredStatus": 0,
                "validCap": true
            }
        ],
        "validCap": true,
        "invoiced": 0,
        "isApiUser": true
    }
}
 Info
NOTE 1: The system always records any Reconciliation process made via API or UI and this information can be found on the Survey dashboard → Reconciliation Tab
These are the label showshown:
  • Reject : Reconciliation via UI - TX changes to buyer_rejects
  • Reject (API): Reconciliation via API - TX changes to buyer_rejects
  • Complete: Reconciliation via UI - TX changes to complete
  • Complete (API): Reconciliation via UI - TX changes to buyer_rejects
  • Accept: Reconciliation via UI - Any TX in the file will changes to complete if they are eligible, and the TX current completes not in the file, will change buyer_rejects
  • Accept (API): Reconciliation via API - Any TX in the file will changes to complete if they are eligible, and the TX current completes not in the file, will change buyer_rejects
...