[v3] Updating the status of a Transaction ID via API
Our updated BUY API documentation is available here.
We hope you enjoy the new experience! Reach out to us with your feedback or questions on supportbuyapi@purespectrum.com
Happy programming! 🎉
This is an updated version of the API described here:
[v2] Updating the status of a Transaction ID via API
This new version returns a faster response and additional useful information in the response body.
Any considerations reported in v2 are valid in this version too.
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/v3
Staging host: https://staging.spectrumsurveys.com/buyers/v3Considerations
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
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 29 - LOI Threshold Termination 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/v3/surveys/:surveyId/transactions/transaction_id/status?st=21Response:
Response Code:
CODE: 200 OK
Response Body:
{
"status": 21,
"status_description": "Complete",
"reconciled": false,
"reconciliation_info": null
}If the user pass an Invalid QLC code then our system sends the below message with 200 OK status
Request:
https://staging.spectrumsurveys.com/buyers/v3/surveys/1110947/transactions/4sPkoWpKAUIJDRtGSxqok4/status?st=21"a_id=M,F,S,PL,MR,D,W,EResponse :
Response Code:
CODE: 200 OK
Response Body:
{
"status": 59,
"status_description": "Missing_QLC_Code",
"reconciled": false,
"reconciliation_info": null
}Response Errors:
Example 1:
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, or the transaction status is other than 16 & 19 then it will throw the error as shown in the below example -
Response Code:
CODE: 400 BAD
Response Body:
{
"ps_api_response_code": 1003,
"ps_api_response_message": "Only transactions with status of 16 & 19 allowed to be updated. This transaction id has a status of 21."
}Example 2:
If the transaction doesn’t belong to the survey given in the request, then the below error message will be displayed with 400 Bad Request.
Response Body:
{
"ps_api_response_code": 1014,
"ps_api_response_message": "This Transaction ID does not exist for the Survey ID. Please check the Survey ID and Transaction ID and try again."
}Example 3:
If the user sends an Invalid status code, then the below error message will be displayed with 400 Bad Request. Valid status codes are 17, 18, 20, 21, 29 and 30.
Response Body:
{
"ps_api_response_code": 1001,
"ps_api_response_message": "Invalid status code"
}Example 4:
If the user doesn't pass the status code in the request, then the below error message will be displayed with 400 Bad Request.
Response Body:
{
"ps_api_response_code": 1002,
"ps_api_response_message": "Missing parameters (st)- please check your request"
}Example 5:
If the user passes invalid disposition info, then the below error message will be displayed with 400 Bad Request.
Request:
https://staging.spectrumsurveys.com/buyers/v3/surveys/1110947/transactions/4sPkoWpKAUIJDRtGSxqok4/status?st=21&211=111113Response Body:
{
"ps_api_response_code": 1003,
"ps_api_response_message": "Disposition info 211=1112 is not valid"
}Example 6:
If the user tries to update the transaction status by using another buyer access token that does not belong to the transaction, then the below error message will be displayed with 403 Forbidden
Response Code:
CODE: 403 Forbidden
Response Body:
{
"ps_api_response_code": 9999,
"ps_api_response_message": "Not authorized to access transaction id"
}Example 7:
If the user tries to update the transaction status by using an Invalid access-token then the below error message will be displayed with 401 Unauthorized
Response Code:
CODE: 401 Unauthorized
Response Body:
{
"ps_api_response_code": 1012,
"ps_api_response_message": "Invalid access token"
}