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

# SEARCH

> Digital fingerprinting, bot and click-farm detection, and duplication scoring at survey entry.

SEARCH provides industry-leading digital fingerprinting, including bot detection and click-farm detection. Call it as a respondent enters your survey to score fraud risk and detect duplicates.

* **Type:** GET
* **Endpoint:** `/api/v4/respondents/search/<publishable_key>`

```text theme={null}
https://prod.rtymgt.com/api/v4/respondents/search/<publishable_key>?sn_ud=170716409&sy_nr=20210575&rt_cy_ce=us
```

<Note>
  For Research Defender to access a respondent's cookies on the browser side, the request must allow credentials. In a JavaScript implementation set `withCredentials = true`. See [Environments & Authentication](https://docs.repdata.com/research-defender/overview/01-environments-and-authentication).
</Note>

## Input Parameters

### Required

| Parameter | Data Type    | Description                                                                                         |
| --------- | ------------ | --------------------------------------------------------------------------------------------------- |
| `sn_ud`   | User-defined | Unique identifier for each API call. Do not reuse across surveys or respondents — GUID recommended. |
| `sy_nr`   | User-defined | Unique identifier for the client survey, consistent for each survey.                                |

### Recommended

| Parameter  | Data Type          | Description                                                   |
| ---------- | ------------------ | ------------------------------------------------------------- |
| `rt_cy_ce` | ISO 3166-1 alpha-2 | Survey country code, so SEARCH can detect country mismatches. |

### Optional

| Parameter     | Data Type    | Description                                                                                                                                     |
| ------------- | ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| `rt_sr_pd`    | User-defined | Persistent respondent identifier for deduplication. **Only use if you have independently verified respondent identity.**                        |
| `pm_sr_id`    | User-defined | Supplier ID (name, abbreviation, or numeric) for backend reporting.                                                                             |
| `sy_gp_nr`    | User-defined | Survey group identifier to deduplicate respondents across surveys. Only use if a survey-group lockout is needed.                                |
| `set_window`  | Integer      | Lockout period in days. Returns `days_flag=1` if the respondent attempted the survey within fewer days than the window. Available in v3 and v4. |
| `coordinates` | `=1`         | Include coordinate-related attributes (latitude, time\_zone, weather\_code, state\_name).                                                       |
| `wd`          | `=1`         | Include the recent date of a survey transaction (`d_date`).                                                                                     |
| `mm`          | `=0`         | Disable MaxMind termed-failure detection (`failure_reason=18`).                                                                                 |
| `csipqs`      | `=1`         | Include an IPQS `fraud_score` result.                                                                                                           |
| `df_details`  | `=1`         | Include an additional dataset with respondent information.                                                                                      |
| `sip`         | —            | Control whether the IP address is shown on the response.                                                                                        |

## Recommended Response Parameters

| Parameter                | Data Type    | Description                                                                                        |
| ------------------------ | ------------ | -------------------------------------------------------------------------------------------------- |
| `threat_potential_score` | Float        | 1 (lowest threat) to 99 (highest threat), based on dozens of checks and the failure reasons below. |
| `failure_reason`         | String       | Populated when `threat_potential_score >= 31`. See the codes below.                                |
| `duplicate_score`        | Float        | `100` if the respondent is a duplicate, `0` if unique.                                             |
| `duplicate_initial_ud`   | User-defined | For a duplicate, the `sn_ud` of the respondent's most recent prior attempt at this survey.         |
| `country_code`           | Text         | Geolocated country of the respondent (ISO 3166-1 alpha-2).                                         |
| `country_mismatch`       | Boolean      | `1` if the respondent's country differs from `rt_cy_ce`, else `0`.                                 |
| `respondent_ud`          | GUID/UUID    | Stable identifier tracking a respondent across sessions and surveys.                               |

### Failure Reason Codes

