Versions Compared

Version Old Version 22 New Version Current
Changes made by

Claudio Baldi

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}

...

  • 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}$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:

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
    }
}

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
    }
}

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": "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

...