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

## Core Functionality

* Advanced digital fingerprinting using browser characteristics, device information, and behavioral patterns
* Bot detection and automated traffic identification
* VPN, proxy, and TOR network detection
* Professional survey taker identification through ecosystem intelligence
* Cross-survey and cross-platform deduplication
* Geolocation verification and country mismatch detection
* Real-time threat scoring from 1 (lowest) to 99 (highest threat)
* Comprehensive failure reason reporting with specific threat categories

## Key Features

* **Threat Potential Scoring:** Provides numerical scores (1–99) based on comprehensive analysis
* **Duplicate Detection:** Identifies repeat attempts across surveys and time periods
* **Geographic Verification:** Validates respondent location against expected parameters
* **Device Intelligence:** Analyzes browser, operating system, and hardware characteristics
* **Network Analysis:** Detects suspicious network usage including proxies and VPNs
* **Ecosystem Intelligence:** Leverages data from millions of tracked respondents

## Typical Use Cases

* Survey entrance screening and qualification
* Real-time quality assessment during survey progression
* Post-completion data validation and cleaning
* Cross-platform respondent verification
* Professional survey taker identification

## Integration Options

<CardGroup cols={2}>
  <Card title="Basic Integration" icon="code" href="/research-defender/guides/search/02-basic-integration">
    Call SEARCH from the browser with your survey number and session ID, using GET or POST.
  </Card>

  <Card title="Advanced Integration (JS Library)" icon="js" href="/research-defender/guides/search/03-advanced-integration">
    Add the Research Defender JavaScript library to collect extra device datasets for a more complete result.
  </Card>

  <Card title="Server-to-Server Integration" icon="shield-halved" href="/research-defender/guides/search/04-s2s-integration">
    Get a token in the browser and call SEARCH from your server so scores and flags never reach the client.
  </Card>

  <Card title="Encrypted Integration" icon="lock" href="/research-defender/guides/search/05-encrypted-integration">
    Request an AES-256-GCM encrypted response in the browser and decrypt it on your server.
  </Card>

  <Card title="URL Validation" icon="badge-check" href="/research-defender/guides/search/06-validated-integration">
    Sign the request URL with your private key so SEARCH rejects any URL changed in transit.
  </Card>
</CardGroup>

