Skip to main content

FV Kinesis Support

All the topics, resources needed for FV Kinesis.

FocusVision Knowledge Base

Panel Community 4.5 REST

1:  Auth

1.1:  portal.auth.login

Create a panelist session and return panelist information needed for future API requests.

Example URL: http://www.example.com/panelinstall/...tal.auth.login

JSON Input Fields:

Parameter Type Description Required
panelid number The panelid the session will log as the current panel. yes
portalid number The portalid the session will log as the current community. yes
username string The email address associated with the panelist. yes
password string The password associated with the panelist. yes

Example POST:


{
    "panelid":1,
    "portalid":1,
    "username":"demo",
    "password":"demo"
}


JSON Output Fields on Success:

Parameter Type Description Since
success boolean true The login was successful.  
seskey string The sessionKey of the user session.  
panelistid number The id of the panelist who has logged in.  
email string The email address of the panelist who has logged in.
fullname string The full name of the panelist who has logged in.  
firstname string The first name of the panelist who has logged in. 4.3
lastname string The last name of the panelist who has logged in. 4.3

Example success:


{
    success:    true,
    seskey:     'ce512c91',
    panelistid: 15,
    email:      'demo@example.com',
    fullname:   'Demo Panelist'
    firstname:  'Demo'
    lastname:   'Panelist'
}


JSON Output Fields on Failure:

Parameter Type Description
success boolean false The login was unsuccessful.
error string The error message.
errno number The error number.

Example failure:


{
    success: false,
    error:   'Invalid username/password.',
    errno:   0
}

1.2:  portal.auth.logout

Logout of the current open API session.

Example URL: http://www.example.com/panelinstall/...al.auth.logout

JSON Input Fields:

Parameter Type Description Required
seskey string The session key of the session to logout of. yes

Example POST:


{
    seskey: 'ce512c91'
}


JSON Output Fields on Success:

Parameter Type Description
success boolean true The logout was successful.

Example success:


{
    success: true
}


JSON Output Fields on Failure:

Parameter Type Description
success boolean false The logout was unsuccessful.
error string The error message.
errno number The error number.

Example failure:


{
    success: false,
    error:   'Session string is invalid',
    errno:   20101
}

1.3:  portal.auth.validate

Checks that the current seskey is valid and return panelist information needed for future API requests.

Example URL: http://www.example.com/panelinstall/....auth.validate

JSON Input Fields:

Parameter Type Description Required
seskey string The sessionKey of the session to validate. yes

Example POST:


{
    seskey: 'ce512c91'
}


JSON Output Fields on Success:

Parameter Type Description
success boolean true The validation was successful.
seskey number The sessionKey of the validated panelist.
panelistid number The panelistid of the validated panelist
email string The email address of the validated panelist.
fullname string The full name of the validated panelist.

Example success:


{
    success:    true,
    seskey:     'ce512c91',
    panelistid: 15,
    email:      'demo@example.com',
    fullname:   'Demo Panelist'
}


JSON Output Fields on Failure:

Parameter Type Description
success boolean false The validation was unsuccessful.
error string The error message.
errno number The error number.

Example failure:


{
    success: false,
    error:   'Session string is invalid',
    errno:   20101
}

 

2:  Email

2.1:  portal.email.sendOptOutConfirmation

Sends an opt-out confirmation email to a panelist. The system will automatically use the pre-defined email template from the community the panelist belongs to. When the panelist clicks on the link embedded in the email the system will mark the panelist as unsubscribed. If a custom API powered community is used then panelists will be redirected to "Receiver URL for landing pages" which is setup in the community properties.


Example direct:
https://www.customcommunity.com/landing.php?kslp=AkjdJDEcnj3ddf

The kslp parameter specifies the appropriate landing page which can be obtained using integration.getLandingPage() call.

Example URL: http://www.example.com/panelinstall/...utConfirmation

JSON Input Fields:

Parameter Type Description Required
seskey string The sessionKey of the panelist to send the confirmation to. yes
mobile boolean If true send an SMS, if false send an Email (default: false). no

Example POST:


{
    seskey: 'ce512c91',
    mobile: false
}


JSON Output Fields on Success:

Parameter Type Description
success boolean true The email was successful.

Example success:


{
    success: true
}


JSON Output Fields on Failure:

Parameter Type Description
success boolean false The email was unsuccessful.
error string The error message.
errno number The error number.

Example failure:


{
    success: false,
    error:   'Failed to send optout email.',
    errno:   0
}

 

2.2:  portal.email.sendReferFriend

Send a refer a friend email to the supplied email address. The system will automatically use the pre-defined email template from the community the panelist belongs to. If a custom API powered community is used then panelists will be redirected to "Receiver URL for landing pages" which is setup in the community properties.


Example direct:
https://www.customcommunity.com/landing.php?kslp=AkjdJDEcnj3ddf

The kslp parameter specifies the appropriate landing page which can be obtained using integration.getLandingPage() call.


Example URL: http://www.example.com/panelinstall/...endReferFriend

JSON Input Fields:

Parameter Type Description Required
seskey string The sessionKey of the referrer. yes
email string The email address to refer. yes
points number The points rewarded to the referrer. yes
mobile boolean If true send an SMS, if false send an Email (default: false). no

Example POST:


{
    seskey: 'ce512c91',
    email:  'person@example.com',
    points: 100,
    mobile: false
}


JSON Output Fields on Success:

Parameter Type Description
success boolean true The email was successful.

Example success:


{
    success: true
}


JSON Output Fields on Failure:

Parameter Type Description
success boolean false The email was unsuccessful.
error string The error message.
errno number The error number.

Example failure:


{
    success: false,
    error:   'Failed to send optout email.',
    errno:   0
}

 

2.3:  portal.email.sendResetPassword

Send a reset password email to the e-mail address provided. The system will automatically use the pre-defined email template from the community the panelist belongs to. If a custom API powered community is used then panelists will be redirected to "Receiver URL for landing pages" which is setup in the community properties.


Example direct:
https://www.customcommunity.com/landing.php?kslp=AkjdJDEcnj3ddf

The kslp parameter specifies the appropriate landing page which can be obtained using integration.getLandingPage() call.


Example URL: http://www.example.com/panelinstall/...dResetPassword

JSON Input Fields:

Parameter Type Description Required
panelid number The panelid that the email address is registered to. yes
email string The email address to send the email to. yes
mobile boolean If true send an SMS, if false send an Email. (default: false) no

Example POST:


{
    panelid: 1,
    email:   'demo@example.com',
    mobile:  false
}


JSON Output Fields on Success:

Parameter Type Description
success boolean true The email was successful.

Example success:


{
    success: true
}


JSON Output Fields on Failure:

Parameter Type Description
success boolean false The email was unsuccessful.
error string The error message.
errno number The error number.

Example failure:


{
    success: false,
    error:   'Failed to send optout email.',
    errno:   0
}

 

2.4:  portal.email.sendOptInConfirmation

Sends an opt-in email to the e-mail address provided. The system will automatically use the pre-defined email template from the community the panelist belongs to. If a custom API powered community is used then panelists will be redirected to "Receiver URL for landing pages" which is setup in the community properties.


Example direct:
https://www.customcommunity.com/landing.php?kslp=AkjdJDEcnj3ddf

The kslp parameter specifies the appropriate landing page which can be obtained using integration.getLandingPage() call.


Example URL: http://www.example.com/panelinstall/...InConfirmation

