Eligibility check

Use this endpoint to check whether a user currently has a survey offer available before you show them a call-to-action. It returns a simple has_offer true/false plus the links you need to send the user into (or away from) the offer.

POST https://www.tapresearch.com/supply_api/v4/surveys/offer

All requests must be made over HTTPS.

Request

Send the parameters as form-encoded body fields, or as a JSON body.

Parameter	Type	Required	Description
user_identifier	String	Yes	Your persistent, unique identifier for this user.
api_token	String	Yes	The API token for your app, found in the Publisher Dashboard. Must belong to an app created with the Eligibility API type.
client_ip	String	Yes	The end user's IP address.
placement_tag	String	No	Tag of the survey wall placement to check.
attributes_hash	Object	No	Custom user attributes for segmentation.
device_identifier	String	No	The user's device identifier, if you have one.

Example request

curl -X POST https://www.tapresearch.com/supply_api/v4/surveys/offer \
  -d "user_identifier=user-12345" \
  -d "api_token=your-api-token" \
  -d "client_ip=203.0.113.42"

Response

The response is a JSON object. has_offer is the field to branch on; the URLs and message_hash are only returned when has_offer is true.

Field	Type	Description
has_offer	Boolean	true if the user has an offer available, false otherwise.
offer_reason	Integer	A code explaining the result. Always present. See Reason codes.
reason_comment	String	Human-readable explanation of offer_reason. Always present.
offer_url	String	The URL to send the user to in order to start the offer. Present when has_offer is true.
abandon_url	String	The URL to send the user to if they decline or abandon the offer. Present when has_offer is true.
message_hash	Object	The reward range for this user. Present when has_offer is true. See message_hash below.

message_hash

The reward range to display to the user, in your currency.

Field	Type	Description
min	String	Minimum reward amount, in your currency.
max	String	Maximum reward amount, in your currency.
currency	String	The name of the currency the user earns.

Example response — offer available

{
  "has_offer": true,
  "offer_reason": 0,
  "reason_comment": "Qualified",
  "offer_url": "https://www.tapresearch.com/router/offers/8f14e45fceea167a5a36dedd4bea2543/pre_entry?sdk=false&uid=user-12345&...",
  "message_hash": {
    "min": "10",
    "max": "700",
    "currency": "gold"
  },
  "abandon_url": "https://www.tapresearch.com/router/offers/8f14e45fceea167a5a36dedd4bea2543?tid=...&uid=user-12345"
}

Example response — no offer

{
  "has_offer": false,
  "offer_reason": 19,
  "reason_comment": "No content available"
}

Using the response

• has_offer: true — Show your call-to-action and link the user to offer_url. Use message_hash to display the reward range (for example, "Earn 10–700 gold"). If the user backs out, send them to abandon_url.
• has_offer: false — Do not show the call-to-action. There is nothing for the user to do right now.

When the user completes the offer, TapResearch reports the reward to your server through a postback.

Reason codes

Every response includes offer_reason (an integer) and a matching reason_comment. Branch on the code, not the comment text. Common values:

Code	Meaning
0	Qualified — an offer is available (has_offer: true)
1	Not qualified — no surveys available for this user right now
2	App is in test mode — only registered test devices are eligible
4	Not a supported country
5	User is under the supported age
8	User is banned
19	No active offers available
20	User identifier is an anonymous device advertising ID, not a real user ID
22	User is blacklisted
23	User doesn't meet the placement's targeting criteria, such as your segmentation attributes
24	No currency is set up for the offer

This is the common subset; other codes may appear.

Errors

Errors return a JSON error message with an HTTP status:

Status	Meaning
401	Missing or invalid API token.
422	Invalid or missing request parameters.
503	Temporarily unavailable.