PS <> JD Power rules and API instructions

Rules and Instructions:

• JD Power 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)

    • JD Power 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 DOCUMENTS HERE

      • https://purespectrum.atlassian.net/wiki/spaces/PRODUCT/pages/edit-v2/2898493452#(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 DOCUMENTS HERE

      • https://purespectrum.atlassian.net/wiki/spaces/PRODUCT/pages/edit-v2/2898493452#(API)-Endpoints-2%3A-Register-the-Transaction-as-Complete

• JD Power 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, JD Power has to redirect to the 1st Transaction ID (core transaction) received.

• JD Power - Survey Creation in Marketplace:

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

  • To check the transaction ID that belongs to a "MODULAR Survey“, you can filter by this field name:

    • FIELDNAME TO ADD

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

Suppliers that agreed to work with Modular Survey:

• Supplier 1

• Supplier 2

• Supplier 3

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,

JDPA 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. Modular transactions created via API endpoint 1 can only be completed using API endpoint 2.

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