JSON Input Fields:

Parameter Type Description Required
panelid number The panelid that the email address is registered to. yes
email string The email address to send the email to. yes
mobile boolean If true send an SMS, if false send an Email. (default: false) no

Example POST:


{
    panelid: 1,
    email:   'demo@example.com',
    mobile:  false
}


JSON Output Fields on Success:

Parameter Type Description
success boolean true The email was successful.

Example success:


{
    success: true
}


JSON Output Fields on Failure:

Parameter Type Description
success boolean false The email was unsuccessful.
error string The error message.
errno number The error number.

Example failure:


{
    success: false,
    error:   'Failed to send optout email.',
    errno:   0
}

 

3:  Panel

3.1:  portal.panel.validateSource

Validate that the given sourceid is valid for the given panelid.

Example URL: http://www.example.com/panelinstall/...validateSource

JSON Input Fields:

Parameter Type Description Required
panelid number The panelid in which the sourceid should be found. yes
sourceid number The sourceid to be validated. yes

Example POST:


{
    panelid:  1,
    sourceid: 10
}


JSON Output Fields on Success:

Parameter Type Description
success boolean true The validation was successful.

Example success:


{
    success: true
}


JSON Output Fields on Failure:

Parameter Type Description
success boolean false The validation was unsuccessful.
error string The error message.
errno number The error number.

Example failure:


{
    success: false,
    error:   'Panel ID "1" is invalid',
    errno:   20101
}

 

3.2:  portal.panel.validateEmail

Validate that the given email is valid for the given panelid.

Example URL: http://www.example.com/panelinstall/....validateEmail

JSON Input Fields:

Parameter Type Description Required
panelid number The panelid in which the email address should be registered. yes
email string The email address to be validated. yes

Example POST:


{
    panelid: 1,
    email:   'demo@example.com'
}


JSON Output Fields on Success:

Parameter Type Description
success boolean true The validation was successful.

Example success:


{
    success: true
}


JSON Output Fields on Failure:

Parameter Type Description
success boolean false The validation was unsuccessful.
error string The error message.
errno number The error number.

Example failure:


{
    success: false,
    error:   'Panel ID "1" is invalid',
    errno:   20101
}

 

4:  Panelist

4.1:  portal.panelist.create

Create a new panelist.

Example URL: http://www.example.com/panelinstall/...anelist.create

JSON Input Fields:

Parameter Type Description Required
panelid number The panelid in which the new panelist should be assigned. yes
datapoints Datapoint array Array of data points and values to assign to the new panelist. See below for more details explanation of the array. yes
referral string A referral hash, as returned by portal.panelist.referralHash, or NULL if this isn't a referral. no
points string Initial number of points awarded for joining no

Datapoint array: The data point array is an array of stdClasses. Each stdClass element of the answer array should contain the following:

Parameter Type Description
label string The datapoint label, may also be one of the reserved labels (email, password, identifier, sourceid, etc.). Email is the only required field.
Please note, that data point labels are case sensitive!
answer mixed The panelist's data point value. Checkboxes should be passed-in as a comma-separated list.

Example POST:


{
    panelid:    1,
    datapoints: [
                    {
                        label:  'email',
                        answer: 'demo@example.com'
                    },
                    {
                        label:  'password',
                        answer: 'demopassword'
                    },
                    {
                        label:  'QGENDER',
                        answer: 'Female'
                    }
                ],
    referral:  '4a2642645e73235ee9daafb0b2df287b'
}


JSON Output Fields on Success:

Parameter Type Description
Success boolean true The panelist creation was successful.
panelistid number The panelistid of the newly created panelist.
verification string The confirmation hash.

Example success:


{
    success:      true,
    panelistid:   2,
    verification: 'c50dea019651460501d2b9dcc0a8aafa'
}


JSON Output Fields on Failure:

Parameter Type Description
success boolean false The panelist creation was unsuccessful.
error string The error message.
errno number The error number.

Example failure:


{
    success: false,
    error:   'The supplied referral hash is invalid',
    errno:   20103
}

 

4.2:  portal.panelist.update

Update the current panelist's information.

Example URL: http://www.example.com/panelinstall/...anelist.update

JSON Input Fields:

Parameter Type Description Required
seskey string The session key of the panelist to be updated. yes
datapoints Datapoint array Array of data points and values to assign to the panelist. See below for more details explanation of the array. yes

Datapoint array: The data point array is an array of stdClasses. Each stdClass element of the answer array should contain the following:

Parameter Type Description
label string The datapoint label, may also be one of the reserved labels (email, password, identifier, sourceid, etc.). Email is the only required field.
answer mixed The panelist's data point value. Checkboxes should be passed-in as a comma-separated list.

Example POST:


{
    seskey:     'ce512c91',
    datapoints: [
                    {
                        label:  'QGENDER',
                        answer: 'Female'
                    },
                    {
                        label:  'QCHECKBOX',
                        answer: '2,4,5,8'
                    }
                ]
}


JSON Output Fields on Success:

Parameter Type Description
success boolean true The update was successful.

Example success:


{
    success: true
}


JSON Output Fields on Failure:

Parameter Type Description
success boolean false The update was unsuccessful.
error string The error message.
errno number The error number.

Example failure:


{
    success: false,
    error:   'Checkbox answer (8) is invalid.',
    errno:   20000
}

 

4.3:  portal.panelist.optOut

This method unsubscribes a panelist. The panelist is not deleted, only marked as unsubscribed.

Example URL: http://www.example.com/panelinstall/...anelist.optOut

JSON Input Fields:

Parameter Type Description Required
seskey string The sessionKey of the panelist to be unsubscribed. yes

Example POST:


{
    seskey: 'ce512c91'
}


JSON Output Fields on Success:

Parameter Type Description
success boolean true The opt out was successful.

Example success:


{
    success: true
}


JSON Output Fields on Failure:

Parameter Type Description
success boolean false The opt out was unsuccessful.
error string The error message.
errno number The error number.

Example failure:


{
    success: false,
    error:   'Session string is invalid',
    errno:   20101
}

 

4.4:  portal.panelist.read

This method returns a panelist information for a specific datapoint.

Example URL: http://www.example.com/panelinstall/....panelist.read

JSON Input Fields:

Parameter Type Description Required
seskey string The sessionKey of panelist to read data. yes
datapoints array An array of datapoint Labels yes

Example POST:


{
    seskey:     'ce512c91',
    datapoints: ['QGENDER','IDENTIFIER','QCHECKBOX']
}


JSON Output Fields on Success:

Parameter Type Description
success boolean true Retrieving panelist information was successful.
values datapoint array Array of datapoint values requested. See below for more detail explanation of the datapoint array.

Datapoint array:

The data point array is an array of stdClasses. Each stdClass element of the answer array will contain the following:

Parameter Type Description
label string The datapoint label, may also be one of the reserved labels (email, password, identifier, sourceid, etc.).
answer mixed The panelist's data point value. Checkboxes are a comma-separated list.

Example success:


{
    success: true,
    values:  [
                 {
                     label:  'QGENDER',
                     answer: 'Female'
                 },
                 {
                     label:  'IDENTIFIER',
                     answer: 'Demo1'
                 },
                 {
                     label:  'QCHECKBOX',
                     answer: '2,4,5'
                 }
             ]
}


JSON Output Fields on Failure:

