Skip to main content

Kinesis Support

All the topics, resources needed for Kinesis.

FocusVision Knowledge Base

Panel Integration 3.4 REST

1:  Auth

1.1:  integration.auth.login

Login to the System Integration API. In order to login you must have create Kinesis Panel user with type System Integration. This function returns sessionkey when successful or zero (user not found). If the login fails for any other errors the standard error is returned.

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

JSON Input Fields:

Parameter Type Description
username string The panelist username.
password string The panelist password.
force boolean Force the login, in case you already have a active session (optional).

Example POST:

{
    "username": "myaccount",
    "password": "abc123!",
    "force": true
}

Response Data:

Parameter Type Description
sesKey string A valid session key to be used in subsequent calls.

Example success:

{
    "success": true,
    "data": {
        "sesKey": "5a15852c564933807bbd36da58071063"
    }
}

1.2:  integration.auth.logout

Logout system integration user. This function will delete the current session for security purposes. It is highly recommended to call this function at the end of each connection.


JSON Input Fields:

Parameter Type Description
sesKey string A valid login hash.

Example POST:

{
    "sesKey": "5a15852c564933807bbd36da58071063",
    "force": true
}

Example success:

{
    "success": true
}

2:  Campaign

2.1:  integration.campaign.create

Schedule campaign for the panelists. Campaign are typically used to send email invitations to the panelists or publish new survey links to the respondent portal.

JSON Input Fields:

Parameter Type Description
sesKey string A valid login hash.
settings array An associative array of settings stdClass objects with the structure of 'label'=>'answer'
messages array An associative array of message stdClass objects with the structure of 'label'=>'answer'
sampleids array A zero based array of sampleids to include in the invitation launch.


JSON Input settings object:

Label Description
name Name of the campaign.
type Type of campaign. (sms, plainText, or html)
senderName Name of the sender. (visible in the email clients)
senderEmailAddress Sender email address.
startTime When to start sending out invitations. (international format YYYY-MM-DD hh:mm:ss)
description The description of the campaign.
purpose The purpose of the campaign. (invitation, profiler)
endTime When this campaign expires. (international format YYYY-MM-DD hh:mm:ss)
includePortal Whether or not to display this invitation to portal members. (true,false)
pointsCompleted Amount of points a panelist will receive upon completion. (Default: setting in project)
pointsProfile Amount of points a panelist will receive when profile terminating. (Default: setting in project)
pointsQuota Amount of points a panelist will receive when quota terminating. (Default: setting in project)
maxParticipation Amount of times a panelist is allowed to participate. (Default: setting in project)
pointsTermination Reward panelist every time he participates or only the first time. (every, first)


JSON Input messages object:

