NAV Navbar
shell ruby python javascript

Introduction

Welcome to the TapResearch Demand API documentation!

Our API enables you to create and modify sampling projects on our platform, start/stop the flow of sample and reconcile completes.

Getting Started

Sign up for a researcher account at https://staging.tapresearch.com/customers/sign_up.

Before you can begin consuming our API, you will need to contact api_support@tapresearch.com for an API token. This token will be used for authentication purposes described in the section below.

The first API token that we send you will only grant you access to our staging server, http://staging.tapresearch.com. Please use this as your base URL until you are ready to go live.

When you are read to go live, please follow the steps below:

  1. Contact us for a live api token.
  2. Replace https://staging.tapresearch.com with https://www.tapresearch.com for all routes.

Authentication


Example Request

$ curl -D- -X GET -H "Authorization: Basic dGVzdEB0YXByZXNlYXJjaC5jb206NGMzMTg2Mjg4YWUyM2ZkOTY2MWNiNWRmY2NlMTkzMGU="
-H "Content-Type: application/json" https://staging.tapresearch.com/api/v1/campaigns



Example Request

# Attach this to your Authorization header.
auth = "Basic" + Base64::strict_encode64("test@tapresearch.com:4c3186288ae23fd9661cb5dfcce1930e")

We use HTTP basic authentication combined with HTTPS to enforce access controls to secure resources. This means that we will check the value passed in the 'Authorization' header to make sure you have access to the resource you are requesting.

The 'Authorization' header needs to be submitted in the following form:

Authorization: Basic dGVzdEB0YXByZXNlYXJjaC5jb206NGMzMTg2Mjg4YWUyM2ZkOTY2MWNiNWRmY2NlMTkzMGU=

The header can be constructed by following the steps below:

  1. EMAIL_ADDRESS_YOU_PROVIDED:API_TOKEN Example: test@tapresearch.com:4c3186288ae23fd9661cb5dfcce1930e

  2. Base64 encode the string generated in step 1. Example: dGVzdEB0YXByZXNlYXJjaC5jb206NGMzMTg2Mjg4YWUyM2ZkOTY2MWNiNWRmY2NlMTkzMGU=

  3. Append Basic to the string generated in step 2. Example: Basic dGVzdEB0YXByZXNlYXJjaC5jb206NGMzMTg2Mjg4YWUyM2ZkOTY2MWNiNWRmY2NlMTkzMGU=

Lookups

List all country languages

HTTP Request

GET https://www.tapresearch.com/api/v1/country_languages

Sample Response

[
  {
    "id": 1,
    "abbr": "en-US"
  },
  {
    "id": 2,
    "abbr": "en-CA"
  },
  {
    "id": 5,
    "abbr": "en-GB"
  },
  {
    "id": 9,
    "abbr": "en-AU"
  }
]

List all qualifications

Get a list of supported targeting criteria.

Sample Response

[
  {
    "answer_type": 5,
    "name": "AGE",
    "question_id": 42,
    "question_text": "What is your age?",
    "en_translation": "What is your age?"
  },
  {
    "answer_type": 0,
    "name": "GENDER",
    "question_id": 43,
    "question_text": "What is your gender?",
    "en_translation": "What is your gender?"
  },
  {
    "answer_type": 5,
    "name": "ZIP",
    "question_id": 45,
    "question_text": "What is your zip or postal code?",
    "en_translation": "What is your your zip or postal code?"
  },
  {
    "answer_type": 0,
    "name": "HISPANIC",
    "question_id": 47,
    "question_text": "Are you of Hispanic, Latino, or Spanish origin?",
    "en_translation": "Are you of Hispanic, Latino, or Spanish origin?"
  },
  {
    "answer_type": 0,
    "name": "STATE",
    "question_id": 96,
    "question_text": "What is your state?",
    "en_translation": "What is your state?"
  }
]

HTTP Request

GET https://www.tapresearch.com/api/v1/qualifications?country_language_id=1

Required Parameters

Parameter Type Description
country_language_id integer Id value used to specify which set of qualifications to get by country language code.

Response Parameters

Parameter Type Description
name String Qualification name
question_id Integer This value will be used to fetch qualification details.
question_text String This is the question text that will be served to our respondents.
answer_type Integer This will determine how campaign_qualifications pre-codes are generated for quotas. See Answer Types section for more information.
en_translation String The english translation of the question.

Get a specific qualification

Get answer options to a specific qualification.

Sample Response

{
  "answer_type": 0,
  "name": "HISPANIC",
  "question_id": 47,
  "question_text": "Are you of Hispanic, Latino, or Spanish origin?",
  "en_translation": "Are you of Hispanic, Latino, or Spanish origin?",
  "qualification_answers": [
    {
      "option_text": "No , not of Hispanic, Latino, or Spanish origin",
      "pre_code": 1,
      "en_translation": "No , not of Hispanic, Latino, or Spanish origin"
    },
    {
      "option_text": "Yes, Mexican, Mexican American, Chicano",
      "pre_code": 2,
      "en_translation": "Yes, Mexican, Mexican American, Chicano"
    },
    {
      "option_text": "Yes, Cuban",
      "pre_code": 3,
      "en_translation": "Yes, Cuban"
    },
    {
      "option_text": "Yes, another Hispanic, Latino, or Spanish origin *** Argentina ",
      "pre_code": 4,
      "en_translation": "Yes, another Hispanic, Latino, or Spanish origin *** Argentina "
    },
    {
      "option_text": "Yes, another Hispanic, Latino, or Spanish origin *** Colombia ",
      "pre_code": 5,
      "en_translation": "Yes, another Hispanic, Latino, or Spanish origin *** Colombia "
    },
    {
      "option_text": "Yes, another Hispanic, Latino, or Spanish origin *** Ecuador ",
      "pre_code": 6,
      "en_translation": "Yes, another Hispanic, Latino, or Spanish origin *** Ecuador "
    },
    {
      "option_text": "Yes, another Hispanic, Latino, or Spanish origin *** El Salvadore ",
      "pre_code": 7,
      "en_translation": "Yes, another Hispanic, Latino, or Spanish origin *** El Salvadore "
    },
    {
      "option_text": "Yes, another Hispanic, Latino, or Spanish origin *** Guatemala ",
      "pre_code": 8,
      "en_translation": "Yes, another Hispanic, Latino, or Spanish origin *** Guatemala "
    },
    {
      "option_text": "Yes, another Hispanic, Latino, or Spanish origin *** Nicaragua ",
      "pre_code": 9,
      "en_translation": "Yes, another Hispanic, Latino, or Spanish origin *** Nicaragua "
    },
    {
      "option_text": "Yes, another Hispanic, Latino, or Spanish origin *** Panama ",
      "pre_code": 10,
      "en_translation": "Yes, another Hispanic, Latino, or Spanish origin *** Panama "
    },
    {
      "option_text": "Yes, another Hispanic, Latino, or Spanish origin *** Peru ",
      "pre_code": 11,
      "en_translation": "Yes, another Hispanic, Latino, or Spanish origin *** Peru "
    },
    {
      "option_text": "Yes, another Hispanic, Latino, or Spanish origin *** Spain ",
      "pre_code": 12,
      "en_translation": "Yes, another Hispanic, Latino, or Spanish origin *** Spain "
    },
    {
      "option_text": "Yes, another Hispanic, Latino, or Spanish origin *** Venezuela ",
      "pre_code": 13,
      "en_translation": "Yes, another Hispanic, Latino, or Spanish origin *** Venezuela ",
    },
    {
      "option_text": "Yes, another Hispanic, Latino, or Spanish origin *** Other Country",
      "pre_code": 14,
      "en_translation": "Yes, another Hispanic, Latino, or Spanish origin *** Other Country",
    },
    {
      "option_text": "Prefer not to answer",
      "pre_code": 15,
      "en_translation": "Prefer not to answer"
    }
  ]
}

