NAV
shell

Introduction

Welcome to the TapResearch Survey API documentation!

Surveys

Get survey offer

Sample Request

{
  "api_token": "9b99ccc0062035544a5b6579b0cfc954",
  "device_identifier": "221668A1-4B0F-45A1-A7AF-DF4DE462D42D",
  "user_identifier": "tapresearch_user1"
}

Sample Response

{
  "has_offer": true,
  "offer_url": "https://www.tapresearch.com/router/device_players/12bf83763d41d1d626fd54d2ada76a78?oid=e4f897d8820b6db278b470bb7ba5fa505686c3d8\u0026sdk=false",
  "message_hash": {
    "min": "191",
    "max": "764",
    "currency": "bombs"
  }
}

Get survey offer for a user based on device identifier and/or user identifier.

HTTP Request

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

Required Parameters

Parameter Type Description
device_identifer String Unique device identifier. IDFA for Apple devices or Google Advertising ID for Android.
user_identifier String Unique alphanumeric string that you use to identify your user.
api_token String This is the unique identifier we generate when you create an app in our dashboard.

Response

Parameter Type Description
has_offer Boolean Send users into the survey only when this value is true.
offer_url String Survey entry URL.
message_hash Hash This contains information that you can show the user before you redirect them to the offer_url.

Postbacks

Survey complete postback

Sample Request

{
  "tid": "777ca23551a4a9173920c22e1ed7f4f3",
  "api_token": "9b99ccc0062035544a5b6579b0cfc954",
  "payout_amount": 191,
  "revenue": "0.5",
  "cpid": "tap_37939e4ede350f3a8d5149d2fcaa025e",
  "uid": "developers@tapresearch.com",
  "did": "0258DE71-DFEB-4399-BF26-11C1F6E600D2",
  "full_sech": "7af799a01b95788158edd95c93cdcaf4",
  "sech": "ea0846c46e93fb67a0c8625f9f88f2cd"
}

Notify your web service on survey complete through a pre-defined postback URL

HTTP Request

POST http://your_postback_url.com

Payload

Parameter Type Description
uid String Persistent unique identifier for this user.
did String Device identifier – IDFA for Apple, Google Device ID for Android.
tid String Transaction ID or click ID. This value will not be unique if the user completed multiple surveys in a single session. Use cpid for deduping purposes.
cpid String Unique survey complete identifier. We recommend that you store and check against this value to ensure you reward the user only once per survey complete.
api_token String This is the unique identifier we generate when you create an app in our dashboard.
payout_amount Integer Amount of currency earned by this user
revenue float Amount you will be paid for this survey complete in USD.
full_sech String This is the payload signature, which is an HMAC-MD5 generated using the entire payload, minus the sech and full_sech parameters. See the security section for more details.
sech String HMAC-MD5 generated using the tid and your api secret.

Response

We expect a 200 if the request was successful

Security


# Note, the full_sech and sech parameters have already been removed.
json_payload = '{"tid":"777ca23551a4a9173920c22e1ed7f4f3","api_token":"9b99ccc0062035544a5b6579b0cfc954","payout_amount":191,"revenue":"0.5","cpid":"tap_37939e4ede350f3a8d5149d2fcaa025e","uid":"developers@tapresearch.com","did":"0258DE71-DFEB-4399-BF26-11C1F6E600D2"}'
api_secret = "26dcc0fc7b6208fdfeffaf19f627cb4a"

digest = OpenSSL::Digest.new("md5")
md5 = OpenSSL::HMAC.hexdigest(digest, api_secret, json_payload)

puts md5 # 7af799a01b95788158edd95c93cdcaf4

For security purposes, every postback request will include an HMAC-MD5, which is generated using the tid parameter and your api secret.

Using the example request in the postback section, here are the steps to generate the HMAC-MD5.

  1. Grab your api secret. This value is located in your main dashboard. Example: 93ab04b83bf49636f29e89156c5481c1

  2. A postback payload will look similar to the example shown below. Example: {"full_sech":"7af799a01b95788158edd95c93cdcaf4","sech":"ea0846c46e93fb67a0c8625f9f88f2cd","tid":"777ca23551a4a9173920c22e1ed7f4f3","api_token":"9b99ccc0062035544a5b6579b0cfc954","payout_amount":191,"revenue":"0.5","cpid":"tap_37939e4ede350f3a8d5149d2fcaa025e","uid":"developers@tapresearch.com","did":"0258DE71-DFEB-4399-BF26-11C1F6E600D2"}

  3. Strip out all parameters that are listed in the “Postbacks” section below. Example: {"tid":"777ca23551a4a9173920c22e1ed7f4f3","api_token":"9b99ccc0062035544a5b6579b0cfc954","payout_amount":191,"revenue":"0.5","cpid":"tap_37939e4ede350f3a8d5149d2fcaa025e","uid":"developers@tapresearch.com","did":"0258DE71-DFEB-4399-BF26-11C1F6E600D2"}

  4. Run the api secret and the modified payload through your favorite HMAC-MD5 generator. Using the example values in steps 1 and 2, the resulting string will be 33dd9d075844c362bbce1a5de40bc883.

  5. Check your generated HMAC against the full_sech param value. If they match, then record a complete and reward the user.

Errors

The TapResearch API uses the following error codes:

Error Code Meaning
400 Bad Request – Double check to make sure you are making a proper request.
401 Unauthorized – You do not have access to the resource you requested. Please make sure your authorization header is set correctly.
404 Not Found – The resource you have requested cannot be found.
422 Unprocessable Entity - There was an error with your request. The response should always have a message detailing why an error has occurred.
500 Internal Server Error – We had a problem with our server. Please contact api_support@tapresearch.com if this problem persists.
503 Service Unavailable – We’re temporarily offline for maintenance. Please try again later.

Versions

v1.0.3

v1.0.2

v1.01

v1.00

Contact Us

Please email developers@tapresearch.com for any questions or concerns.