Summary

This document contains an easy to use API allowing our partners to:


Description

The Live Alert API is designed to allow you as the publisher to be able to decide which of your respondents are a match for any of our surveys. To effectively use this API, you will need to have detailed information collected about your users. At the very minimum, it is recommended that you profile and store information about your user's date of birth, gender, ethnicity, postal code, country, regions, household income, marital status, level of education and the languages they speak. These datapoints are just the basics, you should collect as much information as possible about your users. It will result in better targeting and a better user experience.

Our listDatapoints and datapoint commands will give you detailed information about our datapoints so that you can map them to the ones in your system. This is an important starting point to ensure that you can validate whether or not a user is a match for a particular survey.

Once you have mapped all the datapoints you choose to use, you will be set for working on the integration. Firstly, by calling our Inventory API command you will see a list of all of our current surveys. Look out for surveys which are in field - these are the ones you want your users going to. The inventory command will give you some basic information about each of our surveys and you can choose which ones you would like to consider for you users. You might decide to consider all surveys that are in field. Take into account that paused surveys will return to in field.

When you have your list of chosen surveys, you must then use the targeting command to get a detailed breakdown of the requirements for each of those surveys. You will receive details of the survey's target demographic. With this data (and the datapoint mapping you carried out before) you will be able to accurately validate which surveys are the right choice for each of your users.

Next, by using our createLink API command you will be able to generate the entry point to each survey. You will receive one unique URL for that survey. There is no need to call the createLink API more than once for a single project. The same URL can be used for all users.

You are almost ready to send the user to us, but before you do, it is wise to check if the user is likely to be rejected by our de-duplication criteria. By calling our duplicateCheck command before sending the user to us, you will be able to see if they have already attempted this survey or another survey from the same survey group. We also have a duplicateChecks command which will allow you to check multiple surveys at a time if you prefer that method.

Finally, you can use our log and stats API to check how a project is performing at any time. We will send you stats showing your CR and EPC alone as well as the overall project performance with all suppliers combined.

When the respondent completes a survey, we will send you a notification. Please refer to our API Publisher Callback Specifications document for a detailed description of the notifications we can send back to you.

Livealert Quick Reference Guide

Command Description Recommended Frequency
livealert/listDatapoints/1 Use this to see our entire list of datapoints. Once every 12 hours to checkfor new datapoints
livealert/datapoint/1 For each datapoint you want to map, you should invoke the datapoint command to see the possible answers. Once every 12 hours to checkfor changes to datapoints
livealert/inventory/1 This API is used to list all of the available surveys. No longer than once every 10minutes. If the lastModified field is more recent than the last time you made the call for a survey, you should call the targeting command for that survey.
livealert/targeting/1 For each survey that you want to target, you should invoke the targeting command to see the qualifiers needed for that survey You will only need to make this call for a particular survey again if the "lastModified" field mentioned above has changed.
livealert/createLink/1 Creates a link for the survey. You can use this link for all users, just append all the mandatory parameters mentioned below and any other information you have about each user, relevant to this project You will only need to do this once per survey. The entry link will never change for a survey.
livealert/duplicateCheck/1 This API is used to determine if a respondent is likely to be rejected from a survey because of our deduplication criteria. Make this API call the moment before you display the survey tothe user.
livealert/log/1 This API is used to obtain the logs of the individual starts on surveys. You can use this at a frequency of your choosing
livealert/stats/1 This API is used to obtain the latest statistics on survey performance. You can use this at a frequency of your choosing

Additional tracking parameters in callbacks

In addition to the parameters specified in our API Publisher Callback Specifications document, you can receive additional parameters in your callbacks.

The aim of these additional parameters is to give you more detail in the process each respondent has followed on our side.

Parameter name: liveP

This parameter indicates the steps of the process that the respondent went through, using the following codes:

  • 1 - Screened. We asked some information to the respondent because we did not receive and we did not have all the information required to decide if he qualified for the survey.
  • 2 - Redirected. The respondent was redirected to the survey.
  • 4 - De-duplication. The respondent was rejected because of de-duplication.
  • 8 - Security. The respondent was rejected because of security issues.

The final value of this parameter will be the SUM of all the characteristics that apply to each session. For example:

  • liveP=3 means that we screened and redirected the respondent to the survey.
  • liveP=1 means that we screened the respondent.
  • liveP=8 means that we found a security issue with this respondent.
  • liveP=2 means that we redirected the respondent to the survey without any additional screening.

Note that there are some values that you will never receive, like 10, which would mean that we found a security issue and redirected the respondent to the survey.

Parameter name: liveS

This parameter will only be sent if we found a security issue with the respondent (liveP >= 8). It will give you more detail on the reason why we consider there was a security issue with the respondent.

  • 1 - Blocked panelist.
  • 2 - Suspicious IP (known proxy)
  • 3 - Invalid IP.
  • 4 - IP geolocation does not match the country we received.

Parameter name: liveI

This parameter will only be sent if we received an invalid value in the mandatory parameters (see the createLink command for details on the valid formats):

  • 1 - Invalid birthday.
  • 2 - Invalid gender.
  • 3 - Invalid country.
  • 4 - Invalid postal code.
  • 5 - IP geolocation does not match the country we received.

Parameter name: quotaThrottle

This parameter will only be present if we terminate a respondent due to the quota they are a match for being full at that time. This project can be reconsidered for that respondent after 10 minutes. You can learn more about quota throttling in the section about our Targeting API.

  • 1 - quotaThrottle was currently full.