HTTP Request

GET https://www.tapresearch.com/api/v1/qualifications/:question_id?country_language_id=1

Required Parameters

Parameter Type Description
question_id Integer This value will be returned with each record through the /qualifications route.
country_language_id Integer Id value used to specify which qualification to get by country language code.

Response

Qualification Answers

Parameter Type Description
option_text String The answer text that is shown to our respondents.
pre_code Integer This is value you will be passing into the campaign_qualifications pre_codes array to describe which respondents qualify for a survey.
en_translation String The english translation of the answer.

Campaigns

List your campaigns

Sample Response

{
    "id": 11611886,
    "cpi": null,
    "length_of_interview": 10,
    "name": "Test Survey",
    "total_remaining": 0,
    "status": 5,
    "supplier_link": "https://api.samplecompany.com/surveys/23423?id=",
    "incidence": 50,
    "reentry_interval": null,
    "days_in_field": 3,
    "max_daily_completes": null,
    "is_retarget": false,
    "is_maid_targeted": false,
    "retarget_count": 0,
    "supported_devices": [
        0,
        2
    ],
    "country_language_id": 1,
    "custom_campaign_qualifications": [],
    "buyer_account_id": 1,
    "campaign_quotas": [],
    "campaign_relationships": [],
    "redirect_test_url": "https://www.tapresearch.com/api/v1/campaigns/11611886/redirect_test"
}

Get a list of campaigns that are accessible by the authenticated user.

HTTP Request

GET https://www.tapresearch.com/api/v1/campaigns

Required Parameters

NONE

Optional Parameters

Parameter Type Description
country_language_id Integer Optional id value used to specify which set of campaigns to get by country language code.

Response

Parameter Type Description
id Integer This is the unique campaign identifier. You will need to use this parameter to get campaign details or update a specific campaign.
name String Name of the campaign.
cpi String All CPIs are USD. This is the amount you will be charged per complete.
days_in_field Integer Number of days this campaign will be in the field. This value will be used to estimate feasibility for each associated campaign quota.
incidence Integer The percentage chance that a random respondent will qualify and complete the survey.
status Integer This value will be returned as a 2(Active), 3(Complete), 4(Archived), 5(Paused), 6(Reconciled) or 7(System Paused).
length_of_interview Integer How many minutes will it take to complete the survey?
total_remaining Integer This is the number of completes left before the survey is complete. This value is the sum of num_respondents found inside associated campaign_quotas.
supplier_link String The entry URL when a respondent has qualified for the survey.
max_daily_completes Integer Total completes allowed per day.
reentry_interval Integer Time allowed for a respondent to re-enter this campaign. Never - null, Unlimited - 0, Days - number
country_language_id Integer Country language targeting for this campaign.
retarget_count Integer Total number of recontact records associated with the campaign.
buyer_account_id Integer ID associated wth creation of a buyer via the /adhoc_accounts route.

Create a campaign

Sample Request Payload

{
  "name": "Test Survey",
  "days_in_field": 3,
  "length_of_interview": 10,
  "supplier_link": "https://api.samplecompany.com/surveys/23423?id=",
  "incidence": 50,
  "country_language_id": 1,
  "buyer_account_id": 1,
  "supported_devices": [
    0,
    2
  ]
}

Sample Response

{
    "id": 11598926,
    "cpi": null,
    "length_of_interview": 10,
    "name": "Test Survey",
    "total_remaining": 0,
    "status": 5,
    "supplier_link": "https://api.samplecompany.com/surveys/23423?id=",
    "incidence": 50,
    "reentry_interval": null,
    "days_in_field": 3,
    "max_daily_completes": null,
    "is_retarget": false,
    "is_maid_targeted": false,
    "retarget_count": 0,
    "supported_devices": [
        0,
        2
    ],
    "country_language_id": 1,
    "custom_campaign_qualifications": [],
    "buyer_account_id": 1
}

Create a campaign with campaign-only metadata. Quotas, exclusions, and qualifications will need to be added through other routes.

HTTP Request

POST https://www.tapresearch.com/api/v1/campaigns

Required Parameters

Parameter Type Description
name String Name of the campaign
incidence Integer The percentage chance that a random respondent will qualify and complete the survey.
length_of_interview Integer How many minutes will it take to complete the survey?
country_language_id Integer Country language targeting for this campaign.
supplier_link String The entry URL when a respondent has qualified for the survey. This URL can be configured to accept various respondent values. See below:
cpi Decimal All CPIs are USD. This is the amount you will be charged per complete.

Optional Parameters

Parameter Type Description
is_retarget Boolean Set to true for the first wave of a multi-wave recontact project. This will focus sampling on respondents who are more active, to improve recontact rates on subsequent waves.
days_in_field Integer Number of days this campaign will be in the field. This value will be used to estimate feasibility for each associated campaign quota. Default value is 5.
supported_devices Integer Array Pass in 0 (tablet), 1 (mobile), and/or 2 (desktop).
max_daily_completes Integer Number of completes that will be allowed per day for this campaign.
reentry_interval Integer Time allowed for a respondent to re-enter this campaign. Never - null, Unlimited - 0, Minutes - number.
buyer_account_id Integer ID associated wth creation of a buyer via the /adhoc_accounts route.

Update a campaign