Parameter Type Description
success boolean false Retrieving panelist information was unsuccessful.
error string The error message.
errno number The error number.

Example failure:


{
    success: false,
    error:   'Session string is invalid',
    errno:   20101
}

 

4.5:  portal.panelist.totalPoints (deprecated)

Use portal.points.total() instead. This method returns the total number of redemption points available for the panelist.

Example URL: http://www.example.com/panelinstall/...st.totalPoints

JSON Input Fields:

Parameter Type Description Required
seskey string The sessionKey of the current panelist. yes

Example POST:


{
    seskey: 'ce512c91'
}


JSON Output Fields on Success:

Parameter Type Description
success boolean true Retrieving redemption points was successful.
points integer Redemption points available for the current panelist.

Example success:


{
    success: true,
    points:  150
}


JSON Output Fields on Failure:

Parameter Type Description
success boolean false Retrieving redemption points was unsuccessful.
error string The error message.
errno number The error number.

Example failure:


{
    success: false,
    error:   'Session string is invalid',
    errno:   20101
}

 

4.6:  portal.panelist.confirm

Confirms that a panelist wished to join the panel, and that the email address used to sign-up is valid.

Example URL: http://www.example.com/panelinstall/...nelist.confirm

JSON Input Fields:

Parameter Type Description Required
panelid number The panelid of the panel the panelist wishes to join. yes
panelistid number The id of the panelist that wishes to join. yes
verification string The verification hash returned by the portal.panelist.create function. yes

Example POST:


{
    panelid:      1,
    panelistid    15,
    verification: 'c50dea019651460501d2b9dcc0a8aafa'
}


JSON Output Fields on Success: (On First Attempt Only)

Parameter Type Description Since
success boolean true Confirming the panelist was successful.  
panelistid number The panelistid of the confirmed panelist.  
seskey string The sessionKey of the confirmed panelist.  
fullname string The full name of the confirmed panelist.  
email string The email address of the confirmed panelist.  
firstname string The first name of the panelist who has logged in. 4.3
lastname string The last name of the panelist who has logged in. 4.3

Example success:


{
    success:    true,
    panelistid: 15,
    seskey:     'ce512c91',
    fullname:   'Demo Panelist'
    email:      'demo@example.com'
    firstname:  'Demo'
    lastname:   'Panelist'
}


JSON Output Fields on Failure:

Parameter Type Description
success boolean false Confirming the panelist was unsuccessful.
error string The error message.
errno number The error number.

Example failure:


{
    success: false,
    error:   'The supplied panelist ID could not be found',
    errno:   20302
}

 

4.7:  portal.panelist.activity (deprecated)

Returns past participation data for a panelist.

Example URL: http://www.example.com/panelinstall/...elist.activity

JSON Input Fields:

Parameter Type Description Required
seskey string The sessionKey required to access the activity data. yes
limit number Maximum number of surveys to return. no

Example POST:


{
    seskey: 'ce512c91',
    limit:  10
}


JSON Output Fields on Success:

Parameter Type Description
success boolean true Retrieving panelist activity was successful.
records array Array of activity data. See below for an more details on the records array.

Records array:

Parameter Type Description
project string Name of the project, as defined in Kinesis Panel.
description string (deprecated) Always returns an empty string.
status string Status being 'completed', 'profile' or 'quota'.
time string The ISO 8601 time the survey was finished.
points string The number of points awarded for a completed survey.
projectid string The project ID.

Example success:


{
    success: true,
    records: [
                 {
                     project:     'Demo Project One',
                     description: '',
                     status:      'completed',
                     time:        '2011-11-18 16:10',
                     projectid:   5
                 },
                 {
                     project:     'Demo Project Two',
                     description: '',
                     status:      'profile',
                     time:        '2011-02-15 06:15',
                     projectid:   10
                 }
             ]
}


JSON Output Fields on Failure:

Parameter Type Description
success boolean false Retrieving panelist activity was unsuccessful.
error string The error message.
errno number The error number.

Example failure:


{
    success: false,
    error:   'Session string is invalid',
    errno:   20101
}

 

4.8:  portal.panelist.referralHash

Returns the referral hash.

Example URL: http://www.example.com/panelinstall/...t.referralHash

JSON Input Fields:

Parameter Type Description Required
seskey string The sessionKey of the panelist to get a referral hash for. yes
email string The email address of the referrer. yes
points number The number of points awarded. yes

Example POST:


{
    seskey: 'ce512c91',
    email:  'person@example.com',
    points: 25
}


JSON Output Fields on Success:

Parameter Type Description
success boolean true Retrieving the referral hash was unsuccessful.
referralHash string A hash used in Panelist.create in order for a referrer to get their points.

Example success:


{
    success:      true,
    referralHash: '4a2642645e73235ee9daafb0b2df287b',
}


JSON Output Fields on Failure:

Parameter Type Description
success boolean false Retrieving the referral hash was unsuccessful.
error string The error message.
errno number The error number.

Example failure:


{
    success: false,
    error:   'The person you were trying to refer is already a member or has already been referred by you',
    errno:   20102
}

 

4.9:  portal.panelist.contactFrequenciesGet

Gets the currently set panelist contact frequencies.

Notice:
Panelists don't have a contact frequencies record by default.
 

Example URL: http://www.example.com/panelinstall/...FrequenciesGet

JSON Input Fields:

Parameter Type Description Required Since
seskey string The sessionKey of the panelist to get contact frequencies for. yes 4.5

Example POST:


{
    seskey: 'ce512c91',
}


JSON Output Fields on Success:

Parameter Type Description Since
success boolean true Retrieving the contact frequencies was successful. 4.5
maxMessages int The number of messages the panelist wants to receive in the specified time frame. 4.5
nextMessage string Date string of the projected time, when panelist is ready to receive the next email invitation (YYYY-MM-DD HH:MM:SS). 4.5.2
timeFrame string The time frame (week or day). 4.5
SMSFrom string The time when it is acceptable to start sending SMS to the panelist. 4.5
SMSTo string The time after which the panelist does not wish to receive SMS. 4.5

Example success:


{
    success:      true,
    maxMessages:  5,
    nextMessage:  '2014-12-08 11:34:00',
    timeFrame:    'week',
    SMSFrom:      '09:00:00',
    SMSTo:        '21:00:00'
}

Example success - no record:


{
    success:      true,
}

 

4.10:  portal.panelist.contactFrequenciesSet

Set the contact frequencies for the current panelist

Notice:
The SMSFrom and SMSTo settings are only of importance, if you're sending SMS invitations from your panel.
 

Example URL: http://www.example.com/panelinstall/...FrequenciesSet

JSON Input Fields:

Parameter Type Description Required Since
seskey string The sessionKey of the panelist to get contact frequencies for. yes 4.5
maxMessages int or NULL Set the number of messages a panelist wants to receive per time frame. A value of NULL means unlimited. yes 4.5
timeFrame string The time frame (week or day) in which we apply the maxMessages limit. yes 4.5
SMSFrom string The time when it is acceptable to start sending SMS to the panelist. The time format is expected in 24 hour HH:MM:SS. If omitted, it will default to 09:00:00. no 4.5
SMSTo string The time after which the panelist does not wish to receive SMS. The time format is expected in 24 hour HH:MM:SS. If omitted, it will default to 21:00:00. no 4.5

Example POSTs:
Set limit of 5 invitations by email/sms per week.


