NAV Navbar
shell
  • Introduction
  • Getting Started
  • Surveys
  • Postbacks
  • Audience
  • Reporting
  • Errors
  • Versions
  • Contact Us
  • Introduction

    Welcome to the TapResearch Survey API V2 documentation!

    There are some notable changes to how our API handles security and postbacks. See our versions section for more details. If you're looking for our V1 documentation, please click here.

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

    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_identifier 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.
    client_ip (Optional) String This the IP address of the end user. This attribute is required if you're checking survey availability through a backend service.

    Response

    Parameter Type Description
    has_offer Boolean Send users into the survey only when this value is true.
    offer_url String Offer entry URL
    abandon_url String Use this URL to redirect users back to our site after they decide to skip a survey.
    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 postback request
    "https://www.tapresearch.com/postback?api_token=9b99ccc0062035544a5b6579b0cfc954&cpid=tap_37939e4ede350f3a8d5149d2fcaa025e&did=0258DE71-DFEB-4399-BF26-11C1F6E600D2&payout_amount=191&payout_currency=gold&revenue=0.5&tid=777ca23551a4a9173920c22e1ed7f4f3&uid=developers%40tapresearch.com&sig=b438afd7426c743e777c387d7e2712d4"
    
    

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

    HTTP Request

    GET 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
    payout_currency String The type of Currency the user earned.
    revenue Decimal Amount you will be paid for this survey complete in USD.
    payout_type Integer The action that the user was rewarded for. 0 - Profile complete, 1 - Disqualified, 3 - Survey Complete.
    sig String This is the URL signature, which is an HMAC-MD5 generated using the query string, minus the sig parameter. See the security section for more details.

    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&did=0258DE71-DFEB-4399-BF26-11C1F6E600D2&payout_amount=191&revenue=0.5&tid=777ca23551a4a9173920c22e1ed7f4f3&uid=developers%40tapresearch.com&sig=b438afd7426c743e777c387d7e2712d4"
    
    # 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 # b438afd7426c743e777c387d7e2712d4
    
    

    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&did=0258DE71-DFEB-4399-BF26-11C1F6E600D2&payout_amount=191&revenue=0.5&tid=777ca23551a4a9173920c22e1ed7f4f3&uid=developers%40tapresearch.com&sig=b438afd7426c743e777c387d7e2712d4

    3. Isolate the query string, leaving out the question mark. Example: api_token=9b99ccc0062035544a5b6579b0cfc954&cpid=tap_37939e4ede350f3a8d5149d2fcaa025e&did=0258DE71-DFEB-4399-BF26-11C1F6E600D2&payout_amount=191&revenue=0.5&tid=777ca23551a4a9173920c22e1ed7f4f3&uid=developers%40tapresearch.com&sig=b438afd7426c743e777c387d7e2712d4

    4. Strip out the sig parameter, including the ampersand (&) symbol. Example: api_token=9b99ccc0062035544a5b6579b0cfc954&cpid=tap_37939e4ede350f3a8d5149d2fcaa025e&did=0258DE71-DFEB-4399-BF26-11C1F6E600D2&payout_amount=191&revenue=0.5&tid=777ca23551a4a9173920c22e1ed7f4f3&uid=developers%40tapresearch.com

    5. Decode the query string. Example: api_token=9b99ccc0062035544a5b6579b0cfc954&cpid=tap_37939e4ede350f3a8d5149d2fcaa025e&did=0258DE71-DFEB-4399-BF26-11C1F6E600D2&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 b438afd7426c743e777c387d7e2712d4.

    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 34.198.225.203 and 34.198.176.126, any other connections should be blocked.

    Audience

    Access Token

    The audience API is unavailable, by default. You'll need to contact developers@tapresearch.com in order to request access. If access is granted, we will provide you with an access token, which will be used for authorization purposes.

    Get supported countries

    
    # Sample Request
    "https://www.tapresearch.com/supply_api/audience/countries?access_token=60a783a6fe6315c2162776fb01c4e43d"
    
    

    Sample Response

    {
      "countries": [
        "US",
        "CA",
        "GB",
        "BR",
        "FR",
        "DE",
        "AU",
        "CN",
        "IT",
        "ES",
        "RU",
        "JP",
        "IN",
        "MX",
        "SE",
        "DK",
        "NO",
        "SG",
        "KR"
      ]
    }
    

    Get a list of supported countries.

    We do not collect demographic data from users who reside in an unsupported country.

    HTTP Request

    GET https://www.tapresearch.com/supply_api/audience/countries

    Payload

    Parameter Type Description
    access_token String Unique token used for authorization purposes.

    Response

    Parameter Type Description
    countries Array A list of abbreviations for supported countries.

    Get qualifications

    
    # Sample Request
    "https://www.tapresearch.com/supply_api/audience/qualifications?access_token=60a783a6fe6315c2162776fb01c4e43d&country=US"
    
    

    Sample Response

    {
      "US": [
        {
          "name": "AGE",
          "question_id": 42,
          "question_text": "What is your age?",
          "type": "Text",
          "qualification_answers": [
    
          ]
        },
        {
          "name": "RELATIONSHIP",
          "question_id": 632,
          "question_text": "What is your relationship status?",
          "type": "Single select",
          "qualification_answers": [
            {
              "pre_code": 1,
              "answer_text": "Single, never married"
            },
            {
              "pre_code": 2,
              "answer_text": "Married"
            },
            {
              "pre_code": 3,
              "answer_text": "Separated, divorced or widowed"
            },
            {
              "pre_code": 4,
              "answer_text": "Domestic Partnership"
            },
            {
              "pre_code": 5,
              "answer_text": "Prefer not to answer"
            }
          ]
        },
      ]
    }
    

    Get country specific qualifications.

    There are three different qualification types -- Single select, Multi select, and Text. For single select, users can only select one answer. Multi select allows users to select multiple answers. Text qualifications allows users to submit a numeric or alphanumeric answer. As shown in the example response to the right, "text" type qualifications will not have any qualification_answers.

    Users answer these questions to populate their profile. We recommend that you store these qualifications, which will be required when you source user attributes through our "Get user attributes" endpoint.

    HTTP Request

    GET https://www.tapresearch.com/supply_api/audience/qualifications

    Payload

    Parameter Type Description
    access_token String Unique token used for authorization purposes.
    country String (Optional) Country abbreviation. If this value isn't present, this endpoint will return qualifications for all countries. See Get supported countries to get a list of supported countries.

    Response

    Parameter Type Description
    name String Name of the qualification
    question_id Integer Unique qualification ID. This will be the key name for user attributes. See "Get user attributes" for additional details.
    question_text String Question text that was shown to users
    type String There are three types of questions -- Single select, Multi select, and Text. See above for an explanation of each type.
    qualification_answers Array A list of answer options for a particular qualification. A pre_code is unique for each qualification.

    Get user attributes

    
    # Sample Request
    "https://www.tapresearch.com/supply_api/audience/users/attributes?access_token=60a783a6fe6315c2162776fb01c4e43d"
    
    
    {
      "uids": [
        "user_identifier1",
      ],
      "dids": [
        "e77b8aa8-d7ce-423a-b9ae-f2a440f8ed8d",
        "0258DE71-DFEB-4399-BF26-11C1F6E600D2"
      ]
    }
    

    Sample Response

    {
      "uids": [
        {
          "uid": "user_identifier1.",
          "country": "US",
          "attributes": {
            "42": "29",
            "43": "2",
            "45": "50005",
            "47": "1",
            "113": "5",
            "632": "1",
            "633": "8",
            "1249": "-3105",
            "2189": "1",
            "14785": "24"
          }
        }
      ],
      "dids": [
        {
          "did": "e77b8aa8-d7ce-423a-b9ae-f2a440f8ed8d",
          "country": "US",
          "attributes": {
            "42": "30",
            "43": "1",
            "45": "95120",
            "47": "1",
            "113": "1",
            "632": "1",
            "633": "12",
            "1249": "1,2",
            "2189": "1",
            "14785": "18"
          }
        },
        {
          "did": "0258DE71-DFEB-4399-BF26-11C1F6E600D2",
          "country": "US",
          "attributes": {
    
          }
        }
      ]
    }
    

    Get user attributes for a given set of device IDs or user identifiers.

    The "dids" and "uids" attributes are limited to a maximum of 1,000 elements. Additional elements will not be included in the response. If you want to increase the speed in which your system ingests user data, you are welcome to run up to 10 requests in parallel.

    All new users will be required to fill out their profile. The number of profiling questions will differ depending on country. For example, US users will have 10 attributes -- UK users will only have 8. Some users have incomplete profiles. In this scenario, we will return as many attributes as the user has populated.

    We've actively condensed the size the response payload to reduce response times as much as possible. An attribute "key" is a qualification question_id and the value will be a pre_code(s). For example, the example response for the "Get qualifications" endpoint has two qualifications -- Age and Relationship. The question_id for these qualifications are 42 and 632, respectively. For "user_identifier1", you'll notice that 42 and 632 are keys inside the attributes hash. Age is a text qualification, so we read the value as is -- this user is 29 years old. Relationship is a single select qualification, so we need to refer to the example qualification response -- the value "1" maps to pre_code "1", which is "Single, never married". So, "user_identifier1" is 29 years old and single.

    HTTP Request

    POST https://www.tapresearch.com/supply_api/audience/users/attributes

    Payload

    Parameter Type Description
    access_token String Unique token used for authorization purposes.
    uids Array A list of user identfiers
    dids Array A list of device identifiers -- GAID for Android, IDFA for iOS

    Response

    Parameter Type Description
    country String A user's country of residence
    attributes Hash A user's profile. The format is "question_id":"pre_code(s)". See "Get qualifications" section for further details.

    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",
            "placement_name": "Main Placement",
            "country_abbr": "US",
            "impressions": 10,
            "conversions": 5,
            "revenue": "1.32"
        },
        {
            "datetime": "2018-09-20T12:00:00-07:00",
            "app_name": "Sample App - iOS",
            "placement_name": "Secondary Placement",
            "country_abbr": "US",
            "impressions": 1582,
            "conversions": 366,
            "revenue": "63.54"
        },
        {
            "datetime": "2018-09-20T12:00:00-07:00",
            "app_name": "Sample App - Android",
            "placement_name": "Main Placement",
            "country_abbr": "US",
            "impressions": 45,
            "conversions": 19,
            "revenue": "3.56"
        },
      ]
    
    

    HTTP Request

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

    Payload

    Parameter Type Description
    access_token String Unique token used for authorization purposes.
    from Date The start date Date Format: I.E. "2018-04-05T17:00:00-07:00"
    to Date The end date Date Format: I.E. "2018-04-05T17:00:00-07:00"

    Response

    Parameter Type Description
    datetime date The hour that the stats reflect
    app_name String The App name
    placement_name String The placement name
    country_abbr String The country abbreviation
    impressions Integer The number of entries to TapResearch experience
    conversions Integer The number of entries with at least one survey complete
    revenue Float The revenue in the given hour

    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

    2.12

    2.11

    v2.10

    v2.00

    v2.01

    Contact Us

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