Sample Request Payload - Change name and length of interview for a campaign.

{
  "name": "New Survey Name",
  "length_of_interview": 10
}

Sample Request Payload - Set a campaign to active, allow mobile respondents, and set a maximum complete amount for 250.

{
  "status": 2,
  "max_daily_completes": 250,
  "supported_devices": [
    1
  ]
}

Sample Request Payload - Set a reentry interval for 5 days for a respondent. 

{
  "reentry_internval": 7200
}

Sample Response

{
    "id": 11611886,
    "cpi": null,
    "length_of_interview": 10,
    "total_remaining": 0,
    "status": 5,
    "supplier_link": "https://api.samplecompany.com/surveys/23423?id=",
    "name": "New Survey Name",
    "incidence": 50,
    "days_in_field": 3,
    "is_retarget": false,
    "max_daily_completes": null,
    "reentry_interval": null,
    "country_language_id": 1,
    "is_maid_targeted": false,
    "supported_devices": [
        0,
        2
    ],
    "country_language_id": 1,
    "custom_campaign_qualifications": [],
    "buyer_account_id": 1,
    "redirect_test_url": "http://www.tapresearch.com/api/v1/campaigns/11611886/redirect_test",
    "retarget_count": 0
}

Update a campaign that belongs to the authenticated user.

HTTP Request

PUT https://www.tapresearch.com/api/v1/campaigns/:campaign_id

Optional Parameters

Parameter Type Description
status Integer Only 2 (Active), 3 (Complete), 5 (Paused) will be accepted.

See Create Campaign for additional parameters

Get a specific campaign

Sample Response

{
    "id": 11611886,
    "cpi": null,
    "length_of_interview": 10,
    "name": "New Survey Name",
    "total_remaining": 500,
    "status": 5,
    "supplier_link": "https://api.samplecompany.com/surveys/23423?id=",
    "incidence": 50,
    "reentry_interval": null,
    "days_in_field": 3,
    "max_daily_completes": null,
    "is_retarget": false,
    "is_maid_targeted": false,
    "retarget_count": 0,
    "supported_devices": [
        0,
        2
    ],
    "country_language_id": 1,
    "custom_campaign_qualifications": [],
    "buyer_account_id": 1,
    "campaign_quotas": [
        {
            "id": 54661616,
            "num_respondents": 500,
            "is_global": false,
            "name": "LocationQuota",
            "is_click_balanced": true,
            "campaign_qualifications": [
                {
                    "question_id": 96,
                    "pre_codes": [
                        37
                    ]
                },
                {
                    "question_id": 97,
                    "pre_codes": [
                        650
                    ]
                }
            ]
        }
    ],
    "campaign_relationships": [
        {
            "id": 56369643627,
            "campaign_id": 11611886,
            "related_campaign_id": 11598926
        }
    ],
    "redirect_test_url": "https://www.tapresearch.com/api/v1/campaigns/11611886/redirect_test"
}

Retrieve campaign metadata along with associated quotas, exclusions, and qualifications.

HTTP Request

GET https://www.tapresearch.com/api/v1/campaigns/:id

Required Parameters

Parameter Type Description
id Integer This is the unique campaign identifier.

Redirect URL

Sample Response

{
    "redirect_test_url": "https://www.tapresearch.com/api/v1/campaigns/:id/redirect_test"
}

Retrieve the associated redirect_test_url for a specific campaign.

HTTP Request

GET https://www.tapresearch.com/api/v1/campaigns/:id/redirect_test

Required Parameters

Parameter Type Description
id Integer This is the unique campaign identifier.

Reject completes for a campaign

Sample Request

{
   "transaction_ids": [
    "30c60dbff51a9b8155609534f27de291",
    "22d2dccca27f438876613c46e6d50db3",
    "904895ae97e7412530746b3b709ee9e0",
    "751b36f52152bc765803e65aefe4ace7",
    "b41f02bed5a07fd69b1675f938bdcd05"
  ]
}

Reject completes that did not meet your quality standards.

HTTP Request

POST https://www.tapresearch.com/api/v1/campaigns/:id/reject_completes

Required Parameters

Parameter Type Description
id Integer This is the unique campaign identifier.
transaction_ids Array of strings Transaction ids that were attached to the id parameter when we sent the respondent into your survey.

Feasibility

Sample Response

{
  "campaign_quotas": [
    {
        "id": 446003,
        "estimated_completes": 32
    }
  ],
  "estimated_completes": 32,
  "over_num_days": 5,
  "id": 30309
}

{
  "campaign_quotas": [
      {
          "message": "We can't estimate feasibility for question ids: ( 723 )",
          "id": 959323
      }
  ],
  "estimated_completes": 0,
  "over_num_days": 5,
  "id": 153547
}

Get the total estimated number of completes based on your campaign quotas.

HTTP Request

GET https://www.tapresearch.com/api/v1/campaigns/:campaign_id/feasibility

Required Parameters

NONE

Realtime Feasibility

Sample Request

{
  "incidence":20,
  "length_of_interview" : 10,
  "days_in_field" : 5,
  "campaign_quotas" : [
    {
      "num_respondents": 10,
      "campaign_qualifications": [
        {
          "question_id": 97,
          "pre_codes": [
            662,
            525
          ]
        }
      ]
    },
    {
      "num_respondents": 20,
      "campaign_qualifications": [
        {
          "question_id": 42,
          "pre_codes": [
              18,
              19,
              20,
              21,
              22
          ]
        }
      ]
    }
  ]
}

Sample Response

{
  "campaign_quotas": [
    {
      "estimated_completes": 3
    },
    {
      "estimated_completes": 20
    }
  ],
  "estimated_completes": 23,
  "over_num_days": 5
}

Get the total estimated number of completes without having to create a campaign.

HTTP Request

POST https://www.tapresearch.com/api/v1/campaigns/realtime_feasibility

Required Parameters

Parameter Type Description
incidence Integer The percentage chance that a random respondent will qualify and complete the survey.
length_of_interview Integer How many minutes will it take to complete the survey?
campaign_quotas Array See "create a campaign quota" subsection.
cpi Decimal All CPIs are USD. This is the amount you will be charged per complete.
country_language_id Integer Country language targeting for this campaign.

Optional Parameters

Parameter Type Description
days_in_field Integer Number of days this campaign will be in the field. This value will be used to estimate feasibility for each associated campaign quota. Default value is 5.

Reconciliation

Sample Request