{
    seskey:      'ce512c91',
    maxMessages: 5,
    timeFrame:   'week'
}

Set limit of 1 invitations by email/sms per day. No SMS between 8pm and 5pm.


{
    seskey:      'ce512c91',
    maxMessages: 1,
    timeFrame:   'day',
    SMSFrom:     '17:00:00',
    SMSTo:       '20:00:00'
}

Set unlimited number of invitations by email/sms per day.


{
    seskey:      'ce512c91',
    maxMessages: null,
    timeFrame:   'day'
}


JSON Output Fields on Success:

Parameter Type Description Since
success boolean true Setting the contact frequencies was successful. 4.5

Example success:


{
    success:      true,
}


JSON Output Fields on Failure:

Parameter Type Description Since
success boolean false Setting the contact frequencies has failed 4.5
error string The error message. 4.5
errno number The error number. 4.5

Example failure:


{
    success: false,
    error:   'Invalid time stamp received',
    errno:   0
}

 

5:  Points

5.1:  portal.points.total

Get the panelist's currently available reward points. This total excludes any reward points already used or any pending point redemption.

Example URL: http://www.example.com/panelinstall/...l.points.total

JSON Input Fields:

Parameter Type Description Required
seskey string The sessionKey of the panelist to get the points total for. yes

Example POST:


{
    seskey: 'ce512c91'
}


JSON Output Fields on Success:

Parameter Type Description
success boolean true Retrieving the total points was successful.
points integer Retrieving the panelist's current total reward points.

Example success:


{
    success: true,
    points:  1845
}


JSON Output Fields on Failure:

Parameter Type Description
success boolean false Retrieving the total points was unsuccessful.
error string The error message.
errno number The error number.

Example failure:


{
    success: false,
    error:   'Session string is invalid',
    errno:   20101
}

 

5.2:  portal.points.earned

Get the amount of points the panelist has earned so far. This includes points from referrals, registration points and surveys.

Example URL: http://www.example.com/panelinstall/....points.earned

JSON Input Fields:

Parameter Type Description Required
seskey string The sessionKey of the panelist to get the points earned. yes

Example POST:


{
    seskey: 'ce512c91'
}


JSON Output Fields on Success:

Parameter Type Description
success boolean true Retrieving the total points was successful.
points integer Retrieving the amount of points the panelist has earned so far.

Example success:


{
    success: true,
    points:  1845
}


JSON Output Fields on Failure:

Parameter Type Description
success boolean false Retrieving the points earned was unsuccessful.
error string The error message.
errno number The error number.

Example failure:


{
    success: false,
    error:   'Session string is invalid',
    errno:   20101
}

 

5.3:  portal.points.redeemed

Get the amount of points the panelist has redeemed. This includes all approved redemptions.

Example URL: http://www.example.com/panelinstall/...oints.redeemed

JSON Input Fields:

Parameter Type Description Required
seskey string The sessionKey of the panelist to get points redeemed. yes

Example POST:


{
    seskey: 'ce512c91'
}


JSON Output Fields on Success:

Parameter Type Description
success boolean true Retrieving the total points was successful.
points integer Retrieving the amount of points the panelist has redeemed.

Example success:


{
    success: true,
    points:  1845
}


JSON Output Fields on Failure:

Parameter Type Description
success boolean false Retrieving the points redeemed was unsuccessful.
error string The error message.
errno number The error number.

Example failure:


{
    success: false,
    error:   'Session string is invalid',
    errno:   20101
}

 

5.4:  portal.points.surveys

Get the amount of points the panelist has received for completing surveys.

Example URL: http://www.example.com/panelinstall/...points.surveys

JSON Input Fields:

Parameter Type Description Required
seskey string The sessionKey of the panelist to get points from surveys data. yes

Example POST:


{
    seskey: 'ce512c91'
}


JSON Output Fields on Success:

Parameter Type Description
success boolean true Retrieving the total points was successful.
points integer Retrieving the amount of points the panelist has received for completing surveys.

Example success:


{
    success: true,
    points:  1845
}


JSON Output Fields on Failure:

Parameter Type Description
success boolean false Retrieving the amount of points was unsuccessful.
error string The error message.
errno number The error number.

Example failure:


{
    success: false,
    error:   'Session string is invalid',
    errno:   20101
}

 

5.5:  portal.points.referred

Get the amount of points the panelist has received for referring other panelists.

Example URL: http://www.example.com/panelinstall/...oints.referred

JSON Input Fields:

Parameter Type Description Required
seskey string A valid login hash. yes

Example POST:


{
    seskey: 'ce512c91'
}


JSON Output Fields on Success:

Parameter Type Description
success boolean true Retrieving the total points was successful.
points integer Retrieving the amount of points the panelist has earned for referring other panelists.

Example success:


{
    success: true,
    points:  1845
}


JSON Output Fields on Failure:

Parameter Type Description
success boolean false Retrieving the amount of referral points was unsuccessful.
error string The error message.
errno number The error number.

Example failure:


{
    success: false,
    error:   'Session string is invalid',
    errno:   20101
}

 

5.6:  portal.points.other

Get the amount of points that were given to the panelist by an administrator

Example URL: http://www.example.com/panelinstall/...l.points.other

JSON Input Fields:

Parameter Type Description Required
seskey string A valid login hash. yes

Example POST:


{
    seskey: 'ce512c91'
}


JSON Output Fields on Success:

Parameter Type Description
success boolean true Retrieving the total points was successful.
points integer Retrieving the amount of points that were given to the panelist by an administrator.

Example success:


{
    success: true,
    points:  1845
}


JSON Output Fields on Failure:

Parameter Type Description
success boolean false Retrieving the points given by admins was unsuccessful.
error string The error message.
errno number The error number.

Example failure:


{
    success: false,
    error:   'Session string is invalid',
    errno:   20101
}

 

6:  Quick Poll

6.1:  portal.quickpoll.available

This method returns available quick polls for the user session. It is possible to return just a single random poll and fetch all available polls in the order created or optionally in random order. It is also possible to return quick polls using programmed pagination that utilizes limit and offset parameters. The count value always equals to the total number of items available regardless if the limit and the offset parameters are used.

Example URL: http://www.example.com/panelinstall/...poll.available

JSON Input Fields:

Parameter Type Description Required Since
sesskey string A valid login hash. yes 4.3
randomize boolean Randomize the returned quick polls (default: false) no 4.3
limit number Max number of items to return, default is all. no 4.3
offset number Offset the output for pagination (default: no offset) no 4.3

Example POST:


{
    seskey:    'ce512c91',
    limit:     10,
    offset:    20,
    randomize: false
}


JSON Output Fields on Success:

Parameter Type Description Since
success boolean true The call was successful. 4.3
count number The total count of items available (regardless of limit and offset) 4.3
limit number The limit supplied in the call 4.3
offset number The offset supplied in the call 4.3
quickpolls array An array of quickpolls (see below) 4.3

Quickpolls Array: Each object in the array will be a different record for the user with the following attributes

Parameter Type Description Since
quickpollid number The quick poll ID 4.3
startdate string Start date of the quick poll 4.3
enddate string End date of the quick poll 4.3
questiontype string The question type of the quick poll (radio/checkbox) 4.3
qtext string The (localized) question text 4.3
options array An array of options (see below) 4.3

Options Array: Each object in the array will be a different choice

Parameter Type Description Since
optionid number The option ID of the choice 4.3
optiontext string The (localized) choice text 4.3

