Skip to main content

FV Kinesis Support

All the topics, resources needed for FV Kinesis.

 
FocusVision Knowledge Base

Panel Community 3.4 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
panelid number The panelid the session will log as the current panel.
community number The communityid the session will log as the current community.
username string The email address associated with the panelist.
password string The password associated with the panelist.

Example POST:

{
    panelid:   1,
    community: 1,
    username:  'demo',
    password:  'demo'
}


JSON Output Fields on Success:

Variable Type Description
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.

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

Logout of the current open API session.

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

JSON Input Fields:

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

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
seskey string The sessionKey of the session to validate.

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

Send an optout confirmation email to the active panelist.

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

JSON Input Fields:

Parameter Type Description
seskey string The sessionKey of the panelist to send the confirmation to.
mobile boolean If true send an SMS, if false send an Email.

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.

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

JSON Input Fields:

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

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.

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

JSON Input Fields:

Parameter Type Description
panelid number The panelid that the email address is registered to.
email string The email address to send the email to.
mobile boolean If true send an SMS, if false send an Email.

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

Send an optin email to the e-mail address provided.

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

JSON Input Fields:

Parameter Type Description
panelid number The panelid that the email address is registered to.
email string The email address to send the email to.
mobile boolean If true send an SMS, if false send an Email.

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
panelid number The panelid in which the sourceid should be found.
sourceid number The sourceid to be validated.

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
panelid number The panelid in which the email address should be registered.
email string The email address to be validated.

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
panelid number The panelid in which the new panelist should be assigned.
datapoints Datapoint array Array of data points and values to assign to the new panelist. See below for more details explanation of the array.
referral string A referral hash, as returned by portal.panelist.referralHash, or NULL if this isn't a referral.

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:

{
    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
seskey string The session key of the panelist to be updated.
datapoints Datapoint array Array of data points and values to assign to the panelist. See below for more details explanation of the array.

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
seskey string The sessionKey of the panelist to be unsubscribed.

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
seskey string The sessionKey of panelist to read data.
datapoints array An array of datapoint Labels

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

This method returns the total number of redemption points available for the current panelist.

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

JSON Input Fields:

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

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
panelid number The panelid of the panel the panelist wishes to join.
panelistid number The id of the panelist that wishes to join.
verification string The verification hash returned by the portal.panelist.create function.

Example POST:

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


JSON Output Fields on Success:

Parameter Type Description
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.

Example success:

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


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

Returns the activity data for the active panelist.

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

JSON Input Fields:

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

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
seskey string The sessionKey of the panelist to get a referral hash for.
email string The email address of the referrer.
points number The number of points awarded.

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
}

 

5:  Points

5.1:  portal.points.total

Get the panelist's current total reward points. This total is based on all additions and deductions, and also deducts any unprocessed points already requested for redemption.

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

JSON Input Fields:

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

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
seskey string The sessionKey of the panelist to get the points earned.

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
seskey string The sessionKey of the panelist to get points redeemed.

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
seskey string The sessionKey of the panelist to get points from surveys data.

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
seskey string A valid login hash.

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
seskey string A valid login hash.

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:  Redemption

6.1:  portal.redemption.create

Create a Redemption request.

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

JSON Input Fields:

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

Example POST:

{
    seskey: 'ce512c91',
    type:   2
}


JSON Output Fields on Success:

Parameter Type Description
success boolean true The creation was successful.

Example success:

{
    success: true
}


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
}

 

6.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
seskey string A valid login hash.
limit number Limit the output (i.e. 20, 100 OR 100).

Example POST:

{
    seskey: 'ce512c91',
    limit:  100
}


JSON Output Fields on Success:

Parameter Type Description
success boolean true Retrieving the redemption request was successful.
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
type string Redemption type, currently check, paypal, or gift.
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
}

 

7:  Rewar

7.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
seskey string A valid login hash.

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
}

 

7.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
seskey string A valid login hash.
limit number (optional) Max number of surveys to return, default is all.

Example POST:

{
    seskey: 'ce512c91',
    limit:  10
}


JSON Output Fields on Success:

Parameter Type Description
success boolean true Retrieving the reward history was successful.
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 The subject of the invitation email that was used when the panelist was invited.
projectid number The project ID.

Example success:

{
    success: true,
    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:  Survey

8.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
seskey string A valid login hash.
limit number (optional) Max number of surveys to return, default is all.

Example POST:

{
    seskey: 'ce512c91',
    limit:  10
}


JSON Output Fields on Success:

Parameter Type Description
success boolean true The list of completed surveys was successful.
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
project string Name of the project.
description string (deprecated) Always returns an empty string.
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.

Example success:

{
    success: true,
    surveys: [
                 {
                     project:     'Sample project one',
                     description: '',
                     status:      'completed',
                     time:        '2011-11-18 16:10',
                     points:      200,
                     projectid:   45
                 },
                 {
                     project:     'Sample project two',
                     description: '',
                     status:      'quota',
                     time:        '2011-08-12 15:23',
                     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
}

 

8.2:  portal.survey.available

This method returns an array of survey records.

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

JSON Input Fields:

Parameter Type Description
seskey string A valid login hash.
limit number Max number of surveys to return, default is all.

Example POST:

{
    seskey: 'ce512c91',
    limit:  10
}


JSON Output Fields on Success:

Parameter Type Description
success boolean true The list of available surveys was successful.
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
subject string Email subject that was used in the invitation.
status string 'started' if the panelist has started, but not completed the survey, otherwise NULL.
time string The time this portal 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 (portal 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 (portal 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

Example success:

{
    success: true,
    surveys: [
                 {
                     subject:    'You have been invited to take part in a Sample Project.',
                     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
                 }
             ]
}


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
}

 

8.3:  portal.survey.registerUrl

Returns the registration survey url.

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

JSON Input Fields:

Parameter Type Description
panelid number The Panel ID.
portalid number The Community Portal ID.
mobile boolean Should a mobile link be returned or not.

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
}

 

8.4:  portal.survey.registerUpdateUrl

Returns the registration update survey url.

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

JSON Input Fields:

Parameter Type Description
seskey string A valid login hash.
mobile boolean Should a mobile link be returned or not.

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
}

 

9:  System

9.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
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?