## 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 | Panelist ID, if any. **Only use if you have independently verified respondent identity.** |
| `rt_hd_el` | User-defined | Hashed email, if any. |
| `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 window in days. Returns `days_flag=1` if the respondent attempted the survey within the window. Available in v3 and v4. |
| `coordinates` | `=1` | Include geolocation, time zone, and weather attributes (`latitude`, `longitude`, `time_zone`, `weather_code`, `state_name`). |
| `wd` | `=1` | Include the last transaction date (`d_date`). |
| `vpt` | `=check` | Check VPN status. |
| `usage_type` | `=1` | Return the network usage type. |
| `df_details` | `=1` | Return an additional dataset with respondent information. |
| `mm` | `=1` | Disable MaxMind termed-failure detection (`failure_reason=18`). |
| `csedp3` | `=1` | Provide a result from the EDP score (`EDP3` node). |
| `sip` | `=1` | Show the IP address on the API response. |
| `sisp` | `=1` | Provide the ISP (Internet Service Provider). |
| `dupe_details` | `=1` | Show the corresponding details for the duplicate (`dupes_details`). |
| `mfr` | `=1` | Provide every triggered failure reason (`multiple_failure_reason`), not just one. |
| `tbc` | `=1` | Allows testers to bypass checks. For testing only. |
| `validation` | SHA-256 | Signs the request URL for additional security. Only available to selected clients. See [URL Validation](/research-defender/guides/search/06-validated-integration). |

## Recommended Response Parameters

| Parameter | Data Type | Description |
| - | - | - |
| `threat_potential_score` | Float | 1 (lowest threat) to 99 (highest threat). Calculated internally from fraud signals, device fingerprinting (bot and automation detection, virtual environments, anti-detect browsers), and behavioral checks (batch-entrant patterns, rare user agents, country and screen mismatches). |
| `failure_reason` | String | If the request is termed, the reason as one of 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 SEARCH detected the respondent outside the country in `rt_cy_ce`, else `0`. |
| `respondent_ud` | GUID/UUID | Identifier that tracks a respondent across sessions. The same respondent attempting different surveys at different times has the same `respondent_ud`. |

### Failure Reason Codes

| Code | Meaning |
| - | - |
| `02` | Duplicate Entrant into Survey |
| `03` | User Emulator |
| `04` | VPN Usage Detected |
| `05` | TOR Network Detected |
| `06` | Public Proxy Server Detected |
| `07` | Web Proxy Server Used |
| `08` | Web Crawler Usage Detected |
| `09` | Internet Fraudster Detected |
| `10` | Retail and Ad-Tech Fraudster Detected |
| `11` | IP Address Subnet Detected |
| `12` | Recent Abuse Detected |
| `13` | Duplicate Survey Group Detected |
| `14` | Navigator Webdriver Detected |
| `15` | Developer Tool Detected |
| `16` | WebRTC IP Address |
| `17` | T-Mobile Proxy Detected |
| `18` | Maxmind Failure Detected |
| `19` | Batch Fraud Entrants |
| `20` | ChatGPT/Claude Emulators |
| `21` | Previous Explicit Behavior |
| `22` | Obfuscation Mechanisms Detected |
| `23` | SEARCH Locale Detected |
| `24` | Static Blacklist |
| `25` | Bot Detected |

The same codes are returned by the [FAILURE\_REASON](/research-defender/endpoints/get-api-v2-respondents-reason_codes) lookup.

## Advanced Response Parameters

### Surveys node

| Parameter | Description |
| - | - |
| `sn_ud` | The respondent's unique session ID. |
| `survey_number` | The survey number, as sent in `sy_nr`. |
| `flag` | `1` if the respondent accessed the survey previously, `0` if not. |
| `duplicate_potential` | Redundant response for `duplicate_score`. |
| `duplicate_fingerprint_weight_score` | For a duplicate fingerprint, a score from 0 to 100. |
| `destination` | Unique identifier for the destination platform or buyer. |
| `d_date` | Populates when `wd=1`: the most recent transaction at the survey level. |
| `days_flag` | Only populates if `set_window` is used. `1` means the respondent attempted the survey within the window, `0` means not. For example, with `set_window=30` and an attempt 26 days ago, `days_flag` is `1`. |
| `days_difference` | Works with `set_window`: the difference in days since the previous attempt. |
| `dupes_details` | Codes for detailed duplicate details. Populates when `dupe_details=1`. See [DUPLICATE\_DETAILS](/research-defender/endpoints/get-api-v2-respondents-dupe_details). |
| `multiple_failure_reason` | Every triggered code from `failure_reason`. Populates when `mfr=1`. |

### Respondent node

| Parameter | Description |
| - | - |
| `country` | Name of the respondent's country. |
| `respondent_risk` | Defaults to `0`. `1` if more than one external data provider identifies the respondent as high risk. |
| `threat_potential` | Whether `threat_potential_score` is `low`, `med`, or `high`. |
| `latitude` / `longitude` / `state_name` / `time_zone` / `weather_code` | Populate when `coordinates=1`. `weather_code` is the nearest international weather station code. |
| `vpt` | If `vpt=check` is passed, `1` if the request is via VPN, else `0`. |
| `usage_type` | If `usage_type=1` is passed, `consumer`, `corporate`, or `hosting`. |
| `ip_address` | Detected IP address the request came from. |
| `isp` | Detected Internet Service Provider the request came from. |
| `browser_type` / `browser_full_name` | Detected browser (for example `BrowserChrome`), and the browser with its version. |
| `os_name` / `os_full_name` / `os_version` | Detected operating system, with version where possible. |
| `device_name` / `device_type` / `device_time` | Detected device name, type, and timestamp. |
| `city` | Detected city the request came from. |
| `geo_off_hrs_status` | Detected geolocation services set to "off" or "off-duty", relating to hours-of-service tracking or smart home automation. |

### EDP3 node

| Parameter | Description |
| - | - |
| `EDP3_score` | A score from an external data provider. Populates when `csedp3=1`. |

## 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, load the Research Defender JavaScript system utility library, `rd_sys_util.min.js`. See the [Advanced Integration guide](/research-defender/guides/search/03-advanced-integration) for a complete example.

```text theme={null}
https://<environment>.rtymgt.com/static/js/rd_sys_util.min.js?v=2.0.1
```

* The library is an ES **module** — load it with `import()` or `type="module"`.
* Call `init({ key: <publishable_key>, env: <environment> })` so the library starts collecting data, then wait about **1 second** before reading the result.
* `pass_params()` returns the combined, encrypted dataset detected from the respondent's browser. Send it on the SEARCH call as the **name** of a parameter with an empty value.

```js theme={null}
const { init, pass_params } = await import('https://prod.rtymgt.com/static/js/rd_sys_util.min.js?v=2.0.1')
await init({ key: '<publishable_key>', env: 'prod' })
await new Promise((resolve) => setTimeout(resolve, 1000))
const pass = 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>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.