Fetch surveys with dynamic currency

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

Retrieve surveys with a per-request currency and exchange rate. 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.

Dashboard currency is still required, but unused

A currency variant must still be configured in the dashboard. It will not be used — currency_name and exchange_rate below always take precedence.

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.
currency_name	Yes	Display name of the currency for this request (e.g. Coins). 191 characters or fewer.
exchange_rate	Yes	Units of your currency per $1.00 USD (e.g. 1000). Must be a finite decimal in [10, 100,000,000); invalid values return an error.

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).
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 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.
• Redirects for these sessions also carry the currency_name, signed after pass_through; use {CURRENCY_NAME} if your redirect URL uses placeholders. Include it when you verify sech.

---

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