{
   "purchase_order":"tt489m900",
   "accepted_ids": [
    "30c60dbff51a9b8155609534f27de291",
    "22d2dccca27f438876613c46e6d50db3",
    "904895ae97e7412530746b3b709ee9e0",
    "751b36f52152bc765803e65aefe4ace7",
    "b41f02bed5a07fd69b1675f938bdcd05"
  ]
}

Reconcile a campaign using accepted survey complete ids.

HTTP Request

POST https://www.tapresearch.com/api/v1/campaigns/:id/reconcile

Required Parameters

Parameter Type Description
id Integer This is the unique campaign identifier.
accepted_ids Array of strings Transaction ids of survey completes that were accepted.

Optional Parameters

Parameter Type Description
purchase_order String Purchase order associated with the campaign.

Campaign Exclusions

Create a campaign exclusion

Sample Request Payload - A sampling of valid and invalid player_ids and transaction_ids.

{
  "player_ids": [
    "d35d05c7577ba0c11af91d75b522db18",
    "a356e6e1b1ee8b1ea21ebba41f6b18d6",
    "a356e6e1b1ee8b1ea21ebba41f6b18d6",
    "b57024d5a31f3d24934a7e8f60741d2b",
    "3b73ae4ddacc3b164a9efb56b3f5ad49"
  ],
  "transaction_ids": [
    "111111",
    "212334545",
    "00001e90514db20ed1003395d08d4285",
    "000023fc28bc5c1761a7d9075809f29f",
    "00002a30869515a24565d7647c052165",
    "00003ccc46583c2464ee326bf80aa528"
  ]
}

Sample Response 

{
    "player_ids_excluded": [
        "3b73ae4ddacc3b164a9efb56b3f5ad49",
        "a356e6e1b1ee8b1ea21ebba41f6b18d6",
        "b57024d5a31f3d24934a7e8f60741d2b"
    ],
    "player_ids_not_found": [
        "d35d05c7577ba0c11af91d75b522db18"
    ],
    "transaction_ids_excluded": [
        "00002a30869515a24565d7647c052165",
        "00003ccc46583c2464ee326bf80aa528"
    ],
    "transaction_ids_not_found": [
        "111111",
        "212334545",
        "00001e90514db20ed1003395d08d4285",
        "000023fc28bc5c1761a7d9075809f29f"
    ]
}

Create player and/or transaction exclusions for a specific campaign.

HTTP Request

POST https://www.tapresearch.com/api/v1/campaigns/:campaign_id/campaign_exclusions

Optional Parameters

Parameter Type Description
player_ids Array of strings Specify the player_ids to be excluded for the applicable campaign.
transaction_ids Array of strings Specify the transaction_ids to be excluded for the applicable campaign.

Response

Parameter Type Description
player_ids_excluded Array of strings A list of player_ids that were found and excluded.
player_ids_not_found Array of strings A list of player_ids that were not found.
transaction_ids_excluded Array of strings A list of transaction_ids that were found and excluded.
player_ids_excluded Array of strings A list of transaction_ids that were not found and excluded.

Campaign Export

Create a campaign export

Sample Request Payload - Request body in which you wish to filter on multiple transaction_ids and multiple player_ids.

{
  "player_ids": [
    "1245",
    "64354556"
  ],
  "transaction_ids": [
    "111111",
    "212334545"
  ]
}

Create an export of campaign demographic data in a CSV format. More information on the formatting of the CSV returned in the response may be found here.

HTTP Request

POST https://www.tapresearch.com/api/v1/campaigns/:campaign_id/export_demographics

Required Parameters

NONE

Optional Parameters

Parameter Type Description
transaction_ids String or Array of strings Any transaction_ids you wish to filter the CSV export on.
player_ids String or Array of strings Any player_ids you wish to filter the CSV export on.

Campaign Quotas

Create a campaign quota

Create a quota for a specific campaign.

Sample Request Payload - 32 respondents who are between the ages of 18-24, 30-34 and male.

{
  "num_respondents": 32,
  "name": "Age quota",
  "is_click_balanced": false,
  "is_global": false,
  "campaign_qualifications": [
    {
      "question_id": 42,
      "pre_codes": [
        18,
        19,
        20,
        21,
        22,
        23,
        24,
        30,
        31,
        32,
        33,
        34
      ]
    },
    {
      "question_id": 43,
      "pre_codes": [
        1
      ]
    }
  ]
}

Sample Response - Remember to record the id that is returned.

{
  "id": 274771,
  "num_respondents": 32,
  "is_global": false,
  "name": "Age quota",
  "is_click_balanced": false,
  "campaign_qualifications": [
    {
      "question_id": 42,
      "pre_codes": [
        18,
        19,
        20,
        21,
        22,
        23,
        24,
        30,
        31,
        32,
        33,
        34
      ]
    },
    {
      "question_id": 43,
      "pre_codes": [
        1
      ]
    }
  ]
}

HTTP Request

POST https://www.tapresearch.com/api/v1/campaigns/:campaign_id/campaign_quotas

Required Parameters

Campaign Quota

Parameter Type Description
num_respondents Integer The number of completes required before the quota is closed.
campaign_qualifications Array A list of objects that describe the qualifying criteria for the quota.

Campaign Qualification

Parameter Type Description
question_id Integer The question id of the qualification you want to target on.
pre_codes Integer Array A list of accepted pre-codes or values. See Answer Types section.

Optional Parameters

Campaign Quota

Parameter Type Description
name String Name of the campaign quota.
is_click_balanced Boolean Whether the campaign quota is click balanced.
is_global Boolean Whether this quota should serve as a cap/be applied to all other quotas across the applicable campaign? More information may be found here.

Update a campaign quota

Update a quota for a specific campaign.

Sample Request Payload - 50 respondents who are hispanic and live in specific zip code areas.

{
  "num_respondents": 50,
  "name": "Updated Quota Name",
  "is_click_balanced": true,
  "is_global": true,
  "campaign_qualifications": [
    {
      "question_id": 45,
      "pre_codes": [
        "95120",
        "94089",
        "94115",
      ]
    },
    {
      "question_id": 47,
      "pre_codes": [
        2,
        3,
        4,
        5,
        6,
        7,
        8,
        9,
        10,
        11,
        12,
        13,
        14
      ]
    }
  ]
}

HTTP Request

PUT https://www.tapresearch.com/api/v1/campaigns/:campaign_id/campaign_quotas/:id

Optional Parameters

Campaign Quota

Parameter Type Description
num_respondents Integer The number of completes required before the quota is closed.
name String Name of the campaign quota.
is_click_balanced Boolean Whether the campaign quota is click balanced.
is_global Boolean Whether this quota should serve as a cap/be applied to all other quotas across the applicable campaign? More information may be found here.
campaign_qualifications Array A list of objects that describe the qualifying criteria for the quota.