Example success:


{
    success:    true,
    count:      '1',
    limit:      null,
    offset:     null,
    quickpolls: [
                    {
                        quickpollid:  '4',
                        startdate:    '2013-07-28 12:00:00',
                        enddate:      '2013-08-21 12:00:00',
                        questiontype: 'radio',
                        qtext:        'Another random quickpoll',
                        options: [
                                     {
                                         optionid:   '9',
                                         optiontext: 'Choice 1'
                                     },
                                     {
                                         optionid:   '10',
                                         optiontext: 'Choice 2'
                                     },
                                     {
                                         optionid:   '11',
                                         optiontext: 'Choice 3'
                                     },
                                     {
                                         optionid:   '12',
                                         optiontext: 'Choice 4'
                                     },
                                 ]
                    }
                ]
}

 

6.2:  portal.quickpoll.availableCount

This method returns available quick poll count for the panelist.

Example URL: http://www.example.com/panelinstall/...availableCount

JSON Input Fields:

Parameter Type Description Required Since
sesskey string A valid login hash. yes 4.3

Example POST:


{
    seskey: 'ce512c91'
}


JSON Output Fields on Success:

Parameter Type Description Since
success boolean true The call was successful. 4.3
count number The number of items available 4.3

Example success:


{
    success:    true,
    count:      '1',
}

 

6.3:  portal.quickpoll.completed

This method returns completed quick polls for the user session. It is also possible to return quick polls using programmed pagination that utilizes limit and offset parameters. The count value always equals to the total number of items available regardless if the limit and the offset parameters are used.

Example URL: http://www.example.com/panelinstall/...poll.completed

JSON Input Fields:

Parameter Type Description Required Since
sesskey string A valid login hash. yes 4.3
limit number Max number of items to return, default is all. no 4.3
offset number Offset the output for pagination (default: no offset) no 4.3

Example POST:


{
    seskey: 'ce512c91',
    limit:  10,
    offset: 20
}


JSON Output Fields on Success:

Parameter Type Description Since
success boolean true The call was successful. 4.3
count number The total count of items (regardless of limit and offset) 4.3
limit number The limit supplied in the call 4.3
offset number The offset supplied in the call 4.3
quickpolls array An array of quickpolls (see below) 4.3

Quickpolls Array: Each object in the array will be a different record for the user with the following attributes

Parameter Type Description Since
quickpollid number The quick poll ID 4.3
startdate string Start date of the quick poll 4.3
enddate string End date of the quick poll 4.3
questiontype string The question type of the quick poll (radio/checkbox) 4.3
qtext string The (localized) question text 4.3
options array An array of options (see below) 4.3

Options Array: Each object in the array will be a different choice

Parameter Type Description Since
optionid number The option ID of the choice 4.3
optiontext string The (localized) choice text 4.3

Example success:


{
    success:    true,
    count:      '1',
    limit:      null,
    offset:     null,
    quickpolls: [
                    {
                        quickpollid:  '5',
                        startdate:    '2013-07-28 12:00:00',
                        enddate:      '2013-08-21 12:00:00',
                        questiontype: 'radio',
                        qtext:        'Another random quickpoll',
                        options: [
                                     {
                                         optionid:   '13',
                                         optiontext: 'Choice 1'
                                     },
                                     {
                                         optionid:   '14',
                                         optiontext: 'Choice 2'
                                     },
                                     {
                                         optionid:   '15',
                                         optiontext: 'Choice 3'
                                     },
                                     {
                                         optionid:   '16',
                                         optiontext: 'Choice 4'
                                     },
                                 ]
                    }
                ]
}

 

6.4:  portal.quickpoll.completedCount

This method returns completed quick poll count for the panelist.

Example URL: http://www.example.com/panelinstall/...completedCount

JSON Input Fields:

Parameter Type Description Required Since
sesskey string A valid login hash. yes 4.3

Example POST:


{
    seskey: 'ce512c91'
}


JSON Output Fields on Success:

Parameter Type Description Since
success boolean true The call was successful. 4.3
count number The number of items available 4.3

Example success:


{
    success:    true,
    count:      '1',
}

 

6.5:  portal.quickpoll.saveResponse

This method is used to save the response received from the panelist.

Example URL: http://www.example.com/panelinstall/...l.saveResponse

JSON Input Fields:

Parameter Type Description Required Since
sesskey string A valid login hash. yes 4.3
quickpollid number A valid quick poll ID yes 4.3
response array Panelists response; Array of optionids (must be one for radio questions) yes 4.3

Example POST:


{
    seskey:      'ce512c91',
    quickpollid: 42,
    response:    [
                     259,
                     260
                 ]
}


JSON Output Fields on Success:

Parameter Type Description Since
success boolean true The call was successful. 4.3

Example success:


{
    success: true
}

 

6.6:  portal.quickpoll.stats

This method returns the result for a single quick polls using ID. The result set is calculated among all the panelist who participated. If a quick poll ID is supplied then results for this poll are returned. If omitted, results of a random past quick poll that the panelist has participated in are returned. If quick poll ID is omitted and the panelist has no history of participating in any quick polls, an error is returned.

Example URL: http://www.example.com/panelinstall/...uickpoll.stats

JSON Input Fields:

Parameter Type Description Required Since
sesskey string A valid login hash. yes 4.3
quickpollid number A valid quick poll ID (default: none, results in selection of random quick poll) no 4.3

Example POST:


{
    seskey     : 'ce512c91',
    quickpollid:  42
}


JSON Output Fields on Success:

Parameter Type Description Since
success boolean true The call was successful. 4.3
quickpollid number The ID of the quick poll that was selected (randomly or not) 4.3
startdate string Start date of the quick poll 4.3
enddate string End date of the quick poll 4.3
questiontype string The question type of the quick poll (radio/checkbox) 4.3
qtext string The (localized) question text 4.3
answercount string Total number of panelists who have answered the quick poll 4.3
options array An array of options (see below) 4.3

Options Array: Each object in the array will be a different choice

Parameter Type Description Since
optionid number The option ID of the choice 4.3
optiontext string The (localized) choice text 4.3
frequency number Total number of times that this answer was selected 4.3
percentage number Percentage of how often this answer was selected 4.3

Example success:


{
    success:    true,
    quickpollid:  '5',
    startdate:    '2013-07-28 12:00:00',
    enddate:      '2013-08-21 12:00:00',
    questiontype: 'radio',
    qtext:        'Another random quickpoll',
    options: [
                 {
                     optionid:   '22',
                     optiontext: 'Choice 1'
                     frequency:  '25'
                     percentage: '43'
                 },
                 {
                     optionid:   '23',
                     optiontext: 'Choice 2'
                     frequency:  '33'
                     percentage: '57'
                 },
             ]
}

 

7:  Redemption

7.1:  portal.redemption.create

Create a Redemption request.

Example URL: http://www.example.com/panelinstall/...emption.create

JSON Input Fields:

Parameter Type Description Required
seskey string A valid login hash. yes
type string The redemption typeid or type. yes

Example POST:


{
    seskey: 'ce512c91',
    type:   2
}


JSON Output Fields on Success:

Parameter Type Description Since
success boolean true The creation was successful.  
transactionId int The transaction ID resulting from this request. 4.5.1

Example success:


{
    success: true,
    transactionId: 42
}


JSON Output Fields on Failure:

Parameter Type Description
success boolean false The creation was unsuccessful.
error string The error message.
errno number The error number.

Example failure:


{
    success: false,
    error:   'The redemption type you are trying to use has been disabled.',
    errno:   20102
}

 

7.2:  portal.redemption.read

This method returns redemption requests made by the active panelist.

Example URL: http://www.example.com/panelinstall/...edemption.read

JSON Input Fields:

Parameter Type Description Required Since
seskey string A valid login hash. yes  
limit number Limit the output (i.e. 20, 100 OR 100). no  
offset number Offset the output for pagination (default: no offset) no 4.3

Example POST:


{
    seskey: 'ce512c91',
    limit:  100
}


JSON Output Fields on Success:

Parameter Type Description Since
success boolean true Retrieving the redemption request was successful.  
limit number The limit supplied in the call 4.3
offset number The offset supplied in the call 4.3
count number The total count of items available (regardless of limit and offset) 4.3
requests array Array of redemption requests made by the active panelist. See below for more details of the requests array.  

Requests array:

Parameter Type Description
name string Vendor name as selected in the when redemption option was created in the UI (Kinesis, iCardMall or Coupon)
points number The number of points redeemed.
status string Current status: pending, approved, or denied.
modified string Date and time of last status change in yyyy-mm-dd hh:mm:ss format.
created string Date and time panelist requested the redemption in yyyy-mm-dd hh:mm:ss format.

Example success:


{
    success:  true,
    requests: [
                  {
                      type:     'gift',
                      points:   100,
                      status:   'pending',
                      modified: '2011-11-01 08:32:12',
                      created:  '2011-11-01 08:32:12'
                  },
                  {
                      type:     'paypal',
                      points:   200,
                      status:   'approved',
                      modified: '2011-10-31 20:12:43',
                      created:  '2011-10-28 16:24:49'
                  }
              ]
}


JSON Output Fields on Failure:

Parameter Type Description
success boolean false Retrieving the redemption request was unsuccessful.
error string The error message.
errno number The error number.

Example failure:


{
    success: false,
    error:   'Session string is invalid',
    errno:   20101
}

 

8:  Reward

8.1:  portal.reward.types

Returns the reward types available.

Example URL: http://www.example.com/panelinstall/...l.reward.types

JSON Input Fields:

Parameter Type Description Required
seskey string A valid login hash. yes

Example POST:


{
    seskey: 'ce512c91'
}


JSON Output Fields on Success:

Parameter Type Description
success boolean true Retrieving the reward types was successful.
types array Array of reward types available. See below for more details on the reward types array.

Reward types array:

Parameter Type Description
type string Redemption reward type.
name array Type display name.
available boolean Whether or not this redemption type is available to the current panelist.

Example success:


{
    success: true,
    types:   [
                 {
                     type:      'gift',
                     name:      'My reward',
                     available: true
                 },
                 {
                     type:      'prize',
                     name:      'A new car',
                     available: false
                 }
             ]
}


JSON Output Fields on Failure:

Parameter Type Description
success boolean false Retrieving the reward types was unsuccessful.
error string The error message.
errno number The error number.

Example failure:


{
    success: false,
    error:   'Session string is invalid',
    errno:   20101
}

 

8.2:  portal.reward.history

Returns the reward history of the panelist.

Example URL: http://www.example.com/panelinstall/...reward.history

JSON Input Fields:

Parameter Type Description Required Since
seskey string A valid login hash. yes  
limit number Max number of surveys to return, default is all. no  
offset number Offset the output for pagination (default: no offset) no 4.3

Example POST:


{
    seskey: 'ce512c91',
    limit:  10
}


JSON Output Fields on Success:

Parameter Type Description Since
success boolean true Retrieving the reward history was successful.  
limit number The limit supplied in the call 4.3
offset number The offset supplied in the call 4.3
count number The total count of items available (regardless of limit and offset) 4.3
records array An array of rewards the panelist has received.  

Records array: Each object in the array will be a different record for the user with the following attributes

Parameter Type Description
points string The number of points awarded for a completed survey.
time string The ISO 8601 time the survey was finished.
project string Name of the project, as defined in Kinesis Panel, or NULL.
note string Reason for points.
name string (deprecated) This will contain whichever of the project or note fields is not NULL. You can use it, but it's not recommended.
portalDisplayName string Multilingual survey name from campaign properties
projectid number The project ID.

Example success:


{
    success: true,
    limit:   null,
    offset:  null,
    count:   '2',
    records: [
                 {
                     points:            200,
                     time:              '2011-10-15 18:34:29',
                     project:           'Sample project',
                     note:              'Successful referral',
                     portalDisplayName: 'Sample portal',
                     projectid:         2
                 },
                 {
                     points:            200,
                     time:              '2011-10-02 13:56:28',
                     project:           'Sample project',
                     note:              'Successful referral',
                     portalDisplayName: 'Sample portal',
                     projectid:         2
                 }
             ]
}


JSON Output Fields on Failure:

Parameter Type Description
success boolean false Retrieving the reward history was unsuccessful.
error string The error message.
errno number The error number.

Example failure:


{
    success: false,
    error:   'Session string is invalid',
    errno:   20101
}

 

8.3:  portal.reward.historyCount

Returns the number of reward history items of the panelist.

Example URL: http://www.example.com/panelinstall/...d.historyCount

JSON Input Fields:

Parameter Type Description Required Since
seskey string A valid login hash. yes 4.3

Example POST:


{
    seskey: 'ce512c91'
}


JSON Output Fields on Success:

Parameter Type Description Since
success boolean true Retrieving the reward history was successful.  
limit number The limit supplied in the call 4.3
count number The total count of items available 4.3

Example success:


{
    success: true,
    count:   '2'
}


JSON Output Fields on Failure:

Parameter Type Description
success boolean false Retrieving the reward history count was unsuccessful.
error string The error message.
errno number The error number.

Example failure:


{
    success: false,
    error:   'Session string is invalid',
    errno:   20101
}

 

9:  Survey

9.1:  portal.survey.completed

This method returns a list of completed surveys.

Example URL: http://www.example.com/panelinstall/...rvey.completed

JSON Input Fields:

Parameter Type Description Required Since
seskey string A valid login hash. yes  
limit number Max number of surveys to return, default is all. no  
offset number Offset the output for pagination (default: no offset) no 4.3

Example POST:


{
    seskey: 'ce512c91',
    limit:  10
}


JSON Output Fields on Success:

Parameter Type Description Since
success boolean true The list of completed surveys was successful.  
limit number The limit supplied in the call 4.3
offset number The offset supplied in the call 4.3
count number The total count of items available (regardless of limit and offset) 4.3
surveys array Array of surveys the panelist has completed or been terminated from.  

Surveys array: Each element of the array is an object with the following attributes

Parameter Type Description Since
subject string Multilingual survey name from the campaign  
body string Multilingual survey description from the campaign  
status string Survey status, 'completed', 'profile' or 'quota'.  
time string The ISO 8601 time the survey was finished.  
points number The number of points awarded for a completed survey/  
projectid number The project ID.  
categoryids array Array of category IDs 4.3

Example success:


{
    success: true,
    limit:   null,
    offset:  null,
    count:   2,
    surveys: [
                 {
                     subject:     'Vacation survey',
                     body:        'Take this survey to win a new iPad',
                     status:      'completed',
                     time:        '2013-06-14 11:32',
                     points:      200,
                     projectid:   45
                 },
                 {
                     subject:     'Foo bar survey',
                     body:        'Take this survey to earn 200 reward points',
                     status:      'quota',
                     time:        '2013-06-13 09:32',
                     points:      200,
                     projectid:   34
                 }
             ]
}


