SEARCH - Research Desk Documentation

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>

https://prod.rtymgt.com/api/v4/respondents/search/<publishable_key>?sn_ud=170716409&sy_nr=20210575&rt_cy_ce=us

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.

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.

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.

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.

Response Example

{
  "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 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:

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.

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

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>

Research Defender publishes recommended term logic for translating SEARCH scores into accept/term decisions.

​Input Parameters

​Required

​Recommended

​Optional

​Recommended Response Parameters

​Failure Reason Codes

​Advanced Response Parameters

​Response Example

​Advanced Fingerprint Detection

Input Parameters

Required

Recommended

Optional

Recommended Response Parameters

Failure Reason Codes

Advanced Response Parameters

Response Example

Advanced Fingerprint Detection