Campaign Qualification

Parameter Type Description
question_id Integer The qualification identifier you want to associate with the quota.
pre_codes Integer Array A list of accepted pre-codes or values. See Answer Types section.

Get a specific campaign quota

Get quota details along with associated campaign_qualifications.

Sample Response

{
  "id": 274771,
  "num_respondents": 32,
  "is_global": true,
  "name": "Updated Quota Name",
  "is_click_balanced": true,
  "campaign_qualifications": [
    {
      "question_id": 42,
      "pre_codes": [
        18,
        19,
        20,
        21,
        22,
        23,
        24,
        30,
        31,
        32,
        33,
        34
      ]
    },
    {
      "question_id": 43,
      "pre_codes": [
        1
      ]
    }
  ]
}

HTTP Request

GET https://www.tapresearch.com/api/v1/campaigns/:campaign_id/campaign_quotas/:id

Required Parameters

NONE

Delete a campaign quota

Remove a quota for a specific campaign

HTTP Request

DELETE https://www.tapresearch.com/api/v1/campaigns/:campaign_id/campaign_quotas/:id

Required Parameters

Parameter Type Description
id Integer Unique quota id

Feasibility

Sample Response

{
  "estimated_completes": 72,
  "over_num_days": 5
}

Get the estimated number of completes based on your targeting criteria and days_in_field.

HTTP Request

GET https://www.tapresearch.com/api/v1/campaigns/:campaign_id/campaign_quotas/:id/feasibility

Required Parameters

NONE

Campaign Retargeting

Add Respondents

Sample Request Payloads

{
  "retargeting_type": 1,
  "retargeting_ids": [
    {
      "id": "e2c479d73ff8a256317356a2be25aed4"
    }, {
      "id": "47427850ed299431ad173ec32868dbe9"
    }, {
      "id": "eeb784b657985398f24707e3f0969227"
    }, {
      "id": "69ca1702f0c1b9f508687e37b243e928"
    }, {
      "id": "1b240e62c891524bf62dab9dc18db028"
    }, {
      "id": "6385e12881c8ed49070411f309b43058"
    }
  ]
}

{
  "retargeting_type": 2,
  "expiration_date": "09-28-2019",
  "retargeting_ids": [
    {
      "id": "748F63F4-A2FA-4971-8154-11FE4D03C0C9",
      "replacement_id": "device_1"
    }, {
      "id": "DAFFA6A9-A37A-441E-9E65-73B79FC7B4B6",
      "replacement_id": "device_2"
    }, {
      "id": "82ACEFDA-06C1-4023-B897-F08ECBA330BB",
      "replacement_id": "device_3"
    }, {
      "id": "00000000-0000-0000-0000-000000000000",
      "replacement_id": "device_4"
    }, {
      "id": "8A7D2593-4835-4F04-BEBD-59FC2C3F3272",
      "replacement_id": "device_5"
    }, {
      "id": "C4FBAAB9-A853-498E-8843-6F6A4831C34B",
      "replacement_id": "device_6"
    }
  ]
}