Label Description
subject Subject text.
content Message content (must be CAN-SPAM compliant http://www.ftc.gov/spam/)
locale An array of language codes. If they do not match the number of languages, it will fail. (Default: 1)
surveyLinkText Survey link text (HTML only) (if not specified, the link will be shown)
optoutLinkText Optout link text (HTML only) (if not specified, the link will be shown)
onlineLinkText Online link text (HTML only), for viewing message online, rather than in email (if not specified, the link will be shown)
replyToEmailAddress Where replies are sent (default is web service user's email address)


Response Data:

Parameter Type Description
campaignid int The ID of the newly created campaign.

2.2:  integration.campaign.listing

Read listing of all campaign scheduled for the current project.

JSON Input Fields:

Parameter Type Description
sesKey string A valid login hash.


Response Data: (array)

Label Description
id Id of the campaign.
name Name of the campaign.
description Description of the campaign.
starttime Start time of the campaign.
endtime End time of the campaign.
purpose Purpose of the campaign.
portalinvitation Name of the campaign.
pointscompleted Name of the campaign.
pointsprofile Name of the campaign.
pointsquota Name of the campaign.
maxparticipation Name of the campaign.
pointstermination Name of the campaign.
createdby Name of the user who created the campaign.
created Time and date of the creation of the campaign.

2.3:  integration.campaign.schedule

Outputs a list of all samples and reminders that were scheduled for a specific campaign.

JSON Input Fields:

Label Type Description
sesKey string A valid login hash.
campaignId integer The campaignid of the campaign to list the schedule of.


Response Data: (array)

Label Description
type The type (reminder, sample)
scheduled The date and time it was scheduled.
name The name of the sample or reminder.
sampleid If type is "sample", the sampleid will be listed here.
created_by The user the reminder or sample was created by.

3:  Community

3.1:  integration.community.createSession

(Added 3.4.7.0)

Creates an active session in the for use with Portal API, without the need for a panelist password.


JSON Input Fields:

Parameter Type Description
sesKey string A valid login hash.
username string The username of the panelist the session is created for.


Response Data:

Parameter Type Description
success boolean true Creation of the session was successful.
data array User credentials.


Response "data":

Parameter Type Description
seskey string A valid login hash.
panelistid string The id of the panelist that the session was created for.
email string The email address of the panelist that the session was created for.
fullname string The full name of the panelist that the session was created for.

4:  Datapoint

4.1:  integration.datapoint.create

This function is used to add new datapoints to the panel. All datapoint types are supported.


JSON Input Fields:

Parameter Type Description
sesKey string A valid login hash.
settings array An associative array that differs based on the datapoint type.


JSON settings array Input Field while datapoint type is openend or date

Parameter Description
label The label of the datapoint.
qtext The question text of the datapoint.
type The datapoint type.


JSON settings array Input Field while datapoint type is radio or checkbox

Parameter Description
label The label of the datapoint.
qtext The question text of the datapoint.
type The datapoint type.
choices A zero based array of associative arrays, with the size equal to the number of choices.


JSON choices array Input Field while datapoint type is radio or checkbox

Parameter Description
choiceid The choiceid of the datapoint choice.
name The name of the datapoint choice.
custom A user defined value for panelists that answer with the displayed option."

4.2:  integration.datapoint.delete

Delete existing datapoint by using its unique datapoint ID. WARNING. This will also delete all stored data for the datapoint.

JSON Input Fields:

Parameter Type Description
sesKey string A valid login hash.
datapointid integer Datapoint ID

4.3:  integration.datapoint.idFromLabel

This utility function allows retrieval of datapoint ID by using the label for the datapoint i.e. QAGE -> 22

JSON Input Fields:

Parameter Type Description
sesKey string A valid login hash.
label string The label of the datapoint.

JSON Response Data:

Parameter Type Description
data int Unique id for the given datapoint label.

5:  Panel

5.1:  integration.panel.select

JSON Input Fields:

Parameter Type Description
sesKey string A valid login hash.
panelid string The id of the panel to select.

6:  Panelist

6.1:  integration.panelist.create

Create a panelist with accompanying data

JSON Input Fields:

Parameter Type Description
sesKey string A valid login hash.
settings array[] A zero based array of associative arrays, with a size equal to the number of settings the user wishes to initialize. Settings are listed below.


JSON Response Data:

Parameter Type Description
identifier string Unique panelist identifier created by Kinesis Panel

6.2:  integration.panelist.read

Read panelist data from the Kinesis Panel database.


JSON Input Fields:

Parameter Type Description
sesKey string A valid login hash.
index integer The pid or identifier to lookup the panelist by


JSON Response Data:

Parameter Description
pid The id of the panelist.
sourceid The id of the source.
localid The localizationid, or language code of the panelist.
subscribed Whether the panelist is subscribed or not.
identifier The panelist identifier.
email The email address of the panelist.
password The password of the panelist.
emailok Whether the email is valid.
phoneok Whether the phone is valid.
blacklisted Whether the panelist is blacklisted or not.
timezone The timezone of the panelist.
dateformat The format of the date.
timeformat The format of the time.
modified The most recent date/time the panelist was updated.
created The date/time the panelist was created.
joined The date/time the panelist joined.
first_participation The date/time of the panelist's first participation.
last_participation The date/time of the panelist's last participation.
first_invitation The date/time of the panelist's first invitation.
last_invitation The date/time of the panelist's last invitation.
unsubscribed The date/time that the panelist was unsubscribed.
timeblacklisted The date/time that the panelist was blacklisted.
timeunblacklisted The date/time that the panelist was unblacklisteed.
timereferred The date/time that the panelist was referred.
first_completed The date/time that the panelist first completed a survey.
last_completed The date/time that the panelist last completed a survey.
last_pointsearned The date/time that the panelist last earned points.
last_surveyscreened last date/time that the panelist profiled or quota termed
responserate The number of responses out of the number of invites in a certain period of time (usually 90 days).
completionrate The number of completes out of the number of invites in a certain period of time (usually 90 days).
invited The number of surveys the panelist has been invited to in a certain period of time (usually 90 days).
responded The number of surveys the panelist has responded to in a certain period of time (usually 90 days).
completed The number of surveys the panelist has completed in a certain period of time (usually 90 days).
md_invited The number of surveys the panelist has been invited to.
md_started The number of surveys the panelist has responded to.
md_completed The number of surveys the panelist has completed.
md_screened The number of surveys the panelist has profiled or quota termed.
md_finished The number of surveys the panelist has finished.
md_referredpanelists The number of panelists this panelist has referred.
points_earned The number of points the panelist has earned.
points_available The number of points the panelist has available for redemption.
points_redeemed The number of points the panelist has redeemed.
points_survey The number of points the panelist has earned from completing surveys.
points_other The number of points the panelist has received from an administrator.

6.3:  integration.panelist.update

Update a panelist data

JSON Input Fields:

Parameter Type Description
sesKey string A valid login hash.
settings array[] A zero based array of associative arrays, with a size equal to the number of settings the user wishes to initialize. Settings are listed below.


Settings array:

Parameter Description
sourceid The id of the source.
localid The localizationid, or language code of the panelist.
subscribed Whether the panelist is subscribed or not.
identifier The panelist identifier.
email The email address of the panelist.
password The password of the panelist.
emailok Whether the email is valid.
phoneok Whether the phone is valid.
blacklisted Whether the panelist is blacklisted or not.
timezone The timezone of the panelist.
dateformat The format of the date.
timeformat The format of the time.
joined The date/time the panelist joined.
unsubscribed The date/time that the panelist was unsubscribed.
timeblacklisted The date/time that the panelist was blacklisted.
timeunblacklisted The date/time that the panelist was unblacklisteed.
timereferred The date/time that the panelist was referred.

7:  Project

7.1:  integration.project.select

Select a current project for the connection. The project will stay selected for all consecutive actions. Look for standard return for success or failure.

JSON Input Fields:

Parameter Type Description
sesKey string A valid login hash.
projectid string The id of the project to select.

7.2:  integration.project.create

Create a new project in the currently selected panel.

JSON Input Fields:

Parameter Type Description
sesKey string A valid login hash.
data array An associative array containing project settings with the structure of ('label'=>"", 'value'=>"")


Data array

Parameter Description
name Project name.
URL Project URL, including replacable parameters
description Project description.
clientId id must already exist in the panel.
theme name of theme to use for the project.
defaultCompletedReward Default number of points awarded for survey completion.
defaultProfileReward Default number of points awarded when respondent is profile terminated.
defaultQuotaReward Default number of points awarded when respondent is quota terminated.
defaultMaxParticipation Default number of times respondent can take survey. (0 is unlimited)
receiveEncryptType invitation link encryption.
terminationEncryptType termination link encryption.
secret secret key used for encryption. (should be set to the same value for the survey)


JSON Response Data:

Parameter Type Description
projectid integer Unique project identifier

7.3:  integration.project.close

Closes specified project ID. Once project is closed the panelist will have "grace" period to complete taking the survey, thereafter panelists are no longer accepted to start surveys. Check for standard return for success code (true/false).

JSON Input Fields:

Parameter Type Description
sesKey string A valid login hash.
projectid integer The id of the project to close.

7.4:  integration.project.read (participation)

Output Project data with an input of participation.


JSON Input Fields:

Parameter Type Description
sesKey string A valid login hash.
type string "participation" A call to project.read that returns only participation project statistics.


Response data:

Parameter Type Description
sessionId string The sessionid of the participant (V3.4.7+)
identifier string The identifier of the participant.
status string The status of the participant.
statusDate string The date of the status of the participant. (V3.4.7+)
firstStarted string The start date of the participant. (V3.4.7+)

7.5:  integration.project.read (statistics)

Output project data with an input of statistics.


JSON Input Fields:

Parameter Type Description
sesKey string A valid login hash.
type string "statistics" A call to project.read that returns project statistics.

 

delivery: An object containing 6 objects, the first five of which contain three fields. (count, alias, and percent)
Object Description
delivered The project data of delivered invitations.
pending The project data of pending invitations .
bounced The project data of bounced invitations.
deferred The project data of deferred invitations.
unknown The project data of invitations whose status is unknown.
total The total amount of invitations within the project. Should be the sum of Delivered, Pending, Bounced, Deferred, and Unknown.

 

response: An object containing 2 objects, both of which contain three fields. (count, alias, and percent)
Object Description
responded The panelists who responded to an invitation.
nonresponsive The panelists who did not respond to an invitation.

 

completion: An object containing 7 objects, the first 5 of which contain three fields. (count, alias, and percent)
Object Description
completed Instances where a panelist completed a survey.
profile terminated Instances where a panelist profile terminated a survey.
quota Instances where a panelist quota terminated a survey.
started Instances where a panelist only started a survey.
invited Instances where a panelist was only invited to a survey.
total The sum of all counts from the above statuses.
campaigns The number of campaigns included in these statistics.

 

rewards: An object containing 3 objects, all of which contain three fields. (count, alias, and points)
Object Description
completed Instances where a panelist completed a survey.
profile Instances where a panelist profile terminated a survey.
quota Instances where a panelist quota terminated a survey.

7.6:  integration.project.read (all statistics)

Read all project statistics.


JSON Input Fields:

Parameter Type Description
sesKey string A valid login hash.
type string "allstatistics" A call to project.read that returns all project statistics.


Returned Project data on Success with an input of allstatistics:

Parameter Type Description
success boolean true Returning project statistics was successful.
data stdClass[4] An array of 4 stdClass objects: delivery, response, completion, and rewards

 

delivery: An object containing 6 objects, the first five of which contain three fields. (count, alias, and percent)
Object Description
delivered The project data of delivered invitations.
pending The project data of pending invitations .
bounced The project data of bounced invitations.
deferred The project data of deferred invitations.
unknown The project data of invitations whose status is unknown.
total The total amount of invitations within the project. Should be the sum of Delivered, Pending, Bounced, Deferred, and Unknown.

 

response: An object containing 2 objects, both of which contain three fields. (count, alias, and percent)
Object Description
responded The panelists who responded to an invitation.
nonresponsive The panelists who did not respond to an invitation.

 

completion: An object containing 7 objects, the first 5 of which contain three fields. (count, alias, and percent)
Object Description
completed Instances where a panelist completed a survey.
profile terminated Instances where a panelist profile terminated a survey.
quota Instances where a panelist quota terminated a survey.
started Instances where a panelist only started a survey.
invited Instances where a panelist was only invited to a survey.
total Contains the alias of "Sample size" and a count that is the sum of all counts from the above statuses.
campaigns Contains the alias of "Number of Campaigns" and a count that is the number of campaigns included in these statistics.

 

rewards: An object containing 4 objects, the first 3 of which contain three fields. (count, alias, and points)
Object Description
completed Instances where a panelist completed a survey.
profile Instances where a panelist profile terminated a survey.
quota Instances where a panelist quota terminated a survey.
total Contains a count that is equal to the sum of the above counts, and also contains the sum of all points from the above points.


JSON Output Fields on Failure:

Parameter Type Description
success boolean false Returning project statistics was unsuccessful.
error string The error message.
errno number The error number.

7.7:  integration.project.listing

List all Projects


JSON Input Fields:

Parameter Type Description
sesKey string A valid login hash.


JSON Output Fields on Success:

Parameter Type Description
projects array An array of stdClass objects, each of which is a project containing project data.


Returned projects array on Success

Parameter Description
id Project id
name Project name
status Project status
created The project's date of creation.
created_by The user who created the project.

8:  Reminder

8.1:  integration.reminder.create

Create a reminder for an existing campaign (requires existing campaign with existing scheduled invitation)


JSON Input Fields:

Parameter Type Description
sesKey string A valid login hash.
campaignid int The campaignid of the campaign to create a reminder for.
messages array Associative array containing message data with the structure of 'label'=>'answer'
startDate string Date and time to send the reminder.
sampleIds array Specifies which samples to send to. (If empty it will send to all sampleids in the campaign)


JSON Input messages object:

Label Description
subject Subject text.
content Message content (must be CAN-SPAM compliant http://www.ftc.gov/spam/)
locale An array of language codes. If they do not match the number of languages, it will fail. (Default: 1)
surveyLinkText Survey link text (HTML only) (if not specified, the link will be shown)
optoutLinkText Optout link text (HTML only) (if not specified, the link will be shown)
onlineLinkText Online link text (HTML only), for viewing message online, rather than in email (if not specified, the link will be shown)
replyToEmailAddress Where replies are sent (default is web service user's email address)


JSON Response Data on Success:

Parameter Type Description
data stdClass Returns a stdClass object containing reminderid, The id of the newly created reminder.

9:  Sample

9.1:  integration.sample.create

Create a sample from panelist identifiers.


JSON Input Fields:

Parameter Type Description
sesKey string A valid login hash.
name string Name of the sample.
description string Description of the sample.
identifiers array Zero-based array of identifiers to be included in the sample.


JSON Response Data on Success:

Parameter Type Description
data stdClass A stdClass object containing the sampleid of the newly created sample.

9.2:  integration.sample.update

Update a sample with appended data

JSON Input Fields:

Parameter Type Description
sesKey string A valid login hash.
sampleid integer Sample to which you want to append data. (must already exist)
params array Zero-based array containing parameter names. (i.e. value1,value2)
identifiers array Zero-based array containing identifiers to append data to.
data array[] Array of arrays, containing data for each param, for each panelist, (same order as identifier array)
  • Was this article helpful?