Inventory

This API is used to list all of the available surveys.

Command

"livealert/inventory/1"

Recommended Frequency

No longer than once every 10 minutes. 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. We refresh our cache every 60 seconds, so you should try and call this command as close to this as possible to ensure you have the most up to date information about each project.



Inputs

The following values are expected in the JSON body:

Name Type Required Description
command String

Must be "livealert/inventory/1"
country String

Optional 2 digit ISO Country Code, e.g. US, GB, CA, etc... Restricts projects to match this country.
allowRecontacts Long

Optional boolean parameter that indicates if projects with recontacts should be included in the inventory. Default is false.
type Integer

Optional parameter that indicates the kind of projects that should be returned:

  1. All
  2. Surveys
  3. Offers
category String

Optional parameter that indicates the category of projects that should be returned:

B2B B2C

Outputs

Name Type Description
projects Date[]

List of projects. Each 'project' contains:

Name Type Description
rfg_id String Unique identifier for survey. Usually in the form RFG000000-000
title String Description of survey, suitable for display to respondents
country String 2 digit ISO Country Code, e.g. US, GB, CA, etc...
cpi String Amount paid to you for each complete
estimatedIR Integer The overall incidence rate of the survey (the % likelihood that a person will qualify after meeting the targeting criteria)
estimatedLOI Integer The estimate amount of time (in minutes) it will take to complete the survey
endOfField ISO Date The date the study is anticipated to close. (This field may not always be present)
desiredCompletes Integer Total # of completes needed
currentCompletes Integer Total # of completes already accomplished
collectsPII Boolean True, if the survey asks for personally identifiable information
state Integer Possible values:
0. New Project
1. Pre-Launch
2. In Field
3. Paused
4. Closed

You should only send respondents to projects with state = 2 (in-field).

datapoints String[] List of datapoint names that this survey targets. The full targeting is obtained for a project using the targeting API.
lastModified ISO Date Timestamp of last modification to project. You should watch this date on all of your active projects. Any time this date changes (is more recent that your last check), you should update the project information. After a survey is closed, it will show up in our inventory for 5 more days, so you can get updated values (stats, for example) for closed surveys too. You should rely on the inventory or the targeting command to update the survey state based on the value of "state" and "lastModified".
duplicationKey String Duplication key used by this project. Different projects can be grouped using a duplicationKey, if this is the case, the duplicate check will be applied considering the whole group instead of a single project. (This field will only be present if the project is part of a group)
filterMode Integer Indicates how the respondent will be considered as a duplicate in a group: based on starts or based on completes.
0. Starts
1. Completes

(This field will only be present if the project is part of a group)
isRecontact Boolean Indicates if the project has recontacts.
phoneSupported Integer Indicates if we have confirmed that the survey is optimized for phones. Possible values:
0 - Unknown (We do not know if the survey accepts phones)
1- The survey accepts phones
2 - The survey does not accept phone
tabletSupported Integer Indicates if we have confirmed that the survey is optimized for tablets. Possible values:
0 - Unknown (We do not know if the survey accepts tablets)
1- The survey accepts tablets
2 - The survey does not accept tablets
type Integer Indicates the type of the project. Possible values:
1 - Survey
2 - Offer
category String Indicates the category of the project. Possible values:
B2B
B2C

Example Command

{
  "command": "livealert/inventory/1",
  "country": "CA",
  "allowRecontacts": false,
  category: "B2C"
}

Example Response

{
    "response":{
        "projects":[
            {
                "rfg_id":"RFG780558-001",
                "title":"Share your opinion with us!",
                "country":"CA",
                "cpi":"$1.25",
                "estimatedIR":15,
                "estimatedLOI":30,
                "desiredCompletes":400,
                "currentCompletes":12,
                "collectsPII":false,
                "state":2,
                "datapoints":[
                    "Age",
                    "Gender",
                    "Language"
                ],
                "lastModified":"2014-08-08T01:30:49Z",
                "isRecontact":false,
                "mobileOptimized":"confirmed",
		type: 1,
		category: "B2C"
            },
            ...,
            {
                "rfg_id":"RFG92713-050",
                "title":"Please share your opinion!",
                "country":"CA",
                "cpi":"$2.10",
                "estimatedIR":16,
                "estimatedLOI":33,
                "desiredCompletes":28,
                "currentCompletes":9,
                "collectsPII":false,
                "state":2,
                "datapoints":[
                    "Age",
                    "Gender",
                    "Household Residents",
                    "List of FSAs (CA)"
                ],
                "lastModified":"2014-08-08T00:33:40Z",
                "isRecontact":false,
                "mobileOptimized":"confirmed",
		type: 1,
		category: "B2C"
            }
        ]
    }
}