| Code | Meaning                               | Code | Meaning                            |
| ---- | ------------------------------------- | ---- | ---------------------------------- |
| `02` | Duplicate entrant into survey         | `13` | Duplicate survey group detected    |
| `03` | User emulator                         | `14` | Navigator Webdriver detected       |
| `04` | VPN usage detected                    | `15` | Developer tool detected            |
| `05` | TOR network detected                  | `16` | WebRTC IP address                  |
| `06` | Public proxy server detected          | `17` | Proxy detected                     |
| `07` | Web proxy service used                | `18` | External provider failure detected |
| `08` | Web crawler usage detected            | `19` | Batch fraud entrants               |
| `09` | Internet fraudster detected           | `20` | ChatGPT/Claude emulators           |
| `10` | Retail and ad-tech fraudster detected | `21` | Previous explicit behavior         |
| `11` | IP address subnet detected            | `22` | Obfuscation mechanisms detected    |
| `12` | Recent abuse detected                 |      |                                    |

## Advanced Response Parameters

| Parameter                                                | Data Type      | Description                                                                                   |
| -------------------------------------------------------- | -------------- | --------------------------------------------------------------------------------------------- |
| `days_flag`                                              | Integer        | Only populates if `set_window` is used. `1` means the respondent attempted within the window. |
| `latitude` / `state_name` / `time_zone` / `weather_code` | —              | Populate when `coordinates=1`.                                                                |
| `d_date`                                                 | DateTime (UTC) | Populates when `wd=1`; most recent transaction at the survey level.                           |
| `vpt`                                                    | Integer        | If `vpt=check` is passed, returns `1` if the request is via VPN, else `0`.                    |
| `usage_type`                                             | String         | If `usage_type=1` is passed, returns `consumer`, `corporate`, or `hosting`.                   |
| `df_details`                                             | String         | Additional respondent dataset when `df_details=1` is passed.                                  |

<Warning>
  **Redundant parameters.** `flag`, `duplicate_potential`, `threat_potential`, `country`, and `respondent_risk` are no longer recommended — their outputs are redundant with the recommended parameters above. Use `duplicate_score`, `threat_potential_score`, and `country_code` instead.
</Warning>

## Response Example

```json theme={null}
{
  "Respondent": {
    "threat_potential_score": "23",
    "country": "United States",
    "country_code": "US",
    "respondent_risk": 0,
    "respondent_ud": "4489560a-507f-468a-ae4b-d81ea80fab5d",
    "time_zone": "America/Chicago"
  },
  "Surveys": [
    {
      "flag": 1,
      "duplicate_initial_ud": "481cd5cf-88f1-44c2-8292-6b779b8a3a8e",
      "duplicate_potential": "high",
      "duplicate_score": "100",
      "country_mismatch": 0,
      "failure_reason": "02",
      "days_flag": 1,
      "days_difference": 0
    }
  ]
}
```

See the [SEARCH endpoint reference](https://docs.repdata.com/research-defender/endpoints/get-api-v4-respondents-search-publishable_key) for the full parameter list and a live playground.

## Advanced Fingerprint Detection

For Developer Tools and WebRTC IP address detection, include the Research Defender JavaScript system utility library, `rd_sys_util.min.js`:

```text theme={null}
https://prod.rtymgt.com/static/js/rd_sys_util.min.js
```

* The library is built as a **module** — load it with `type="module"`.
* Apply a refresh interval of **500ms or less** so data returns properly.
* The `pass_params` property is the combined, encrypted dataset detected from the respondent's browser; pass it directly on the SEARCH call (no parameter name). The `to_object` function parses JSON results into objects.

```js theme={null}
import { pass_params, to_object } from 'https://prod.rtymgt.com/static/js/rd_sys_util.min.js'
```

```text theme={null}
v3: <environment>/api/v3/respondents/search/<publishable_key>?sy_nr=<survey_number>&sn_ud=<unique_identifier>&<pass_params>

v4: <environment>/api/v4/respondents/search/<publishable_key>?sy_nr=<survey_number>&sn_ud=<unique_identifier>&validation=<hashed url value with private key>&<pass_params>
```

<Tip>
  Research Defender publishes [recommended term logic](https://docs.google.com/document/d/1B5bJScX0kQzzCsrWqzgF46rV44ciYiEu16bgZutoK7w/edit?usp=sharing) for translating SEARCH scores into accept/term decisions.
</Tip>