JSON Output Fields on Failure:

Parameter Type Description
success boolean false The list of completed surveys was unsuccessful.
error string The error message.
errno number The error number.

Example failure:


{
    success: false,
    error:   'Session string is invalid',
    errno:   20101
}

 

9.2:  portal.survey.completedByCategory

This method returns a list of completed surveys - filtered by category id.

Example URL: http://www.example.com/panelinstall/...etedByCategory

JSON Input Fields:

Parameter Type Description Required Since
seskey string A valid login hash. yes 4.3
limit number Max number of surveys to return, default is all. no 4.3
offset number Offset the output for pagination (default: no offset) no 4.3
categoryid number Category ID yes 4.3

Example POST:


{
    seskey:     'ce512c91',
    limit:      10,
    offset:     20,
    categoryid: 42
}


JSON Output Fields on Success:

Parameter Type Description Since
success boolean true The list of completed surveys was successful. 4.3
limit number The limit supplied in the call 4.3
offset number The offset supplied in the call 4.3
count number The total count of items available (regardless of limit and offset) 4.3
surveys array Array of surveys the panelist has completed or been terminated from. 4.3

Surveys array: Each element of the array is an object with the following attributes

Parameter Type Description Since
subject string Multilingual survey name from the campaign 4.3
body string Multilingual survey description from the campaign 4.3
status string Survey status, 'completed', 'profile' or 'quota'. 4.3
time string The ISO 8601 time the survey was finished. 4.3
points number The number of points awarded for a completed survey/ 4.3
projectid number The project ID. 4.3
categoryids array Array of category IDs 4.3

Example success:


{
    success: true,
    limit:   null,
    offset:  null,
    count:   '2',
    surveys: [
                 {
                     subject:     'Vacation survey',
                     body:        'Take this survey to win a new iPad',
                     status:      'completed',
                     time:        '2013-06-14 11:32',
                     points:      200,
                     projectid:   45
                     categoryids:  []
                 },
                 {
                     subject:     'Foo bar survey',
                     body:        'Take this survey to earn 200 reward points',
                     status:      'quota',
                     time:        '2013-06-13 09:32',
                     points:      200,
                     projectid:   34
                     categoryids:  [
                                        1,
                                        2
                                   ]
                 }
             ]
}


JSON Output Fields on Failure:

Parameter Type Description
success boolean false The call status.
error string The error message.
errno number The error number.

Example failure:


{
    success: false,
    error:   'Session string is invalid',
    errno:   20101
}

 

9.3:  portal.survey.completedCount

This method retrieves the number of surveys completed by the panelist.

Example URL: http://www.example.com/panelinstall/...completedCount

JSON Input Fields:

Parameter Type Description Required Since
seskey string A valid login hash. yes 4.3

Example POST:


{
    seskey: 'ce512c91'
}


JSON Output Fields on Success:

Parameter Type Description Since
success boolean true The call status. 4.3
count number The number of items available 4.3


Example success:


{
    success: true,
    count:   42
}


JSON Output Fields on Failure:

Parameter Type Description
success boolean false The call status.
error string The error message.
errno number The error number.

Example failure:


{
    success: false,
    error:   'Session string is invalid',
    errno:   20101
}

 

9.4:  portal.survey.completedCountByCategoryID

This method retrieves the number of surveys completed by the panelist - filtered by category id.

Example URL: http://www.example.com/panelinstall/...ntByCategoryID

JSON Input Fields:

Parameter Type Description Required Since
seskey string A valid login hash. yes 4.3
categoryid number A valid category id yes 4.3

Example POST:


{
    seskey:     'ce512c91',
    categoryid: 42
}


JSON Output Fields on Success:

Parameter Type Description Since
success boolean true The call status. 4.3
count number The number of items available 4.3


Example success:


{
    success: true,
    count:   42
}


JSON Output Fields on Failure:

Parameter Type Description
success boolean false The call status.
error string The error message.
errno number The error number.

Example failure:


{
    success: false,
    error:   'Session string is invalid',
    errno:   20101
}

 

9.5:  portal.survey.available

This method returns all available surveys for the panelist.

Example URL: http://www.example.com/panelinstall/...rvey.available

JSON Input Fields:

Parameter Type Description Required Since
seskey string A valid login hash. yes  
limit number Max number of surveys to return, default is all. no  
offset number Offset the output for pagination (default: no offset) no 4.3

Example POST:


{
    seskey: 'ce512c91',
    limit:  10,
    offset: 20
}


JSON Output Fields on Success:

Parameter Type Description Since
success boolean true The call status.  
limit number The limit supplied in the call 4.3
offset number The offset supplied in the call 4.3
count number The total count of items available (regardless of limit and offset) 4.3
surveys array An array of surveys to which the panelist has been invited, but has not yet taken. It will not include surveys from closed projects, or from invitations that have expired.  

Surveys array:

Parameter Type Description Since
subject string Multilingual survey name from the campaign  
body string Multilingual survey description from the campaign  
status string 'started' if the panelist has started, but not completed the survey, otherwise NULL.  
time string The time this invitation was sent.  
points number The number of points awarded for a completed survey.  
url string URL to take the panelist to the survey, as defined in the project.  
previewurl string URL to take the panelist to the original invitation. If the campaign did not have an invitation (community launch only) this field will be NULL.  
type string The type of invitation that was used (emailhtml,emailtext,SMS). If the type is not available (community launch only), this field will be NULL.  
endtime string The time when the campaign expires and the survey links will stop working.  
invited string The time when the panelist was invited.  
purpose string The campaign purpose ('invitation', 'automated', 'diary', 'profiler' or 'portal').  
projectid number The project ID  
categoryids array Array of category IDs 4.3

Example success:


{
    success: true,
    limit:   null,
    offset:  null,
    count:   1,
    surveys: [
                 {
                     subject:    "Today's 5 minute Survey",
                     body:       "This survey is about your favorite type of car.",
                     status:     null,
                     time:       "2011-10-15 12:18:19",
                     points:     200,
                     url:        "http://www.example.com/panelinstall/receiver.pro?seskey=ce512c91",
                     previewurl: "http://www.example.com/panelinstall/portalinvite.pro?seskey=ce512c91",
                     type:       "emailhtml",
                     endtime:    "2012-01-15 20:00:00",
                     invited:    "2011-10-15 12:18:19",
                     purpose:    "invitation",
                     projectid:  10,
                     categoryids:  [
                                        1,
                                        2
                                   ]
                 }
             ]
}


JSON Output Fields on Failure:

Parameter Type Description
success boolean false The list of available surveys was unsuccessful.
error string The error message.
errno number The error number.

Example failure:


{
    success: false,
    error:   'Session string is invalid',
    errno:   20101
}

 

9.6:  portal.survey.availableByCategory

This method returns all available surveys for the panelist - filtered by category id.

Example URL: http://www.example.com/panelinstall/...ableByCategory

JSON Input Fields:

Parameter Type Description Required Since
seskey string A valid login hash. yes  
limit number Max number of surveys to return, default is all. no  
offset number Offset the output for pagination (default: no offset) no 4.3
categoryid number A valid category id yes 4.3

Example POST:


