PS <> Buyer rules and API instructions

Rules and Instructions:

• Buyer should use these two endpoints created by PureSpectrum:

  • (API) Endpoints 1: YELLOW FLOW - Can validate the Respondent with PureSpectrum:

    • This endpoint is used to Validate the PSID if it belongs to a supplier that agreed to work with a Modular survey - In case the PSID is valid, the endpoint returns a new Transaction ID (modular transaction)

    • Buyer needs to capture from the Buyer/Live URL these 3 parameters:

      • Survey ID: Survey identification → survey_id

      • Supplier ID: Supplier identification → supplier_id

      • Transaction ID: Transaction identification → transaction_id (core transaction)

      • NOTE: Make sure the 3 variables are enabled in Buyer settings

    • ENDPOINT SPECS:

      • https://purespectrum.atlassian.net/wiki/spaces/PRODUCT/pages/2898493452/PS+JD+Power+rules+and+API+instructions#(API)-Endpoints-1%3A-Validate-the-Transaction-and-create-a-new-Transaction

  • (API) Endpoints 2: GREEN FLOW - When the respondent finalizes the screener or the modular study, use this endpoint to register the respondent as Complete

    • ENDPOINT SPECS:

      • https://purespectrum.atlassian.net/wiki/spaces/PRODUCT/pages/2898493452/PS+JD+Power+rules+and+API+instructions#(API)-Endpoints-2%3A-Register-the-Transaction-as-Complete

• Buyer should redirect the Respondent to the PS redirect link /surveydone only at the end of the survey on these 2 occasions:

  • Respondent is not qualified → Buyer terminated (18)

  • Respondent completed the study → Complete (21)

  • In both cases, Buyer has to redirect and pass the 1st Transaction ID (core transaction) received.

    • NOTE: In case Buyer use a Transaction ID generated for a modular survey, the system will continue to accept the value and redirect the respondent to correspondent supplier.

• Buyer - Survey Creation in Marketplace:

  • Create only one single survey and on the Launch page on Marketplace activate the feature Modular Launch

  • Download the report from the survey dashboard (UI) in order to fetch the transaction IDs created through the ENDPOINT 1 (YELLOW FLOW). Use the column "MODULAR Survey“, and filter by the value TRUE

    • Modular Transaction

    • isModularTransaction

Schema:

Buyer Configuration:

• The operator should activate a configuration flag under Configuration Settings - Modular Survey

  • EXAMPLE TO ADD

• Buyer should activate the supplier ID, survey ID, and transaction ID on the Buyer settings page.

  • Buyer Settings:

    

Supplier Configuration:

• Supplier should activate a flag to agree to work with Modular Supplier

  • EXAMPLE TO ADD

Suppliers that agreed to work with Modular Survey:

• Prime

• CPX

API ENDPOINT SPECIFICATION:

(API) Endpoints 1: Validate the Transaction and create a new Transaction

Use this API to validate the Respondent and in case of a valid transaction,

Buyer should send us survey_id, supplier_id, and transaction_id (core transaction) in the API.

POST {{BASE_URL}}/buyers/v2/surveys/SURVEY_ID/transactions?supplier_id=SUPPLIER_ID&transaction_id=TRANSACTION_ID

Body (Optional if data is sent via URL):

{
    "supplier_id": 2,
    "transaction_id": "40AekOxWhKu8hffwcm7LC7"
}

Response (Transaction is valid for next study):

{
    "transaction_id": "01vA34sCj8wffKBmelT6xT"
}

Response (Transaction is NOT valid for next study):

{
    "ps_error_code": 1014,
    "ps_error_message": "Invalid 'transaction_id'."
}

Response (Supplier did NOT agree to Modular Survey):

{
    "ps_error_code": 1014,
    "ps_error_message": "The 'transaction_id' doesn’t belong to a supplier that agrees to Modular Survey."
}

(API) Endpoints 2: Register the Transaction as Complete

Use this API to complete a transaction (modular transaction).

POST {{BASE_URL}}/buyers/v2/surveys/SURVEY_ID/transactions/TRANSACTION_ID/status?st=21

Body:

[]

Response 200 OK:

[]

NOTE:

1. The CPI (BCPI and SCPI) associated for the new transaction created for the modular survey is the same as the original transaction.

2. Use always the original transaction (core TX) to request a new transaction for a respondent eligible for multiple modular study.

3. Modular transactions created via API endpoint 1 (YELLOW FLOW). Should be completed using API endpoint 2.

4. Any core transaction received initially in the buyer URL should be completed or rejected using s/surveyDone endpoint.

Not developed:

1. Assign a different CPI to any new transaction. Buyer might have a different CPI if the respondent complete a modular or long form study.

2. Supplier is not advised if the respondent completed a modular study. They should provide an Endpoint that allow PureSpectrum to send the details.