Introduction

Welcome to the TapResearch Survey API V3 documentation!

There are some notable changes to how our API handles security and postbacks. See our versions section for more details.

Getting Started

Sign up for a publisher account at https://www.tapresearch.com/suppliers/sign_up.

Before you can begin consuming our API, you will need an api token. This token will be used for authentication purposes. You can generate an api token by creating an app in the dashboard.

Please let us know when you are ready to go live. We will need to make changes to your account before your users can see real surveys.

Surveys

Get survey offer

Sample Request

{
  "api_token": "9b99ccc0062035544a5b6579b0cfc954",
  "user_identifier": "tapresearch_user1",
  "offer_identifier": "05700f12180cdde5b131a0f8"
}

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"
  },
  "abandon_url": "https://www.tapresearch.com/router/offers/d1105fad890c931188905ab8198f308a?tid=f5807f26ff3c57426d0749fdc381ed4e&uid=tapresearch_user1"
}

Get survey offer for a user based on user identifier. Placement must first be created for your app using the supplier dashboard.

HTTP Request

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

Required Parameters

Response

Postbacks

Survey complete postback

# Sample postback request
"https://www.your_postback_url.com/postback?api_token=9b99ccc0062035544a5b6579b0cfc954&cpid=tap_37939e4ede350f3a8d5149d2fcaa025e&payout_amount=191&payout_currency=gold&revenue=0.5&tid=777ca23551a4a9173920c22e1ed7f4f3&uid=developers%40tapresearch.com&sig=ea354b408a1183fa27606ece2c3cf8d1"

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

HTTP Request

GET http://your_postback_url.com

Payload

Response

We expect a 200 if the request was successful

Security

# Sample request URL
url = "https://www.tapresearch.com/postback?api_token=9b99ccc0062035544a5b6579b0cfc954&cpid=tap_37939e4ede350f3a8d5149d2fcaa025e&payout_amount=191&revenue=0.5&tid=777ca23551a4a9173920c22e1ed7f4f3&uid=developers%40tapresearch.com&sig=ea354b408a1183fa27606ece2c3cf8d1"

# Isolate query string
query_string = url.gsub(/^(.*?)\?/, "")

# Strip out the sig parameter
stripped_query_string = query_string.gsub(/&sig.*/, "")

# Decode URL
decoded = URI.decode(stripped_query_string)

# Generate HMAC-MD5
api_secret = "26dcc0fc7b6208fdfeffaf19f627cb4a"
digest = OpenSSL::Digest.new("md5")
md5 = OpenSSL::HMAC.hexdigest(digest, api_secret, decoded)

puts md5 # ea354b408a1183fa27606ece2c3cf8d1

For security purposes, every postback request will include an HMAC-MD5, which is generated using the query string.

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: 26dcc0fc7b6208fdfeffaf19f627cb4a

2. A postback request will look similar to the example shown below. Example: https://www.tapresearch.com/postback?api_token=9b99ccc0062035544a5b6579b0cfc954&cpid=tap_37939e4ede350f3a8d5149d2fcaa025e&payout_amount=191&revenue=0.5&tid=777ca23551a4a9173920c22e1ed7f4f3&uid=developers%40tapresearch.com&sig=ea354b408a1183fa27606ece2c3cf8d1

3. Isolate the query string, leaving out the question mark. Example: api_token=9b99ccc0062035544a5b6579b0cfc954&cpid=tap_37939e4ede350f3a8d5149d2fcaa025e&payout_amount=191&revenue=0.5&tid=777ca23551a4a9173920c22e1ed7f4f3&uid=developers%40tapresearch.com&sig=ea354b408a1183fa27606ece2c3cf8d1

4. Strip out the sig parameter, including the ampersand (&) symbol. Example: api_token=9b99ccc0062035544a5b6579b0cfc954&cpid=tap_37939e4ede350f3a8d5149d2fcaa025e&payout_amount=191&revenue=0.5&tid=777ca23551a4a9173920c22e1ed7f4f3&uid=developers%40tapresearch.com

5. Decode the query string. Example: api_token=9b99ccc0062035544a5b6579b0cfc954&cpid=tap_37939e4ede350f3a8d5149d2fcaa025e&payout_amount=191&revenue=0.5&tid=777ca23551a4a9173920c22e1ed7f4f3&uid=developers@tapresearch.com

6. 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 ea354b408a1183fa27606ece2c3cf8d1.

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

IP Whitelist

The postbacks will be send from the following addresses. Any other connections should be blocked.

3.88.121.21, 3.92.129.242, 3.89.214.250, 54.92.201.189, 3.84.132.120, 34.226.244.76, 52.6.75.91, 52.206.204.41, 35.168.113.51, 34.229.18.35, 35.175.253.126, 3.80.4.1, 18.212.246.233

Reporting

Get supplier Stats

# Sample stats request

"https://www.tapresearch.com/supply_api/suppliers/stats?access_token=83742aa7dc154c1a84d03213ac1228b5&from=2018-09-20T12:00:00-07:00&to=2018-09-20T13:00:00-07:00"

Sample Response

[
    {
        "datetime": "2018-09-20T12:00:00-07:00",
        "app_name": "Sample App - iOS",
        "id": 42,
        "app_store_identifier": "com.sample.app",
        "placement_name": "Main Placement",
        "placement_identifier":"fb15ebe9c89c3fc4256c33a8e0eabcff",
        "country_abbr": "US",
        "impressions": 10,
        "conversions": 5,
        "revenue": "1.32",
        "platform": "iOS"
    },
    {
        "datetime": "2018-09-20T12:00:00-07:00",
        "app_name": "Sample App - iOS",
        "id": 42,
        "app_store_identifier": "com.sample.app",
        "placement_name": "Secondary Placement",
        "placement_identifier":"ab13eabbc89c3fc1956c83a8e0efbbfa",
        "country_abbr": "US",
        "impressions": 1582,
        "conversions": 366,
        "revenue": "63.54",
        "platform": "iOS"
    },
    {
        "datetime": "2018-09-20T12:00:00-07:00",
        "app_name": "Sample App - Android",
        "id": 43,
        "app_store_identifier": "com.sample.app",
        "placement_name": "Main Placement",
        "placement_identifier": "fb15eabbc89c3fc1466c83a8e0adbbcf",
        "country_abbr": "US",
        "impressions": 45,
        "conversions": 19,
        "revenue": "3.56",
        "platform": "Android"
    },
  ]

HTTP Request

GET https://www.tapresearch.com/supply_api/suppliers/stats

Payload

Response

Errors

The TapResearch API uses the following error codes:

Versions

v3.00

• /supply_api/v3/surveys/offer
  • This is the new endpoint to get the offer url.
  • Removed attribute - device_identifier

2.12

• /surveys/offer
  • New attribute - client_ip

2.11

• /surveys/offer
  • Response now includes an abandon URL. Use it to redirect users back to our site after they decide to skip a survey.

v2.10

• Audience API
  • Get all supported countries
  • Get country specific qualifications
  • Get user attributes for a given set of device IDs or user identifiers

v2.00

• Changes compared to v1
  • Our postbacks are now an HTTP GET as opposed to a POST.
  • All request parameters will be appended to the postback URL.
  • Added the sig parameter, which is the postback URL signature. See the security section for more details.
  • The sech parameter has been removed.
  • Postback Content-Type and Accept headers will no longer be application/json.

v2.01

• Postbacks
  • New attribute - payout_type. 0 - Profile complete, 1 - Disqualified, 2 - Survey complete
  • New attribute - currency_name.

Contact Us

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