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/v3/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.
offer_identifier	String	✅	The identifier of the placement/offer you are checking eligibility for.
client_ip	String	❌	The end user's IP address. Optional, but recommended for accurate geo-targeting.

Example Request

curl -X POST https://www.tapresearch.com/supply_api/v3/surveys/offer \
  -d "user_identifier=user-12345" \
  -d "api_token=your-api-token" \
  -d "offer_identifier=your-offer-identifier" \
  -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_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
}

---

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.