> ## Documentation Index
> Fetch the complete documentation index at: https://docs.repdata.com/llms.txt
> Use this file to discover all available pages before exploring further.

# REVIEW

> Text analysis of open-ended survey responses — copy/paste, profanity, engagement, language, and LLM detection.

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>`

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

## GET vs POST

<Tabs>
  <Tab title="GET">
    There is a cap on the number of characters that can be sent on a GET call.

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

  <Tab title="POST">
    POST allows a higher number of characters than GET.

    ```text theme={null}
    POST https://prod.rtymgt.com/api/v4/respondents/review/<publishable_key>
    Content-Type: application/json
    ```

    ```json theme={null}
    {
      "q_id": "[%survey-question-id%]",
      "text": "[%survey text%]",
      "s_text_length": "[%text length%]"
    }
    ```
  </Tab>
</Tabs>

## 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. |

### Recommended

| 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.                                                                  |

<Warning>
  **Redundant parameters.** `profanity_check_score` and `pasted_response` are no longer recommended. Use `profanity_check` and `pasted_response_score` instead.
</Warning>

## Response Example

```json theme={null}
{
  "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](https://docs.repdata.com/research-defender/endpoints/get-api-v4-respondents-review-publishable_key) 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:

```html theme={null}
<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`):

```js theme={null}
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);
  }
};
```

<Tip>
  REVIEW's supported languages are listed in the [REVIEW Supported Languages](https://docs.google.com/spreadsheets/d/1Jfm6_LhEyhDTuAgcaVVUztrCplO_icQQJR5l7ny9-oA/edit?usp=sharing) reference.
</Tip>