REVIEW - Research Desk Documentation

REVIEW provides text analysis of open-ended survey responses, producing a composite quality score along with copy/paste, profanity, engagement, language, and LLM-detection signals.

Type: GET or POST
Endpoint: /api/v4/respondents/review/<publishable_key>

There is a JavaScript portion of this integration (below) that is required for the copy/paste and timestamp functionality.

GET vs POST

GET
POST

There is a cap on the number of characters that can be sent on a GET call.

https://prod.rtymgt.com/api/v4/respondents/review/<publishable_key>?q_id=[%question-id%]&text=[%survey text%]&s_text_length=[%text length%]&question=[%question%]

POST allows a higher number of characters than GET.

POST https://prod.rtymgt.com/api/v4/respondents/review/<publishable_key>
Content-Type: application/json

{
  "q_id": "[%survey-question-id%]",
  "text": "[%survey text%]",
  "s_text_length": "[%text length%]"
}

Input Parameters

Required

Parameter	Data Type	Description
`q_id`	User-defined	Identifier for each survey question.
`text`	User-defined	Text entered by the respondent.
`sn_ud`	User-defined	Unique session identifier (GUID recommended).
`sy_nr`	User-defined	Unique identifier for the client survey.
`question`	Text	The survey question, which drives the contextual analysis.

Parameter	Data Type	Description
`c_text`	Text	Pasted text from the JS library, base64-encoded.
`s_text_length`	Text	Minimum number of characters needed to run the similarity check.
`t_page_load`	Float	Page-load time, base64-encoded.
`t_text_typed`	Float	Time when typing started, base64-encoded.
`t_submit`	Float	Time on submit, base64-encoded.

Recommended Response Parameters

Parameter	Data Type	Description
`composite_score`	Integer	Primary measure of response quality, combining copy/paste, profanity, engagement, language, and more. The individual inputs are also returned so you can build custom rules.
`similarity_text`	Integer	`1` if a duplicate open-end is detected (based on `s_text_length`).
`profanity_check`	Integer	`1` if profanity is detected, else `0`.
`model`	Object	Whether the response is contextually correct relative to the question, and whether it appears LLM-generated.

Additional Response Parameters

Parameter	Data Type	Description
`language_detected`	Text	Language used in the response (e.g. English, French).
`language_detected_score`	Float	Confidence interval (`.01` ≈ 99.9% confidence).
`pasted_response_score`	Float	Share of the answer pasted from the clipboard (e.g. `0.4` = 40%).
`engagement_score`	Float	Response length relative to others for the same question ID (`1` = average, `<1` shorter, `>1` longer).
`page_view_time`	Float	Time from page load to submit (ms). Stand-alone; not part of the composite score.
`typed_response_time`	Float	Time from entering text to submit (ms). Stand-alone; not part of the composite score.
`similarity_text_length`	Integer	Echoes the `s_text_length` value sent.

Redundant parameters. profanity_check_score and pasted_response are no longer recommended. Use profanity_check and pasted_response_score instead.

Response Example

{
  "model": {
    "rw_context_risk_score": 12,
    "rw_context_risk_level": "low",
    "rw_context_description": "Yes, contextually correct",
    "rw_llm_risk_score": 1,
    "rw_llm_risk_level": "low",
    "rw_llm_description": "LLM not detected"
  },
  "input": {
    "sy_nr": "test",
    "q_id": "3333",
    "question": "How satisfied are you with the current product features?",
    "sn_ud": "T_test",
    "text": "I am very satisfied because the features meet all my needs.",
    "similarity_text_length": "50"
  },
  "score": {
    "composite_score": 0,
    "similarity_text": 1,
    "profanity_check": 0,
    "engagement_score": 1,
    "language_detected": "English",
    "language_detected_score": 0.01,
    "pasted_response_score": 0,
    "page_view_time": 0,
    "typed_response_time": 0,
    "pasted_response": 0
  }
}

See the REVIEW endpoint reference for the full parameter list and a live playground.

Enabling the Copy/Paste JavaScript Library

The copy/paste and timestamp functionality requires the REVIEW JS library. Include it on the page header:

<script src="https://prod.rtymgt.com/static/js/review/sc_review_lib_secured_v1-2.min.js?v=1.0.1" type="text/javascript"></script>

Then initialize scReviewLib with your environment, publishable key, an element-ID object, and the four listeners (pageLoadListener, copyPasteListener, textEventListener, submitEventListener):

window.onload = function () {
  var objElement = {
    textElementId               : '[text_element_id]',
    pastedTextElementId         : '[encoded_pasted_text_element_id]',
    pageLoadTextTimeElementId   : '[encoded_page_load_time_text_element_id]',
    entryStartTextTimeElementId : '[encoded_typed_time_text_element_id]',
    submitTextTimeElementId     : '[encoded_submit_time_text_element_id]',
    submitButtonElementId       : '[submit_button_id]'
  };

  try {
    new scReviewLib(
      'https://prod.rtymgt.com', // [server]
      '[publishable_key]',       // client's publishable key
      objElement,
      pageLoadListener,
      copyPasteListener,
      textEventListener,
      submitEventListener
    );
  } catch (e) {
    document.write(e);
  }
};

REVIEW’s supported languages are listed in the REVIEW Supported Languages reference.

​GET vs POST

​Input Parameters

​Required

​Recommended

​Recommended Response Parameters

​Additional Response Parameters

​Response Example

​Enabling the Copy/Paste JavaScript Library

GET vs POST

Input Parameters

Required

Recommended

Recommended Response Parameters

Additional Response Parameters

Response Example

Enabling the Copy/Paste JavaScript Library