PureText Buyer API Integration in Qualtrics

OVERVIEW 

This API checks for the Open-Ended (OE) survey responses to ensure data quality. It performs language comparison, AI-generated answer detection, exclusion list checks, and PureText deduplication. Below is the processing flow: 

• Language Compare: Compares the language of the OE answer with the survey language determined from the transaction ID
• AI Detection: Detects whether the answer is AI-generated
• Exclusion List: Checks if the answer is in an exclusion list of undesirable responses
• PureText Deduplication: Ensures the answer's uniqueness through deduplication

Pre-Requisites

• Need to add below host names in the decipher directory. 
  • For Production: https://spectrumsurveys.com/ 
  • For Staging: https://staging.spectrumsurveys.com/
• API Access token 
• Valid transaction_id 
• question_id: string or number or alpha numeric.  
  • Examples are Q1, S1 etc. 
• text: Survey Response to validate.  
• Endpoint 
  • POST /buyers/v3/transactions/ps_api_fail 

How to get API access token from Market Place 

If you are an API user, you already have a API access token or one could be created for you. Please contact your Account manager to know how to get the access token for your account. 

How to Program in Qualtrics

Login into Qualtrics platform and open/create your project and follow the steps outlined below.

Step 1: Create transaction_id as embedded variables

• Click on Survey Flow
• Click on Add a New Element, click on Embedded Data
• Add “transaction_id” as an Embedded Data element
• Move this element to the top of the Survey Flow

Step 2: Create a group after the block, which contains open end questions to add API request for validation and to add termination.

• Click on Add a New Element, click on Group and name it
• Click on Add a New Element within the group, click on Web Service and name it.
• Please fill API URL, Method, Query/Body parameters, custom header(access-
  token) and set embedded data with results. See Details below.

[ 
       { 
  "question_id": "Q1", 
  "text": "${q://QID179/QuestionText}" 
       }, 
       { 
  "question_id": "Q2_other", 
  "text": "${q://QID183/ChoiceTextEntryValue/4}" 
       } 
   ] 

We have taken two questions to build this example (i.e. Q1 and Q2).

Example

 

 

Step 3: Create 11 embedded variables with the below names to capture the consolidated results. (Click on Add a New Element, click on Embedded Data.)

1. PT_puretext_api_fail_Result_Set1: Indicates the count of all the flags where the respondents failed. For example, if the respondent was flagged due to incoherent response at Q1 and language mismatch at Q2. Then this count will be 2 (consolidated count). 
2. PT_puretext_api_fail_QIDs_Set1: Indicates the question ids (with comma separation) which the respondents failed.  For example, if the respondent was flagged due to incoherent response at Q1 and language mismatch at Q2. Then it shows “ Q1, Q2” 
3. PT_ai_generated_response_COUNT_Set1: Indicates the count of all questions where the respondent failed due to AI generated text.  
4. PT_ai_generated_response_QIDs_Set1: Shows the list of all question ids with the comma separation where the respondent failed due to AI generated text. 
5. PT_incoherent_response_COUNT_Set1: Indicates the count of all questions where the questions failed due to incoherent/junk response.   
6. PT_incoherent_response_QIDs_Set1: Shows the list of all question ids with the comma separation where the questions are failed due to incoherent/junk response. 
7. PT_duplicate_response_COUNT_Set1: Indicates the count of all questions where the questions failed due to duplicate response.  
8. PT_duplicate_response_QIDs_Set1: Shows the list of all question ids with the comma separation where the questions failed due to duplicate response. 
9. PT_language_mismatch_COUNT_Set1: Indicates  the count of all questions where the questions are failed due to language mismatch.  
10. PT_language_mismatch_QIDs_Set1:  Shows the list of all question ids with the comma separation where the questions are failed due to language mismatch. 
11. PT_original_transaction_dedupe_id: Only in case of PT Deduplicate fail, this shows the list of all question ids and the original transaction_id that was duplicated from. 

Step 4: Then, please add a Text/Graphic screen before the embedded variables created in step 3. We will add java script in this node to set the values for embedded variables, add below style tag in question text along with “Please wait...” text.

<style type="text/css">#NextButton,#Questions { 
  display: none; 
} 
</style>

And then please copy the script below into the Java script area which will be opened if you click on above green highlighted area. 

Step 5: Then, please update the yellow highlighted arrays with the embedded variables created to store the Puretext API results in Step 2 as shown in the code. 

Step 6: Termination Process, create branch and add the below condition for termination.

• Click on Add a New Element, click on branch and add condition on embedded variables created based on PT_puretext_api_fail_Result_Set1.
  • Greater than or equal to 1 is Failed
  • 0 is Successful
• To terminate the session, add the End of Survey element within this branch. At this point the respondent session can be terminated (if >=  1) or let to continue (if==0) based on the API call response.
• Click on the option Customize and reference the below screenshot to set the fields as below.

Step 7: Important - Click on Apply to save changes.

Possible Errors