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.

Parameter	Type	Required	Description
user_identifier	String	✅	Your persistent, unique identifier for this user.
api_token	String	✅	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	✅	The end user's IP address.

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 meaningful 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	Details about the reward for completing the offer. See message_hash below.

message_hash

A preview of the reward range currently available to this user, given current survey inventory.

Field	Type	Description
min	String	Minimum reward amount currently available.
max	String	Maximum reward amount currently available.
currency	String	The name of the currency the user earns.

Example Response — offer available

{
  "has_offer": true,
  "offer_url": "https://www.tapresearch.com/supply_api/v3/surveys/start?token=...",
  "abandon_url": "https://www.tapresearch.com/supply_api/v3/surveys/abandon?token=...",
  "message_hash": {
    "min": "50",
    "max": "200",
    "currency": "gold"
  }
}

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 50–200 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 callback.

---

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
6	Missing user identifier
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

This is the common subset; other codes may appear.

Errors

Errors return { "error": "<message>" } with an HTTP status:

Status	When
401 Unauthorized	Missing or invalid api_token — body {"error":"Unauthorized."}
422 Unprocessable Entity	user_identifier missing ({"error":"user_identifier must be specified"}), or the token isn't an Eligibility API app ({"error":"This endpoint requires a v4 Eligibility API app."})

TapResearch may also return 503 during maintenance.