NAV Navbar
shell ruby

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

[
  {
      "cpi": "3.15",
      "days_in_field": 3,
      "id": 14706,
      "incidence": 10,
      "length_of_interview": 20,
      "name": "Test Survey 1",
      "status": 2,
      "supplier_link": "https://api.samplecompany.com/survey/1?id=",
      "total_remaining": 6,
      "max_daily_completes": null,
      "renentry_interval": null,
      "country_language_id": 1
  },
  {
      "cpi": "3.69",
      "days_in_field": 10,
      "id": 14707,
      "incidence": 20,
      "length_of_interview": 15,
      "name": "Test Survey 2",
      "status": 2,
      "supplier_link": "https://api.samplecompany.com/survey/2?id=",
      "total_remaining": 37,
      "max_daily_completes": null,
      "renentry_interval": null
      "country_language_id": 1
  }
]

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 This is the amount you will payout 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), 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.
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.

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,
  "supported_devices": [
    0,
    2
  ]
}

Sample Response

{
  "cpi": "2.5",
  "days_in_field": 3,
  "id": 14724,
  "incidence": 50,
  "length_of_interview": 10,
  "name": "Test Survey",
  "status": 5,
  "supplier_link": "https://api.samplecompany.com/surveys/23423?id=",
  "total_remaining": 0,
  "max_daily_completes": null,
  "country_language_id": 1,
  "supported_devices": [
      0,
      2
  ]
}

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 This is the amount you will payout per complete.

Transaction ID (required)

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

OR

It will be automatically appended to the end of the URL: https://api.samplecompany.com/surveys/23423?&id=

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}

{AGE} will be an integer.

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

{ZIP_CODE} will be an alphanumeric string.

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

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

{
  "name": "Test Survey",
  "days_in_field": 8
  "cpi": "2.50",
  "length_of_interview": 10,
  "supplier_link": "https://api.samplecompany.com/surveys/23423?id=",
  "incidence": 50,
  "max_daily_completes": 250,
  "reentry_interval": 7200,
  "supported_devices": [
    0,
    2
  ]
}

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

{
  "cpi": "3.15",
  "days_in_field": 12,
  "id": 14706,
  "incidence": 20,
  "length_of_interview": 20,
  "name": "Test Survey #123",
  "status": 2,
  "supplier_link": "https://api.samplecompany.com/surveys/234230?id=",
  "total_remaining": 6,
  "max_daily_completes": 250,
  "country_language_id" : 1,
  "supported_devices": [
    0,
    1,
    2
  ],
  "campaign_relationships" : [
    {
      "campaign_id": 14706,
      "related_campaign_id": 14709,
      "id": 538
    }
  ]
  "campaign_quotas": [
    {
      "id": 273057,
      "name": "Test Campaign Quota",
      "num_respondents": 6,
      "campaign_qualifications": [
        {
          "question_id": 42,
          "pre_codes": [
            30,
            31,
            32,
            33,
            34,
            35,
            36,
            37,
            38,
            39,
            40
          ]
        },
        {
          "question_id": 43,
          "pre_codes": [
            1,
            2
          ]
        }
      ]
    }
  ]
}

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.

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 This is the amount you will payout 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 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,
  "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,
  "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
qualification_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.

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,
  "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.
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,
  "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 This is the amount you will payout 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.

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.

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 – 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

1.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.