Versions Compared

Version Old Version 1 New Version Current
Changes made by

David Boyajian

Akhil Veeramallu

Saved on

Key

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

This endpoint is not available on staging or production. The documentation is hidden from external users.

An external system may update a transaction in PureSpectrum for a number of reasons such as:

...

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. In order to make a successful request, one of two sets of parameters must be present:

    • Scenario 1 - Buyer calls API with parameters for:

      • supplierId

      • supplierRespondentId

      • supplierRespondentSessionId

    • Scenario 2 - Buyer calls API with old transaction ID:

      oldTransactionId

      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

supplierId

st

integer - enum (17, 18, 20, 21, 30)

This is the PureSpectrum

supplier ID. An incorrect supplier ID, or the supplier ID of a supplier not currently allocated to the survey should result in an http 400 error.

37

supplierRespondentId

string

This is the persistent member ID of the respondent

abc123

supplierSessionId

string

This is the unique session identified provided by the supplier

1513326965960

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: 

Code Block
languagejs
POST api.spectrumsurveys.com/buyers/v2/surveys/:surveyId/transactions?supplier/transaction_id/status?st=221&memberquota_id=3&session_id=41,2,3

Response:

Response Code:

201200

Response Body:

Code Block
[]

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:

Code Block
{
    "ps_error_code": 1003,
    "ps_error_message": "This transaction id already has a final status"
}

Postman example:

...

Other Error Messages:

Code Block
languagejs
{ 
	"ps_error_code": 1001,
	"ps_error_message":"InvalidIncorrect supplierstatus IDcode"
},

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