Updating the status of a Transaction ID via API
- David Boyajian
- Akhil Veeramallu
- Chad Nuesmeyer
- Claudio Baldi
An external system may update a transaction in PureSpectrum for a number of reasons such as:
Making sure all completes are properly captured
Verifying authenticity of a complete
Recording a complete on an Augment survey
This API should not be used with the “Register Completes” API endpoint
Request
POST $apihost/$basepath/surveys/:survey_id/transactions/:transactionId/status
($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)
Production host: https://api.spectrumsurveys.com/buyers/v2
Staging host: https://staging.spectrumsurveys.com/buyers/v2
Considerations
Behavior - If the POST /status endpoint is called, and the respondent is later redirected to PureSpectrum via the /surveydone redirect, the status of the original API call will be trusted as the source of truth.
For example - the API call is made with st=18 (termination), but the respondent is redirected later with st=21 (complete), we will continue to recognize the transaction as a termination.
Required Parameters must be present in the query string:
Status - st
Optional Parameters
QLC Codes - quota_id
Transaction can be changed only if is on these 3 states:
Buyer side in progress
Buyer drop
PS LOI threshold
API Parameters:
Request Parameter | Type | Description | Example |
|---|---|---|---|
st | integer - enum (17, 18, 20, 21, 30) | This is the PureSpectrum status code. Pass in the appropriate code corresponding to your desired status. 17 - OverQuota 18 - Termination 20 - Quality Termination 21 - Complete 30 - Dedupe | st=21 |
quota_id | string - comma separated values | This is the identifier of the quotas for which the respondent has qualified for. | abc123 |
Sample Request:
POST /buyers/v2/surveys/:surveyId/transactions/transaction_id/status?st=21"a_id=1,2,3Response:
Response Code:
200
Response Body:
[]Other examples:
Once the survey respondent status is passed as “complete” through /surveydone endpoint, it is the final status of that transaction id. If tried to update the transaction using /status endpoint again, then it will throw the error as shown in below example -
Response Code:
400
Response Body:
{
"ps_error_code": 1003,
"ps_error_message": "This transaction id already has a final status"
}Postman example:
Other Error Messages:
{
"ps_error_code": 1001,
"ps_error_message":"Incorrect status code"
},
{
"ps_error_code": 1002,
"ps_error_message":"Insufficient parameters - please check your request"
},
{
"ps_error_code": 1004,
"ps_error_message":"Transaction ID Not found. Please check the survey id and transaction ID and try again."
},
{
"ps_error_code": 1005,
"ps_error_message":"Invalid or missing QLC codes"
}