GET /campaigns

Retrieve available campaigns (surveys) for a participant profile. This endpoint should be called after impaneling a participant to discover live survey opportunities.

Configure a post-survey redirect URL first

/campaigns requires your app to have a post-survey redirect URL configured (and an active placement) before it will return surveys. Without one, the call returns 422 with A valid post-survey redirect URL is required. — before any surveys are evaluated. See Redirects.

---

Request

Headers

Name	Required	Description
X-Api-Token	✅	Your API token.
X-User-Identifier	✅	Participant UUID.
X-Device-Identifier	❌	Optional hardware/device ID for multi-device distinction.

Query Parameters

Name	Required	Description
user_ip	✅	Participant IP address (e.g., 107.193.140.76).
device_type	✅	Device type — 1 = mobile, 2 = desktop, 3 = tablet.

---

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	Float	Earnings per click to you, factoring in completes, DQs, and OQs.
currency_name	String	Name of the in-app currency.
offer_entry_url	String	URL to start the survey (redirect the participant here).
is_hot_tile	Boolean/Integer	Indicates whether this survey's performance exceeds our internal threshold.
support_url	String	TapResearch-hosted support contact URL for the player's current session. Present this as a "Get Help" link alongside the campaign in your UI.

---

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. An empty surveys array almost always traces back to one of these. Common values:

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

This is the common subset; other codes may appear.

---

Example Response

{
  "surveys": [
    {
      "identifier": "4da2192594d2420648e5996e8bc1cb59",
      "length_in_minutes": 6,
      "conversion_rate": 66,
      "reward_amount": 68,
      "epc": 1.5,
      "currency_name": "points",
      "offer_entry_url": "https://www.tapresearch.com/router/offers/28e0f041675fb74b7ef254482ad1d502/pre_entry...",
      "is_hot_tile": 1
    },
    {
      "identifier": "7e41c40fa02ed36035b5955b58e52388",
      "length_in_minutes": 15,
      "conversion_rate": 8,
      "reward_amount": 232,
      "epc": 2.0,
      "currency_name": "points",
      "offer_entry_url": "https://www.tapresearch.com/router/offers/28e0f041675fb74b7ef254482ad1d502/pre_entry...",
      "is_hot_tile": 1
    }
  ],
  "player_eligibility": {
    "is_eligible": true,
    "reason": 0,
    "comment": "Qualified"
  }
}

---

Errors

Errors return { "message": "<text>", "error_code": <integer|null> }:

error_code	Status	When
1000	401	Invalid or missing X-Api-Token
1001	422	Missing X-User-Identifier
1003	422	A required header is missing
1002	503	Temporarily unavailable (maintenance)

Other validation failures return 422 with a descriptive message and error_code: null — for example, A valid post-survey redirect URL is required. (see the prerequisite at the top of this page).

---

Notes

• Call this endpoint after successfully impaneling a participant. See Impanel.
• Cache responses for up to 2 minutes to reduce load.
• 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: Callbacks → — receive reward notifications on your backend when a participant completes a survey.