Versions Compared

Version Old Version 19 New Version Current
Changes made by

Chad Nuesmeyer

Claudio Baldi

Saved on

Key

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

...

...

...

...

PRODUCTION API

...

ENDPOINTS Recap:

Code Block
Single survey: 
POST: https://api.spectrumsurveys.com/buyers/v2/adjustments/surveys/{surveyId}?operationType=LIVE_RECONCILIATION&reconStatus={1/2} 

Multiple Survey: 
POST: https://api.spectrumsurveys.com/buyers/v2/adjustments?operationType=LIVE_RECONCILIATION&reconStatus={1/2}

...

  • reconStatus = 2

In live reconciliation mode, it is possible to add for each transaction an additional field that allow the user to add enter the reason for the the reconciliation . This part made in an additional field. Please note this is optional.

  • 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 has as Respondent Quality.

Example Single Survey Call:

Buyer API Endpoint:

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

Change to Buyer_Reconciliation_Reject
POST: {url}$apihost/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 PAYLOAD:

Response:
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": {21/33},
        "eligible": 24,
        "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": 20,
                "test": 0,
                "transactions": 24,
                "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
 Warning
CODE: 400 Bad Request
 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
 Warning
CODE: 400 Bad Request
 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
 Warning
CODE: 400 Bad Request
 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
 Warning
CODE: 400 Bad Request
 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"
    }
]
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": 24,
                "rejected": 2,4,
                "completed": 0,
                "test": 0,
                "transactions": 24,
                "transactionsWithDesiredStatus": 0,
                "validCap": true
            }
        ],
        "validCap": true,
        "invoiced": 0,
        "isApiUser": true
    }
}
2 - Reconciliation multiple surveys (Bulk Reconciliation)
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": "46e10177b43ce6a3-c3a39578-42464ba6-a33a8cc5-0c8306f3a9a6a4add094a352",
    "summary": {
        "currentCompletes": 16,
        "previouslyRejectedCompletes": 0,
        "rejectingCompletesInCurrentUpload": 4,
        "acceptingCompletesInCurrentUpload": 0,
        "resultingCompletes": 16,
        "totalRawCompletes": 20,
        "totalRejects": 4,
        "rejectPercentage": "22.50",
        "desiredStatus": {33},
        "eligible": 2, 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": 2,4,
                "completed": 0,
                "test": 0,
                "transactions": 2,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
Screenshot 2024-02-01 at 15.13.02.png
 Info
NOTE 2:
...
 if you need to test the Live Reconciliation API and you want to create some test transactions, please ask your account manager or contact the PureSpectrum product team and they will give you access to a document that will allow you to create a transaction via API.
 Info
NOTE 3: 
...
10pm 
10 pm PT is the absolute latest you can submit a reconciliation for it to be included in the next 
 months 
month's invoice.