Fetch surveys

Retrieve the surveys available to a participant. See profiling options.

GET https://api.tapresearch.com/supply_api/v4/campaigns

Configure your app first

Set a post-survey Redirect URL and add active content to your placement before requesting surveys.

Request

Headers

Name	Required	Description
X-Api-Token	Yes	Your API token.
X-User-Identifier	Yes	Your unique, stable participant identifier.
X-Device-Identifier	No	Optional hardware/device ID for multi-device distinction.

Query parameters

Name	Required	Description
user_ip	Yes	Participant IP address (e.g., 107.193.140.76).
device_type	Yes	Device type — 0 = tablet, 1 = phone, 2 = desktop.

Response

The response returns a JSON object containing:

Field	Type	Description
surveys	Array	List of available surveys for the participant.
player_eligibility	Object	Participant eligibility status.

Surveys object

Each item in the surveys array contains:

Field	Type	Description
identifier	String	Unique campaign identifier.
length_in_minutes	Integer	Estimated survey duration.
conversion_rate	Integer	Completion rate percentage.
reward_amount	Integer	Reward amount for the participant on a full complete.
epc	String or Integer	Your earnings per click in USD after revenue share, returned as a decimal string or 0.
currency_name	String	Name of the in-app currency.
offer_entry_url	String	URL to start the survey (redirect the participant here).
support_url	String	TapResearch-hosted support contact URL for this survey. Present this as a "Get Help" link alongside the campaign in your UI. See Support center.
is_hot_tile	Boolean/Integer	Indicates whether this survey's performance exceeds our internal threshold.
category	String	Survey category label (e.g. Entertainment), or None when uncategorized.

Player eligibility object

Field	Type	Description
is_eligible	Boolean	Indicates if the participant is eligible to take surveys.
reason	Integer	Eligibility reason code. See Reason codes.
comment	String	Human-readable eligibility comment.

Reason codes

When is_eligible is false, reason tells you why, and surveys is empty:

Code	Meaning
0	Eligible
2	App is in test mode — only registered test devices are eligible
4	Not a supported country
5	Under the supported age
6	Missing user identifier
8	Banned
12	Missing device/user identifier
20	User identifier is an anonymous device advertising ID, not a real user ID
22	Blacklisted

Example response

{
  "surveys": [
    {
      "identifier": "4da2192594d2420648e5996e8bc1cb59",
      "length_in_minutes": 6,
      "conversion_rate": 66,
      "reward_amount": 68,
      "epc": "1.35",
      "currency_name": "points",
      "offer_entry_url": "https://www.tapresearch.com/router/offers/28e0f041675fb74b7ef254482ad1d502/pre_entry?...",
      "support_url": "https://www.tapresearch.com/support/contact?reference_code=...",
      "is_hot_tile": 1,
      "category": "Entertainment"
    }
  ],
  "player_eligibility": {
    "is_eligible": true,
    "reason": 0,
    "comment": "Qualified"
  }
}

Errors

Errors return a JSON error or message. Coded errors also include error_code.

Status	Meaning
401	Missing or invalid API token.
422	Missing or invalid request parameters, or incomplete app setup.
503	Temporarily unavailable.

Notes

• Call this endpoint after successfully impaneling a participant. See Impanel.
• Use the offer_entry_url to redirect participants into a live survey.
• The player_eligibility block determines whether the user can proceed. If the participant is not qualified, the surveys array will be empty.
• Surveys are already ordered by our internal yield management algorithm, so we recommend using them in the order returned.
• Reward amounts represent what the participant earns on a full survey complete. The actual value to you may be lower since TapResearch also pays out for DQs/OQs based on time spent in the survey.
• EPC (earnings per click) reflects all payout types—not just completes—giving you a holistic view of expected earnings. Use this field if you plan to manage yield on your end instead of relying solely on reward amount.

---

Next step: Handling rewards → — receive reward postbacks on your backend when a participant completes a survey.