{
    seskey:     'ce512c91',
    limit:      10,
    offset:     20,
    categoryid: 42
}


JSON Output Fields on Success:

Parameter Type Description Since
success boolean true The call status.  
limit number The limit supplied in the call 4.3
offset number The offset supplied in the call 4.3
count number The total count of items available (regardless of limit and offset) 4.3
surveys array An array of surveys to which the panelist has been invited, but has not yet taken. It will not include surveys from closed projects, or from invitations that have expired.  

Surveys array:

Parameter Type Description Since
subject string Multilingual survey name from the campaign  
body string Multilingual survey description from the campaign  
status string 'started' if the panelist has started, but not completed the survey, otherwise NULL.  
time string The time this invitation was sent.  
points number The number of points awarded for a completed survey.  
url string URL to take the panelist to the survey, as defined in the project.  
previewurl string URL to take the panelist to the original invitation. If the campaign did not have an invitation (community launch only) this field will be NULL.  
type string The type of invitation that was used (emailhtml,emailtext,SMS). If the type is not available (community launch only), this field will be NULL.  
endtime string The time when the campaign expires and the survey links will stop working.  
invited string The time when the panelist was invited.  
purpose string The campaign purpose ('invitation', 'automated', 'diary', 'profiler' or 'portal').  
projectid number The project ID  
categoryids array Array of category IDs 4.3

Example success:


{
    success: true,
    limit:   null,
    offset:  null,
    count:   1,
    surveys: [
                 {
                     subject:    "Today's 5 minute Survey",
                     body:       "This survey is about your favorite type of car.",
                     status:     null,
                     time:       "2011-10-15 12:18:19",
                     points:     200,
                     url:        "http://www.example.com/panelinstall/receiver.pro?seskey=ce512c91",
                     previewurl: "http://www.example.com/panelinstall/portalinvite.pro?seskey=ce512c91",
                     type:       "emailhtml",
                     endtime:    "2012-01-15 20:00:00",
                     invited:    "2011-10-15 12:18:19",
                     purpose:    "invitation",
                     projectid:  10,
                     categoryids:  [
                                        1,
                                        2
                                   ]
                 }
             ]
}


JSON Output Fields on Failure:

Parameter Type Description
success boolean false The list of available surveys was unsuccessful.
error string The error message.
errno number The error number.

Example failure:


{
    success: false,
    error:   'Session string is invalid',
    errno:   20101
}

 

9.7:  portal.survey.availableCount

This method retrieves the number of surveys available to the panelist.

Example URL: http://www.example.com/panelinstall/...availableCount

JSON Input Fields:

Parameter Type Description Required Since
seskey string A valid login hash. yes 4.3

Example POST:


{
    seskey: 'ce512c91'
}


JSON Output Fields on Success:

Parameter Type Description Since
success boolean true The call status. 4.3
count number The number of items available 4.3


Example success:


{
    success: true,
    count:   42
}


JSON Output Fields on Failure:

Parameter Type Description
success boolean false The call status.
error string The error message.
errno number The error number.

Example failure:


{
    success: false,
    error:   'Session string is invalid',
    errno:   20101
}

 

9.8:  portal.survey.availableCountByCategoryID

This method retrieves the number of surveys available to the panelist - filtered by category id.

Example URL: http://www.example.com/panelinstall/...ntByCategoryID

JSON Input Fields:

Parameter Type Description Required Since
seskey string A valid login hash. yes 4.3
categoryid number A valid category id yes 4.3

Example POST:


{
    seskey:     'ce512c91',
    categoryid: 42
}


JSON Output Fields on Success:

Parameter Type Description Since
success boolean true The call status. 4.3
count number The number of items available 4.3


Example success:


{
    success: true,
    count:   42
}


JSON Output Fields on Failure:

Parameter Type Description
success boolean false The call status.
error string The error message.
errno number The error number.

Example failure:


{
    success: false,
    error:   'Session string is invalid',
    errno:   20101
}

 

9.9:  portal.survey.registerUrl

Returns URL for the primary registration survey URL. This registration URL is only available if Kinesis Survey is used for the initial registration survey.

Example URL: http://www.example.com/panelinstall/...ey.registerUrl

JSON Input Fields:

Parameter Type Description Required
panelid number The Panel ID. yes
portalid number The Community Portal ID. yes
mobile boolean Should a mobile link be returned or not. (default: false) no

Example POST:


{
    panelid:  77,
    portalid: 21,
    mobile:   false
}


JSON Output Fields on Success:

Parameter Type Description
success boolean true Retrieving the registration url was successful.
url string The Survey Link.

Example success:


{
    success: true,
    url:     'http://www.example.com/surveyinstall/html.pro?ID=469&ks_cid=22'
}


JSON Output Fields on Failure:

Parameter Type Description
success boolean false Retrieving the registration url was unsuccessful.
error string The error message.
errno number The error number.

Example failure:


{
    success: false,
    error:   'Panel ID "77" does not exist, or is currently inaccessible.',
    errno:   10000
}

 

9.10:  portal.survey.registerUpdateUrl

Returns URL for the profile update survey URL. This registration URL is only available if Kinesis Survey is used for the profile update survey.

Example URL: http://www.example.com/panelinstall/...isterUpdateUrl

JSON Input Fields:

Parameter Type Description Required
seskey string A valid login hash. yes
mobile boolean Should a mobile link be returned or not. (default: false) no

Example POST:


{
    seskey: 'ce512c91',
    mobile: true
}


JSON Output Fields on Success:

Parameter Type Description
success boolean true Retrieving the registration url was successful.
url string The Survey Link.

Example success:


{
    success: true,
    url:     'http://www.example.com/surveyinstall/?ID=512&ks_identifier=F6EF7EWQ&ks_hash=5aae5a28b5bcf4142f94e40b75f143c5'
}


JSON Output Fields on Failure:

Parameter Type Description
success boolean false Retrieving the registration update url was unsuccessful.
error string The error message.
errno number The error number.

Example failure:


{
    success: false,
    error:   'Session string is invalid',
    errno:   20101
}

 

10:  System

10.1:  portal.system.carriers

Create a panelist session and return panelist information needed for future API requests.

Example URL: http://www.example.com/panelinstall/...ystem.carriers

JSON Input Fields:

Parameter Type Description Required
empty none The data field must still be posted, however it should be blank.  

Example POST:


{
}


JSON Output Fields on Success:

Parameter Type Description
success boolean true Getting a list of carriers was successful.
carriers array An array of carrier IDs and names that are valid for this installation. NULL if no carriers are found. See below for more details on the carriers array.

Carriers array

Parameter Type Description
carrierid number Carriers ID.
name string Carriers name.

Example success:


{
    success:  true,
    carriers: [
                  {
                      carrierid: 1,
                      name:      'AT&T'
                  },
                  {
                      carrierid: 2,
                      name:      'Verizon'
                  },
                  {
                      carrierid: 3,
                      name:      'Sprint'
                  },
                  {
                      carrierid: 4,
                      name:      'T-Mobile'
                  },
                  {
                      carrierid: 5,
                      name:      'Cricket'
                  },
              ]
}


JSON Output Fields on Failure:

Parameter Type Description
success boolean false Getting a list of carriers was unsuccessful.
error string The error message.
errno number The error number.

Example failure:


{
    success: false,
    error:   'Internal error',
    errno:   10000
}

 

  • Was this article helpful?