PureText Buyer API V3

Description: 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 response deduplication.

PureText Deduplication: Ensures the OE response is unique through deduplication.
Language Mismatch: Compares the language of the OE response with the survey language determined from the transaction ID.
AI Detection: Detects patterns to flag if the OE response is AI-generated content.
Incoherent Response: Flags the obviously unacceptable responses such as gibberish, curse words, etc

PureText can be effectively used:

For expected responses with at least one meaningful sentence (unlike categorical responses such as brand names, people and place names, etc)
Expected responses are in the same language as survey language (if the survey is in French, response should be only in French)

The API call can be made in two ways:

Individual response: after every open-ended question , or
Bulk processing: at the end of the survey for ALL open-ended responses

In either case, the API response shows you the result for each answer separately.

Please note: Upto 20 open-ended responses that can be processed in bulk at a time.

Request

POST $apihost/$basepath/v3/transactions/ps_api_fail

($apihost is the environment against which you are testing, $basepath is the base path with the api version. All Buy API calls will require access-token parameter in the header.)

Parameters for 1 OE response:

Body:

{
    "transaction_id": "4mWpY50Z5ZpovKkXjt7Liw",
    "questions": [
        {
            "question_id": alpha numeric,
            "text": "string"
        }
    ]
}

Result:

API Response Body:

{
    "transaction_id": "4mWpY50Z5ZpovKkXjt7Liw",
    "data": [
        {
            "puretext_api_fail": 0,
            "ai_generated_response": 0,
            "incoherent_response": 0,
            "duplicate_response": 0,
            "language_mismatch": 0,
            "question_id": “alpha numeric”
        }
    ]
}

Parameters for 2+ OE responses:

Body:

{
    "transaction_id": "4mWpY50Z5ZpovKkXjt7Liw",
    "questions": [
        {
            "question_id": alpha numeric,
            "text": "string"
        },
        {
            "question_id": alpha numeric,
            "text": "string"
        }
    ]
}

Result:

API Response Body:

{
    "transaction_id": "4mWpY50Z5ZpovKkXjt7Liw",
    "data": [
        {
            "puretext_api_fail": 0,
            "ai_generated_response": 0,
            "incoherent_response": 0,
            "duplicate_response": 0,
            "language_mismatch": 0,
            "question_id": “alpha numeric”
        },
        {
            "puretext_api_fail": 0,
            "ai_generated_response": 0,
            "incoherent_response": 0,
            "duplicate_response": 0,
            "language_mismatch": 0
            "question_id": "alpha numeric"
        }
    ]
}

If "puretext_api_fail": 1we recommend to terminate the session with status code 84. However, you can create your own termination logic with all the information provided.

For example, if you have a survey which is in French but also accepts English responses, to not terminate sessions where "language_mismatch": 1.

URL: https://spectrumsurveys.com/surveydone?st=84&transaction_id=[transaction_id]

Response Codes:

200 OK: The validation process was completed successfully.
400 Bad Request: Invalid input or missing fields in the payload.

Error:

The API can only be used for valid transactions.

{
    "ps_api_response_code": 1014,
    "ps_api_response_message": "Invalid transaction"
}

The API requires all parameters to be valid and present.

{
    "ps_api_response_code": 1014,
    "ps_api_response_message": "Invalid parameters: Answer Text, Question Code/Id or Transaction Id is missing."
}

Example for a termination due to AI detection:

POST https://spectrumsurveys.com/buyers/v3/transactions/ps_api_fail

Body:

{
    "transaction_id": "4mWpY50Z5ZpovKkXjt7Liw",
    "questions": [
        {
            "question_id": 123A,
            "text": "As an AI language model I don't have a personal opinion."
        }
    ]
}

API Response which results in a termination:

{
    "transaction_id": "4mWpY50Z5ZpovKkXjt7Liw",
    "data": [
        {
            "puretext_api_fail": 1,
            "ai_generated_response": 1,
            "incoherent_response": 0,
            "duplicate_response": 0,
            "language_mismatch": 0,
            "question_id": “123A”
        }
    ]
}

Example for a termination due to PureText Deduplication:

POST https://spectrumsurveys.com/buyers/v3/transactions/ps_api_fail

Body:

{
    "transaction_id": "4mWpY50Z5ZpovKkXjt7Liw",
    "questions": [
        {
            "question_id": ABC987,
            "text": "I prefer white chocolate over any other chocolate."
        }
    ]
}

API Response which results in a termination:

{
    "transaction_id": "4mWpY50Z5ZpovKkXjt7Liw",
    "data": [
        {
            "puretext_api_fail": 1,
            "ai_generated_response": 0,
            "incoherent_response": 0,
            "duplicate_response": 1,
            "language_mismatch": 0,
            "original_transaction_id": 3rWnTCAisTABjZEa2P3ZMF,
            "question_id": “ABC987”
        }
    ]
}

When processing "transaction_id": "4mWpY50Z5ZpovKkXjt7Liw" we found a duplicate answer which was first stated by "original_transaction_id": 3rWnTCAisTABjZEa2P3ZMF.

Example which processes 2 OE responses:

POST https://spectrumsurveys.com/buyers/v3/transactions/ps_api_fail

Body:

{
    "transaction_id": "4mWpY50Z5ZpovKkXjt7Liw",
    "questions": [
        {
            "question_id": 1573,
            "text": "I prefer dark chocolate over white chocolate. "
        },
        {
            "question_id": 1575,
            "text": "I prefer white chocolate over dark chocolate. "
        }
    ]
}

API Response:

{
    "transaction_id": "4mWpY50Z5ZpovKkXjt7Liw",
    "data": [
        {
            "puretext_api_fail": 0,
            "ai_generated_response": 0,
            "incoherent_response": 0,
            "duplicate_response": 0,
            "language_mismatch": 0,
            "question_id": 1573
        },
        {
            "puretext_api_fail": 0,
            "ai_generated_response": 0,
            "incoherent_response": 0,
            "duplicate_response": 0,
            "language_mismatch": 0,
            "question_id": 1575
        }
    ]
}