Hashed MAIDs retargeting type identifiers should be generated using UPPER(SHA1(UPPER(REAL_MAID))

{
  "retargeting_type": 3,
  "retargeting_ids": [
    {
      "id": "9ed0d5fe11b11fd29fce8c1bdd593b3a35be5728"
    }, {
      "id": "f7e227a9751a68c2c7ec254b88f189aa37e76bc3"
    }, {
      "id": "1ede8b7aafa7dfee06912a9105664fcfaefad484"
    }, {
      "id": "07b552be2546b724e0aecefb10b4468d81d1d1cf"
    }, {
      "id": "2145473a23f6ba30bf2c5e80c48ed5272603d84e"
    }
  ]
}

Sample Response

{
  "cpi": "2.75",
  "days_in_field": 5,
  "id": 365,
  "incidence": 10,
  "length_of_interview": 20,
  "name": "PO1607074800517",
  "status": 2,
  "supplier_link": "https://api.samplecompany.com/survey/1?id=",
  "total_remaining": 100
}

Add respondent/device ID targeting to a campaign

HTTP Request

POST https://www.tapresearch.com/api/v1/campaigns/:id/campaign_retargets

Required Parameters

Parameter Type Description
retargeting_type Integer Specify the type of retargeting identifiers passed in. 0 (Transaction ID), 1 (Respondent ID), 2(Device ID), 3(Hashed Mobile Ad ID)
retargeting_ids Array A list of objects that specify the following criteria.

Retargeting Ids

Parameter Type Description
id String Required identifier used to target a respondent in a campaign.
replacement_id String Optional replacement value that is subsituted in the entry url. See campaign for details.

Optional Parameters

Parameter Type Description
expiration_date String Pass this parameter to override the default expiration date of 30 days. The format must be specified as "month-day-year", for example "08-17-2019".

Response

Parameter Type Description
id Integer This is the unique campaign identifier. You will need to use this parameter to get campaign details or update a specific campaign.
name String Name of the campaign
cpi String All CPIs are USD. This is the amount you will be charged per complete.
days_in_field Integer Number of days this campaign will be in the field. This value will be used to estimate feasibility for each associated campaign quota.
incidence Integer The percentage chance that a random respondent will qualify and complete the survey.
is_retarget Boolean Set to true for the first wave of a multi-wave recontact project. This will focus sampling on respondents who are more active, to improve recontact rates on subsequent waves.
status Integer This value will be returned as a 2(Active), 3(Complete), or 5(Paused).
length_of_interview Integer How many minutes will it take to complete the survey?
total_remaining Integer This is the number of completes left before the survey is complete. This value is the sum of num_respondents found inside associated campaign_quotas.
supplier_link String The entry URL when a respondent has qualified for the survey.

Remove Respondents

Sample Request Payload

{
  "retargeting_type": 1,
  "retargeting_ids": [
    "e2c479d73ff8a256317356a2be25aed4",
    "47427850ed299431ad173ec32868dbe9"
  ]
}

Sample Response

{
  "cpi": "2.75",
  "days_in_field": 5,
  "id": 365,
  "incidence": 10,
  "length_of_interview": 20,
  "name": "PO1607074800517",
  "status": 2,
  "supplier_link": "https://api.samplecompany.com/survey/1?id=",
  "total_remaining": 100
}

Remove respondent/device ID targeting to a campaign

HTTP Request

DELETE https://www.tapresearch.com/api/v1/campaigns/:id/campaign_retargets

Required Parameters

Parameter Type Description
retargeting_type Integer Specify the type of retargeting identifiers passed in. 0 (Transaction ID), 1 (Respondent ID), 2(Device ID)
retargeting_ids String Array List of retargeting identifiers to remove.

Campaign Relationships

Add Exclusion

Sample Request Payloads

{
  "campaign_id": 1234,
  "related_campaign_id": 5678
}

Sample Response

{
  "campaign_id": 1234,
  "related_campaign_id": 5678,
  "id": 222 
}

Excludes campaigns from being shown together for a user.

HTTP Request

POST https://www.tapresearch.com/api/v1/campaign_relationships/

Required Parameters

Parameter Type Description
campaign_id Integer Unique campaign id to be excluded from the related campaign.
related_campaign_id Integer Unqiue campaign id to be excluded from the related campaign.

Response

Parameter Type Description
id Integer Unique campaign relationship id. Used to identify the relationship between campaigns.
campaign_id Integer Unique campaign id to be excluded from the related campaign.
related_campaign_id Integer Unqiue campaign id to be excluded from the related campaign.

Remove Exclusion

Remove campaign exclusion.

HTTP Request

DELETE https://www.tapresearch.com/api/v1/campaign_relationships/:id

Required Parameters

Parameter Type Description
id Integer Unique campaign relationship id. Used to identify the relationship between campaigns.

Custom Screeners

A custom screener is targeting criteria that you can define yourself. These qualifications behave similarly to the qualifications available in the /qualifications endpoint, however they are not re-usable. Each time a custom screener is used, it must be re-created.

Create a custom qualification

Create a custom qualification question.

Sample Request 

{
    "name": "My qualification",
    "question_text": "What do you want to do with your life?",
    "answer_type": 0,
    "country_language_id": 1
}

Sample Response 

{
    "name": "My qualification",
    "question_id": 100112709,
    "question_text": "What do you want to do with your life?",
    "answer_type": 0,
    "en_translation": "What do you want to do with your life?",
    "country_language_id": 1
}

HTTP Request

POST https://www.tapresearch.com/api/v1/custom_qualifications

Required Parameters

Parameter Type Description
question_text String This is the question text that will be served to our respondents.
answer_type Integer The answer format to be used for the qualification. Mapping information may be found here.
country_language_id Integer Country language targeting for the qualification.

Optional Parameters

Parameter Type Description
name String Name of the custom qualification.
customer_id Integer The unique identifier associated with your account. See Callbacks section for more information. This is set automatically and unable to be edited.

Response

Parameter Type Description
name String Name of the custom qualification.
question_id Integer This value will be used to fetch qualification details.
question_text String This ans the question text that will be served to our respondents.
answer_type Integer The answer format to be used for the qualification. Mapping information may be found here.
country_language_id Integer Country language targeting for the qualification.
en_translation String The English translation of the question.

Create a custom qualification answer

Create a custom qualification answer to correspond with your custom qualifications.

Sample Request Payload - Update custom qualification name

{
    "option_text": "Corporate Chef"
}

Sample Response 

{
    "option_text": "Corporate Chef",
    "pre_code": 4,
    "en_translation": "Corporate Chef",
    "country_language_id": 1
}

HTTP Request

POST https://www.tapresearch.com/api/v1/custom_qualifications/:question_id/custom_qualification_answers

Required Parameters

Parameter Type Description
option_text String The answer text that is shown to our respondents.

Response

Parameter Type Description
option_text String The answer text that is shown to our respondents.
pre_code Integer This is the value(s) you will be passing into the campaign_qualifications pre_codes array to describe which respondents qualify for a survey.
en_translation String The English translation of the question.
country_language_id Integer Country language targeting for the qualification.

Create a campaign qualification

Create a campaign qualification which will allow you to associate your custom qualifications and answers to a specific campaign.

Sample Request Payload - 

{
    "question_id": 100112713,
    "pre_code_values": "1"
}

Sample Response 

{
    "id": 50394692475,
    "question_id": 100112713,
    "pre_codes": [
        1
    ]
}

HTTP Request

POST https://www.tapresearch.com/api/v1/campaigns/:campaign_id/campaign_qualifications

Required Parameters

Parameter Type Description
id Integer This the unique identifier of the campaign qualification.You will need to use this parameter to update a specific campaign qualification.
question_id Integer This value will be used to fetch qualification details.
pre_code_values String The pre_code value received in the response of returned when creating a custom qualification answer. See Create a custom qualification answer for more information.

Response

Parameter Type Description
question_id Integer This value will be used to fetch qualification details.
pre_codes Array of Integers Values to be passed in the pre_codes array to describe which respondents qualify for a survey.

Update a campaign qualification

Update the pre_code_values for a specified campaign qualification.

Sample Request

{
    "pre_code_values": "2"
}

Sample Response

{
    "id": 50395232189,
    "question_id": 100112748,
    "pre_codes": [
        2
    ]
}

HTTP Request

PUT https://www.tapresearch.com/api/v1/campaigns/:campaign_id/campaign_qualifications/:id

Optional Parameters

Parameter Type Description
pre_code_values String The pre_code value received in the response of returned when creating a custom qualification answer. See Create a custom qualification answer for more information.

Delete a campaign qualification

Remove a campaign qualification

HTTP Request

DELETE https://www.tapresearch.com/api/v1/campaigns/:campaign_id/campaign_qualifications/:id

Required Parameters

Parameter Type Description
id Integer This the unique identifier of the campaign qualification.

Adhoc Accounts

Create an Adhoc Account

Create an adhoc account also known as a buyer that can subsequently be provided in requests to the /campaigns endpoint using the parameter 'buyer_account_id'.

Sample Request Payload

{
    "buyer_name":"buyer",
    "buyer_identifier":"buyer1234"
}

Sample Response

{
    "id": 1,
    "buyer_name": "buyer",
    "buyer_identifier": "buyer1234"
}

HTTP Request

POST https://www.tapresearch.com/api/v1/adhoc_accounts

Optional Parameters

Parameter Type Description
buyer_name String Name of the buyer.
buyer_identifier String Identifier of the buyer.

Response Parameters

Parameter Type Description
id Integer ID to be passed in as the 'buyer_account_id' when using the /campaigns endpoint.
buyer_name String Name of the buyer.
buyer_identifier String Identifier of the buyer.

Answer Types

When you make a request to our qualifications route, there will be an answer_type field returned with every object. The answer_type value will determine how the campaign_qualifications pre_codes array is constructed.

When answer_type is a 0 or 1

Pass in every pre code that qualifies a respondent. For example, the gender qualification has two accept answers, male and female, with pre codes of 1 and 2, respectively.

If you passed in:

When answer_type is equal to 5

Qualifications with answer_type 5 will return with an empty qualification_answers array. You will need to construct an array of customer values.

Supplier Links

Transaction ID

Specify where you want this ID to appear using {ID}: https://api.samplecompany.com/surveys/23423?id={ID}

Here is an example upon survey entry: https://api.samplecompany.com/surveys/23423?&id=46f8bb49ad688570abb84eafae38733d

This value must be passed back in the status callback URLs.

Respondent ID

https://api.samplecompany.com/surveys/23423?respondent_id={RESPONDENT_ID}&id={ID}

This is the unique alphanumeric ID for this respondent.

Retarget Identifier

https://api.samplecompany.com/surveys/23423?retarget_id={RETARGET_IDENTIFIER}&id={ID}

{RETARGET_IDENTIFIER} will be replaced with the retargeting_id as provided in Campaign Retargeting.

If a replacement_id is specified in Campaign Retargeting, that value will be used instead.

Respondent Demographics

https://api.samplecompany.com/surveys/23423?id={ID}&age={AGE}&gender={GENDER}&zip={ZIP_CODE}&education={633}

{AGE} will be an integer.

{GENDER} will be either M (male) or F (female).

{ZIP_CODE} will be an alphanumeric string.

Any {QUESTION_ID} from the /qualifications route may now be used as a substitution value. Any invalid values will be safely ignored. The URL example above has been updated with an example using the Education Level question_id.

For the above example upon survey entry the URL will look like this: https://api.samplecompany.com/surveys/23423?id=46f8bb49ad688570abb84eafae38733d&age=23&gender=M&zip=90210&education=10

Security (optional)

We now support the creation of an HMAC-SHA1 security hash to be appended to the end of a Supplier Link using the substitution value {LINK_HASH} used in conjunction with a new parameter called security_hash.

The HMAC-SHA1 security hash should be generated using the fully constructed Supplier Link less the {LINK_HASH} substitution value and the customer’s API secret.

The {LINK_HASH} should always be the final value appended to a supplier link.

Example

Use the customer API secret and Fully Constructed Supplier link sans the {LINK_HASH} substitution value to generate the HMAC-SHA1 security hash. See Callbacks for an additional example.

Parameter Type Description
security_hash String HMAC-SHA1 security hash generated using the fully constructed Supplier Link less the {LINK_HASH} substitution value.

Insights API

List organization projects

Sample Response

{
  "data": {
    "id": "projects_list_683",
    "type": "projects_list",
    "attributes": {
      "page": 1,
      "pages": 2,
      "projects": {
        "data": [
          {
            "id": "87",
            "type": "project",
            "attributes": {
              "id": 87,
              "name": "A one time project",
              "project_type": "one_time",
              "campaigns": {
                "data": [
                  {
                    "id": "478",
                    "type": "campaign",
                    "attributes": {
                      "id": 478,
                      "status": "complete",
                      "complete_at": "2022-07-01T19:01:18.000Z",
                    },
                    "links": {
                      "results_url": "https://www.tapresearch.com/insights_api/projects/87/campaigns/478",
                      "columns_url": "https://www.tapresearch.com/insights_api/projects/87/campaigns/478/columns"
                    }
                  }
                ]
              }
            }
          },
          {
            "id": "318",
            "type": "project",
            "attributes": {
              "id": 318,
              "name": "A recurring project",
              "project_type": "recurring",
              "campaigns": {
                "data": [
                  {
                    "id": "509",
                    "type": "campaign",
                    "attributes": {
                      "id": 509,
                      "status": "complete",
                      "complete_at": "2022-07-01T19:01:18.000Z",
                    },
                    "links": {
                      "results_url": "https://www.tapresearch.com/insights_api/projects/318/campaigns/509",
                      "columns_url": "https://www.tapresearch.com/insights_api/projects/318/campaigns/509/columns"
                    }
                  },
                  {
                    "id": "510",
                    "type": "campaign",
                    "attributes": {
                      "id": 510,
                      "status": "complete",
                      "complete_at": "2022-07-07T19:01:18.000Z",
                    },
                    "links": {
                      "results_url": "https://www.tapresearch.com/insights_api/projects/318/campaigns/510",
                      "columns_url": "https://www.tapresearch.com/insights_api/projects/318/campaigns/510/columns"
                    }
                  },
                  {
                    "id": "511",
                    "type": "campaign",
                    "attributes": {
                      "id": 511,
                      "status": "active",
                      "complete_at": null,
                    },
                    "links": {
                      "results_url": "https://www.tapresearch.com/insights_api/projects/318/campaigns/511",
                      "columns_url": "https://www.tapresearch.com/insights_api/projects/318/campaigns/511/columns"
                    }
                  }
                ]
              }
            }
          }
        ]
      }
    }
  }
}

Get a list of projects for the organization. Request identity/organization is derived from the Authorization header.

Note: Projects that are still in draft are not returned.

HTTP Request

GET https://www.tapresearch.com/insights_api/projects

Required Parameters

NONE

Optional Parameters

Parameter Type Description
project_type String Pass this parameter to return only projects of the specified type. Accepted values: recurring or one_time
page Integer Response is paginated, 30 projects per page. By default this endpoint returns the first page. If you have more than 30 projects, you will need to make subsequent requests using the page parameter.

Response

Response follows the JSON:API specification. Each resource type returns a top-level data key, and within that, an attributes field containing the data.

Top-Level Fields

Parameter Type Description
id String Unique identifier in the format: projects_list_<Organization ID>
type String Resource type: projects_list
attributes Object Object which contains the resource data (see below)

data.attributes Fields

Parameter Type Description
page Integer The current page being returned
pages Integer The total number of pages for this resource
projects Array of projects List of projects for the organization. If a project_type param was not specified, the list may contain both one-time and recurring projects (if they both exist). See below for projects item attributes.

projects Attributes

Parameter Type Description
id Integer Project ID
name String Project name
project_type String Project type: one_time or recurring
campaigns Array of campaigns List of campaigns for the project. One-time projects will have only 1 campaign returned. Recurring project waves are in order using 0-based indexing where wave_number = index + 1. See below for campaigns item attributes and campaigns item links.

projects.campaigns Attributes

Parameter Type Description
id Integer Campaign ID
status String Campaign status: active / paused / complete / archived
complete_at String or null Date completed in RFC 3339 format, or null (when campaign is not complete)
Parameter Type Description
results_url String or null Endpoint URL that returns the results CSV file, or null (when there's no responses yet).
columns_url String or null Endpoint URL that returns the CSV file headers mapping { column_id: "Column title" }

Get a specific project

Sample Response

{
  "data": {
    "id": "318",
    "type": "project",
    "attributes": {
      "id": 318,
      "name": "A recurring project",
      "project_type": "recurring",
      "campaigns": {
        "data": [
          {
            "id": "509",
            "type": "campaign",
            "attributes": {
              "id": 509,
              "status": "complete",
              "complete_at": "2022-07-01T19:01:18.000Z",
            },
            "links": {
              "results_url": "https://www.tapresearch.com/insights_api/projects/318/campaigns/509",
              "columns_url": "https://www.tapresearch.com/insights_api/projects/318/campaigns/509/columns"
            }
          },
          {
            "id": "510",
            "type": "campaign",
            "attributes": {
              "id": 510,
              "status": "complete",
              "complete_at": "2022-07-07T19:01:18.000Z",
            },
            "links": {
              "results_url": "https://www.tapresearch.com/insights_api/projects/318/campaigns/510",
              "columns_url": "https://www.tapresearch.com/insights_api/projects/318/campaigns/510/columns"
            }
          },
          {
            "id": "511",
            "type": "campaign",
            "attributes": {
              "id": 511,
              "status": "active",
              "complete_at": null,
            },
            "links": {
              "results_url": "https://www.tapresearch.com/insights_api/projects/318/campaigns/511",
              "columns_url": "https://www.tapresearch.com/insights_api/projects/318/campaigns/511/columns"
            }
          }
        ]
      }
    }
  }
}

Get a specific project by ID with its associated campaigns.

HTTP Request

GET https://www.tapresearch.com/insights_api/projects/:project_id

Required Parameters

NONE

Response

Parameter Type Description
id Integer Project ID
name String Project name
project_type String Project type: one_time or recurring
campaigns Array of campaigns List of campaigns for the project. One-time projects will have only 1 campaign returned. Recurring project waves are in order using 0-based indexing where wave_number = index + 1. See below for campaigns item attributes and campaigns item links.

campaigns.attributes

Parameter Type Description
id Integer Campaign ID
status String Campaign status: active / paused / complete / archived
complete_at String or null Date completed in RFC 3339 format, or null (when campaign is not complete)
Parameter Type Description
results_url String or null Endpoint URL that returns the results CSV file, or null (when there's no responses yet).
columns_url String or null Endpoint URL that returns the CSV file headers mapping { column_id: "Column title" }

Get the CSV headers for a campaign

Sample Response

{
  "data": {
    "id": "columns_510",
    "type": "campaign_columns",
    "attributes": {
      "columns": {
        "id": "Id",
        "time": "Time",
        "panelist_id": "Panelist ID",
        "status": "Status",
        "pq_42": "Age",
        "pq_101": "Division",
        "pq_97": "Dma",
        "pq_113": "Ethnicity",
        "pq_43": "Gender",
        "pq_122": "Region",
        "pq_633": "Education",
        "pq_2189": "Employment",
        "pq_14785": "Household income",
        "pq_14785_non_bucketed": "Household income (raw value)",
        "pq_96": "State",
        "pq_45": "Zip",
        "pq_50017": "Birthday",
        "pq_50020": "Parent of children under 18",
        "tq_1325": "Do you ever travel internationally?",
        "tq_1326": "Which of the following countries have you visited?",
        "tq_1327": "Rank the following countries in order of places you want to visit.",
        "tq_1328": "Which of these factors is most important to you when considering international travel?",
      }
    }
  }
}

Returns the CSV file header mapping for a given campaign.

HTTP Request

GET https://www.tapresearch.com/insights_api/:project_id/campaigns/:campaign_id/columns

Required Parameters

NONE

Base Data Columns

Column Description
id Respondent session identifier
time Session start timestamp
panelist_id Unique respondent identifier
status Respondent survey result status (usually Complete)

Demographic Columns

Column Description
pq_<Demographic ID> These columns represent the various demographic data points returned.

Survey Question Columns

Column Description
tq_<Root Question ID> These columns represent the answers to the survey questions.

Get a campaign result CSV

Returns the CSV results export for a given campaign.

HTTP Request

GET https://www.tapresearch.com/insights_api/:project_id/campaigns/:campaign_id

Required Parameters

NONE

Response

HTTP Headers

Header Value
Content-Type text/csv
Content-Disposition attachment; filename="campaign_result_<Campaign ID>.csv"

CSV Format

Refer to the CSV columns endpoint to see the data returned for a campaign.

Callbacks


# Sample redirect URL
redirect_url = "https://www.tapresearch.com/router/customers/fdbe1666a0146f54d85dbc90a5f12552/cps/complete?tid=53b183dd1a729fa04acd9ba2283af896"

# Generate HMAC-SHA1
api_secret = "f81324b50c807cd7118ffe32a34a6681"
digest = OpenSSL::Digest.new("sha1")
sha1 = OpenSSL::HMAC.hexdigest(digest, api_secret, redirect_url)

puts sha1 # e48ad262a413283078f5841cb3beb8d75def03a2

redirect_url += "&tr_sech=#{sha1}"

These are the routes you will need to use when you redirect a respondent back to TapResearch.

Parameter Type Description
(customer_id) String The unique identifier associated with your account.
tid String Unique transaction identifier that is passed to you on survey entry.
tr_sech String HMAC-SHA1 security hash generated using the redirect URL (less the tr_sech parameter) and your API secret.

Errors

The TapResearch API uses the following error codes:

Error Code Meaning
400 Bad Request -- Your request is invalid.
401 Unauthorized -- Your API key is wrong.
403 Forbidden -- The kitten requested is hidden for administrators only.
404 Not Found -- The specified kitten could not be found.
405 Method Not Allowed -- You tried to access a kitten with an invalid method.
406 Not Acceptable -- You requested a format that isn't json.
410 Gone -- The kitten requested has been removed from our servers.
418 I'm a teapot.
422 Unprocessable Entity -- You request is a duplicate of an existing resource or it contains invalid parameters/data.
429 Too Many Requests -- You're requesting too many kittens! Slow down!
500 Internal Server Error -- We had a problem with our server. Try again later.
503 Service Unavailable -- We're temporarily offline for maintenance. Please try again later.

Changelog

4/8/2022

1/6/2022

11/1/2021

10/6/2021

9/8/2021

8/20/2021

8/9/2021

v1.07

v1.06

v1.05

v1.04

v1.03

v1.02

v1.01

v1.00

Contact Us

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

shell ruby python javascript