Skip to main content

FV Kinesis Support

All the topics, resources needed for FV Kinesis.

FocusVision Knowledge Base

Panel Integration 4.5.0 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 Required
username string The panel username. yes
password string The panel password. yes
force boolean Force the login, in case you already have an active session (DEPRECATED). no
panelid integer Panel ID for selecting the correct panel no

Example POST:

{
    "username": "myaccount",
    "password": "abc123!",
    "panelid": 1
}

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 Required
sesKey string A valid login hash. yes

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 Required
sesKey string A valid login hash. yes
settings array An associative array of settings stdClass objects with the structure of 'label'=>'answer' yes
messages array An associative array indexed by localid consisting of associative arrays of message data with the structure of 'label'=>'answer' yes
sampleids array A zero based array of sampleids to include in the invitation launch. yes


JSON Input settings array:

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


JSON Input messages array:

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

 

Example POST:

{
    "sessKey": "5a15852c564933807bbd36da58071063",
    "settings": {
        "name": "Test Campaign",
        "startTime": "2011-12-22 17:50:00",
        "type": "html",
        "senderName": "Test",
        "senderEmailAddress": "info@kinesissurvey.com"
    },
    "messages": [
        {
            "subject": "Test Email",
            "content": "This is the Test Email."
        },
        {
            "subject": "Test Email 2",
            "content": "This is the Second Test Email."
        }
    ],
    "sampleids": [
        1,
        2,
        3
    ]
}

Response Data:

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

 

Example success:

{
    "success": true,
    "data": {
        "campaignid": 2
    }
}

2.2:  integration.campaign.listing

Read listing of all campaign scheduled for the current project.

JSON Input Fields:

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

Example POST:

{
    "sesKey": "5a15852c564933807bbd36da58071063",
}

Response Data: (array)

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

Example success:

{
    "success": true,
    "data": [
        {
            "id": 2,
            "name": "New portal only campaign",
            "description": "",
            "starttime": "2011-10-11 19:00:00",
            "endtime": null,
            "purpose": "portal",
            "portalinvitation": "yes",
            "pointscompleted": 100,
            "pointsprofile": 30,
            "pointsquota": 10,
            "maxparticipation": 1,
            "pointstermination": "first",
            "created_by": "Kinesis Tester",
            "created": "2011-10-14 12:46:52"
        }
    ]
}

2.3:  integration.campaign.get

Read listing of all campaign scheduled for the current project.

JSON Input Fields:

Parameter Type Description Required
sesKey string A valid login hash. yes
campaignid integer The id of the campaign. yes

Example POST:

{
    "sesKey": "5a15852c564933807bbd36da58071063",
    "campaignid": 42,
}

Response Data:

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

Example success:

{
    "success": true,
    "data": {
        "id": 2,
        "name": "New portal only campaign",
        "description": "",
        "starttime": "2011-10-11 19:00:00",
        "endtime": null,
        "purpose": "portal",
        "portalinvitation": "yes",
        "pointscompleted": 100,
        "pointsprofile": 30,
        "pointsquota": 10,
        "maxparticipation": 1,
        "pointstermination": "first",
        "created_by": "Kinesis Tester",
        "created": "2011-10-14 12:46:52"
    }
}

2.4:  integration.campaign.schedule

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

JSON Input Fields:

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

Example POST:

{
    "sesKey": "5a15852c564933807bbd36da58071063",
    "campaignid": 1
}

Response Data: (array)

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


Example success:

{
    "success": true
    "data": {
        "type": "sample",
        "scheduled": "2011-10-11 19:00:00",
        "name": "Sample import from list by Kinesis",
        "sampleid": 4,
        "created_by": "Kinesis Tester"
    }
}

3:  Category

3.1:  integration.category.listing

This call retrieves a list of defined categories for the selected panel.

JSON Input Fields:

Parameter Type Description Required Since
sesKey string A valid login hash. yes 4.5

Example POST:

{
    "sesKey": "5a15852c564933807bbd36da58071063"
}

Response data:

Parameter Type Description Since
id int The category id (used in integration.project.create and integration.project.listing) 4.5
name string The name of the category 4.5

Example success:

{
    "success": true
    "data": [
        {
            "id": 1,
            "name": "New category"
        },
        {
            "id": 2,
            "name": "Second category"
        }
    ]
}

No categories

{
    "success": true
    "data": []
}

4:  Community

4.1:  integration.community.createSession

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


JSON Input Fields:

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

Example POST:

{
    "sesKey": "5a15852c564933807bbd36da58071063",
    "username": "test@kinesissurvey.com"
}


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.

Example success:

{
    "success": true,
    "data": {
        "seskey": "672ef56f6a475fedb0fcf8f109e3f410",
        "panelistid": 1,
        "email": "test@kinesissurvey.com",
        "fullname": ""
    }
}

4.2:  integration.community.getLandingPage

Query community landing page texts and page titles.
Since panel itself does not display themed info pages anymore, but has its built in community portal handle it instead, in order to display these now called "landing pages" when the community portal is in API Mode, this call is necessary.
Every time a panelist triggers an action that before would have resulted in a message displayed on screen, we must now query for that.
When a community is used in "API mode", an setting becomes available to specify a "Receiver URL for landing pages". This URL is where panelists are redirected and where the landing page can be shown.

Example PHP code for landing page receiver:

<?php

// Get parameter from incoming URL
$kslp = $_GET['kslp'];
// Prepare data to be sent to API
$data = array(
	'sesKey'=>$sesKey, // We must be authenticated to use this! (see: integration.auth.login)
	'encStr'=>$kslp
);
// JSON Encode our data
$dataJSON = json_encode($data);

// Initialize CURL and post the data
$client = curl_init();
curl_setopt($client, CURLOPT_URL, "https://example.com/panel/api.pro?method=integration.community.getLandingPage");
curl_setopt($client, CURLOPT_POST, true);
curl_setopt($client, CURLOPT_POSTFIELDS, array('data' => $dataJSON));
curl_setopt($client, CURLOPT_RETURNTRANSFER, true);
// Submit request
$result = curl_exec($client);

// JSON decode result data
$result = json_decode($result);

?>

<html>
<head>
<title><?php echo $result->data->title; ?></title>
</head>
<body>
<?php echo $result->data->message; ?>
</body>
</html>

JSON Input Fields:

Parameter Type Description Required
sesKey string A valid login hash. yes
encStr string This string is submitted via URL to the current "Receiver URL for landing pages", which is configurable on the "Community settings" page in the Community manager.
The incoming URL parameter is called: "kslp" and is safe for submitting via URL. It must not be altered in any way.
yes

Example POST:

{
    "sesKey": "5a15852c564933807bbd36da58071063",
    "encStr": "mLBVh8xap8EmpdilvnTSh3gMY3Yxg1Y08FifDcH64mydZf6klHFAidAq0CjIzTi_uZDtCQJEtLnHPl_NjmXDwktJDJqCiTIdiUx1UVyM2psBWjzfDm1qcTG-1VGQnR-P3AVC_kNVdGQFcfMc7kB3NQ"
}


Response Data:

Parameter Type Description
success boolean true encStr parameter was successfully validated
data array Landing page data.


Response "data":

Parameter Type Description
title string The landing page title.
message string The landing page text with all datapoint pipes replaced and in the language of the panelist.

Example success:

{
    "success": true,
    "data": {
        "title": "Participation recorded!",
        "message": "<span style='font:normal 1em Arial;'>We appreciate your responses. Your participation in this study has been recorded.<br /><br />Thank you!</span>",
    }
}

5:  Datapoint

5.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 Required
sesKey string A valid login hash. yes
settings array An associative array that differs based on the datapoint type. yes


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

Name Description Required
label The label of the datapoint. yes
qtext The question text of the datapoint. yes
type The datapoint type. yes


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

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


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

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

Example POST:

{
    "sesKey": "5a15852c564933807bbd36da58071063",
    "settings": {
        "label": "Q3",
        "qtext": "Thisisdatapointthree",
        "type": "openend"
    }

}

Example success:

{
    "success": true,
    "data": {
        "datapointid": 3
    }
}

5.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 Required
sesKey string A valid login hash. yes
datapointid integer Datapoint ID yes

Example POST:

{
    "sesKey": "5a15852c564933807bbd36da58071063",
    "datapointid": 1
}

Example success:

{
    "success": true
}

5.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 Required
sesKey string A valid login hash. yes
label string The label of the datapoint. yes

Example POST:

{
  "sesKey": "5a15852c564933807bbd36da58071063",
  "label": "Q1"
}

JSON Response Data:

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

Example success:

{
    "success": true
    "data":  {
        "datapointid": 1
    }
}

6:  Panel

6.1:  integration.panel.select

JSON Input Fields:

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

Example POST:

{
    "sesKey": "5a15852c564933807bbd36da58071063",
    "panelid": "1"
}

Example success:

{
    "success": true
}

7:  Panelist

7.1:  integration.panelist.rewardPointsAdd

Add points to the panelist's account.

JSON Input Fields:

Parameter Type Description Required
sesKey string A valid login hash. yes
index string Panelist identifier or PID yes
points integer Points to add yes
note string Note that will be visible to the panelists and show in the rewards history. yes


Example POST:

{
    "sesKey": "5a15852c564933807bbd36da58071063",
    "index": 34359
    "points": 50
    "note": "Participation bonus"
}

Example success:

{
     "success": true
}

7.2:  integration.panelist.rewardPointsDeduct

Deduct points from the panelist's account.

JSON Input Fields:

Parameter Type Description Required
sesKey string A valid login hash. yes
index string Panelist identifier or PID yes
points integer Points to deduct (must be negative) yes
note string Note that will be visible to the panelists and show in the rewards history. yes


Example POST:

{
    "sesKey": "5a15852c564933807bbd36da58071063",
    "index": 34359
    "points": -50
    "note": "Gift card redemption"
}

Example success:

{
     "success": true
}

7.3:  integration.panelist.addPoints (DEPRECATED)

This method is deprecated, use integration.panelist.rewardPointsDeduct and integration.panelist.rewardPointsAdd instead. Add or deduct points from the panelist account.

JSON Input Fields:

Parameter Type Description Required
sesKey string A valid login hash. yes
index string Panelist identifier or PID yes
points integer Points to add or points to deduct (using negative value) yes
note string Note that will be visible to the panelists and show in the rewards history. yes


Example POST:

{
    "sesKey": "5a15852c564933807bbd36da58071063",
    "index": 34359
    "points": -50
    "note": "Redeemed gift card"
}

Example success:

{
     "success": true,
     "deprecated": true
}

7.4:  integration.panelist.rewardPointsBalance

Get a panelist's current reward point balance

JSON Input Fields:

Parameter Type Description Required
sesKey string A valid login hash. yes
index string Panelist identifier or PID yes


Example POST:

{
    "sesKey": "5a15852c564933807bbd36da58071063",
    "index": 34359
}

Example success:

{
    "success": true,
    "data": [
        "balance": 9001
    ]
}

7.5:  integration.panelist.create

Create a panelist with accompanying data

JSON Input Fields:

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

Example POST:

{
    "sesKey": "5a15852c564933807bbd36da58071063",
    "settings": [
        {
            "label": "email",
            "answer": "test@kinesissurvey.com"
        },
        {
            "label": "sourceid",
            "answer": 335
        },
        {
            "label": "identifier",
            "answer": "KS_234234"
        }
    ]
}

JSON Response Data:

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


Example success:

{
     "success": true,
     "data": {
        "pid": 1,
        "sourceid": null,
        "localid": 1,
        "portalid": 1,
        "subscribed": "yes",
        "identifier": "test",
        "email": "test@kinesissurvey.com",
        "password": "c393160294275737d9c5cb047242342b",
        "emailok": "yes",
        "phoneok": "no",
        "blacklisted": "no",
        "modified": "2011-12-0114: 02: 15",
        "created": "2011-10-1411: 09: 56",
        "joined": "2011-01-01",
        "first_participation": null,
        "last_participation": null,
        "first_invitation": null,
        "last_invitation": null,
        "unsubscribed": null,
        "timeblacklisted": null,
        "timeunblacklisted": null,
        "timereferred": null,
        "first_completed": null,
        "last_completed": null,
        "last_pointsearned": null,
        "last_surveyscreened": null,
        "responserate": null,
        "completionrate": null,
        "invited": 0,
        "responded": 0,
        "completed": 0,
        "md_invited": 0,
        "md_started": 0,
        "md_completed": 0,
        "md_screened": 0,
        "md_finished": 0,
        "md_referredpanelists": 1,
        "points_earned": 0,
        "points_available": 0,
        "points_redeemed": 0,
        "points_survey": 0,
        "points_referral": 0,
        "points_other": 0
    }
}

7.6:  integration.panelist.read

Read panelist data from the Kinesis Panel database. By default, this call will return all panelist system fields (see example below), unless the optional datapoints parameter is supplied. If the optional datapoints parameter is supplied, the call will return only the requested values (if found). Please note that question labels and system field names are case-sensitive.

JSON Input Fields:

Parameter Type Description Required
sesKey string A valid login hash. yes
index string The pid or identifier to lookup the panelist by yes
datapoints array Array of datapoint labels or panelist fields to return no

Example POST:

{
    "sesKey": "5a15852c564933807bbd36da58071063",
    "index": 1
}

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_referral The number of points the panelist has received from referrals.
points_other The number of points the panelist has received from an administrator.

Example success:

{
    "success": true,
    "data": {
        "pid": "1",
        "sourceid": "1",
        "localid": "1",
        "portalid": "1",
        "subscribed": "yes",
        "identifier": "1_SVFMJV",
        "email": "test@example.com",
        "password": null,
        "emailok": "yes",
        "phoneok": "no",
        "blacklisted": "no",
        "modified": "2011-11-08 16:39:02",
        "created": "2011-10-04 12:50:32",
        "joined": "2011-10-04",
        "first_participation": null,
        "last_participation": null,
        "first_invitation": null,
        "last_invitation": null,
        "unsubscribed": null,
        "timeblacklisted": null,
        "timeunblacklisted": null,
        "timereferred": null,
        "first_completed": null,
        "last_completed": null,
        "last_pointsearned": "2011-11-08 16:39:02",
        "last_surveyscreened": null,
        "responserate": null,
        "completionrate": null,
        "invited": "0",
        "responded": "0",
        "completed": "0",
        "md_invited": "0",
        "md_started": "0",
        "md_completed": "0",
        "md_screened": "0",
        "md_finished": "0",
        "md_referredpanelists": "0",
        "points_earned": "5000",
        "points_available": "5000",
        "points_redeemed": "0",
        "points_survey": "0",
        "points_referral": "0",
        "points_other": "5000"
    }
}

7.7:  integration.panelist.update

Update a panelist data

JSON Input Fields:

Parameter Type Description Required
sesKey string A valid login hash. yes
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. Email or Identifier required. yes

Example POST:

{
    "sesKey": "5a15852c564933807bbd36da58071063",
    "settings": [
        {
            "label": "email",
            "answer": "test@kinesissurvey.com"
        },
        {
            "label": "sourceid",
            "answer": 335
        },
        {
            "label": "identifier",
            "answer": "KS_234234"
        }
    ]
}

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.

Example success:

{
    "success": true
}

8:  Project

8.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 Required
sesKey string A valid login hash. yes
projectid string The id of the project to select. yes

Example POST:

{
    "sesKey": "5a15852c564933807bbd36da58071063",
    "projectid": 1
}

Example success:

{
    "success": true
}

8.2:  integration.project.create

Create a new project in the currently selected panel.

JSON Input Fields:

Parameter Type Description Required Since
sesKey string A valid login hash. yes  
settings array An associative array containing project settings (listed below). yes  
categories array An array of category IDs that the project will be assigned to. (Category IDs can be obtained by calling integration.category.listing) no 4.5

Example POST:

{
    "sesKey": "5a15852c564933807bbd36da58071063",
    "settings": {
        "name": "First Project",
        "url": "https://web.example.com/panelinstall/?identifier=[IDENTIFIER]&sesskey=[sesskey]"
    }
}

Example with categories:

{
    "sesKey": "5a15852c564933807bbd36da58071063",
    "settings": {
        "name": "First Project",
        "url": "https://web.example.com/panelinstall/?identifier=[IDENTIFIER]&sesskey=[sesskey]"
    },
    "categories" : [
        1,
        2,
        42
    ]
}

Settings array

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


JSON Response Data:

Parameter Type Description Since
projectid integer Unique project identifier  

Example success:

{
    "success": true,
    "data": {
        "projectid": 3
    }
}

8.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 Required
sesKey string A valid login hash. yes
projectid integer The id of the project to close. yes

Example POST:

{
    "sesKey": "5a15852c564933807bbd36da58071063",
    "projectid": 1
}

Example success:

{
    "success": true
}

 


8.4:  integration.project.read (participation)

Output Project data with an input of participation.


JSON Input Fields:

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

Example POST:

{
    "sesKey": "5a15852c564933807bbd36da58071063",
    "type": "participation"
}

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+)

Example success:

{
    "success": true
    "data": [
        {
            "sessionid": 259,
            "identifier": "1_SVFMJV",
            "status": "pending",
            "statusDate": "2011-11-08 17:33:48",
            "firstStarted": null
        }
    ]
}

8.5:  integration.project.read (statistics)

Output project data with an input of statistics.


JSON Input Fields:

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

Example POST:

{
    "sesKey": "5a15852c564933807bbd36da58071063",
    "type": "statistics"
}
delivery: An object containing 6 objects, the first five of which contain three fields. (count, alias, and percent)
Parameter 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)
Parameter 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)
Parameter 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)
Parameter 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.

Example success:

{
    "success": true,
    "data": {
        "delivery": {
            "delivered": {
                "count": 0,
                "alias": "Delivered",
                "percent": ""
            },
            "pending": {
                "count": 246,
                "alias": "Pending",
                "percent": "100%"
            },
            "bounced": {
                "count": 0,
                "alias": "Bounced",
                "percent": ""
            },
            "deferred": {
                "count": 0,
                "alias": "Deferred",
                "percent": ""
            },
            "unknown": {
                "count": 0,
                "alias": "Unknown",
                "percent": ""
            },
            "total": 246
        },
        "response": {
            "responded": {
                "count": 0,
                "alias": "Responders",
                "percent": "0%"
            },
            "nonresponsive": {
                "count": 0,
                "alias": "Non-responders",
                "percent": "0%"
            }
        },
        "completion": {
            "completed": {
                "count": 0,
                "alias": "Completed",
                "percent": "0%"
            },
            "profile": {
                "count": 0,
                "alias": "Profile terminated",
                "percent": "0%"
            },
            "quota": {
                "count": 0,
                "alias": "Quota terminated",
                "percent": "0%"
            },
            "started": {
                "count": 0,
                "alias": "Dropouts",
                "percent": "0%"
            },
            "invited": {
                "count": 0,
                "alias": "Non-responders",
                "percent": "0%"
            },
            "total": 0,
            "campaigns": 5
        },
        "rewards": {
            "completed": {
                "count": 246,
                "alias": "Completed",
                "points": 24600
            },
            "profile": {
                "count": 0,
                "alias": "Profile terminated",
                "points": 0
            },
            "quota": {
                "count": 0,
                "alias": "Quota terminated",
                "points": 0
            }
        }
    }
}

8.6:  integration.project.read (all statistics)

Read all project statistics.


JSON Input Fields:

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

Example POST:

{
    "sesKey": "5a15852c564933807bbd36da58071063",
    "type": "allstatistics"
}


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)
Parameter 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)
Parameter 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)
Parameter 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)
Parameter 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.

Example success:

{
    "success": true,
    "data": {
        "delivery": {
            "delivered": {
                "count": 0,
                "alias": "Delivered",
                "percent": ""
            },
            "pending": {
                "count": 246,
                "alias": "Pending",
                "percent": "100%"
            },
            "bounced": {
                "count": 0,
                "alias": "Bounced",
                "percent": ""
            },
            "deferred": {
                "count": 0,
                "alias": "Deferred",
                "percent": ""
            },
            "unknown": {
                "count": 0,
                "alias": "Unknown",
                "percent": ""
            },
            "total": {
                "count": 246
            }
        },
        "response": {
            "responded": {
                "count": 0,
                "alias": "Responders",
                "percent": "0%"
            },
            "nonresponsive": {
                "count": 0,
                "alias": "Non-responders",
                "percent": "0%"
            }
        },
        "completion": {
            "completed": {
                "count": 0,
                "alias": "Completed",
                "percent": "0%"
            },
            "profile": {
                "count": 0,
                "alias": "Profile terminated",
                "percent": "0%"
            },
            "quota": {
                "count": 0,
                "alias": "Quota terminated",
                "percent": "0%"
            },
            "started": {
                "count": 0,
                "alias": "Dropouts",
                "percent": "0%"
            },
            "invited": {
                "count": 0,
                "alias": "Non-responders",
                "percent": "0%"
            },
            "total": {
                "count": 0,
                "alias": "Sample size"
            },
            "campaigns": {
                "count": 5,
                "alias": "Number of campaigns"
            }
        },
        "rewards": {
            "completed": {
                "count": 246,
                "alias": "Completed",
                "points": 24600
            },
            "profile": {
                "count": 0,
                "alias": "Profile terminated",
                "points": 0
            },
            "quota": {
                "count": 0,
                "alias": "Quota terminated",
                "points": 0
            },
            "total": {
                "count": 246,
                "points": 24600
            }
        }
    }
}

 

8.7:  integration.project.listing

List all Projects


JSON Input Fields:

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


Example POST:

{
    "sesKey": "5a15852c564933807bbd36da58071063",
}


JSON Output Fields on Success:

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


JSON Response data on Success

Parameter Description Since
id Project id  
name Project name  
status Project status  
created The project's date of creation.  
created_by The user who created the project.  
categories An array of category IDs that the project belongs to. (Category IDs can be obtained by calling integration.category.listing) 4.5

Example success:

{
    "success": true
    "data": [
        {
            "id": 1,
            "name": "foo's new project",
            "status": "open",
            "created": "2011-10-14 12:13:13",
            "closed": null,
            "created_by": "Kinesis Tester"
            "categories": [
                1,
                2,
                42
            ]
        },
        {
            "id": 2,
            "name": "bar's new project",
            "status": "closed",
            "created": "2014-02-10 14:34:00",
            "closed": null,
            "created_by": "Kinesis Tester"
            "categories": []
        },
    ]
}

9:  Reminder

9.1:  integration.reminder.create

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


JSON Input Fields:

Parameter Type Description Required
sesKey string A valid login hash. yes
campaignid int The campaignid of the campaign to create a reminder for. yes
messages array[] A zero based array of associative arrays containing message data, indexed by localid. yes
startDate string Date and time to send the reminder. yes
sampleIds array Specifies which samples to send to. (If empty it will send to all sampleids in the campaign) yes

Example POST:

{
    "sesKey": "5a15852c564933807bbd36da58071063",
    "campaignid": 2,
    "messages": [
        {
            "subject": "The Subject",
            "content": "This is the message content"
        }
    ],
    "startdate": "2011-12-24 17:40:00",
    "sampleids": [
        1,
        2,
        3
    ]
}

JSON Input messages object:

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

Example success:

{
    "success": true,
    "data": {
        "reminderid": 1
    }
}

10:  Sample

10.1:  integration.sample.create

Create a sample from panelist identifiers.


JSON Input Fields:

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

Example POST:

{
    "sesKey": "5a15852c564933807bbd36da58071063",
    "name": "First Sample",
    "description": "This is the First Sample",
    {
    "identifiers": [
        "130_FNOAHH",
        "131_FNOAHH",
        "132_FNOAHH",
        "133_FNOAHH",
        "134_FNOAHH"
    ]
}
}

JSON Response Data on Success:

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

Example success:

{
    "success": true,
    "data": {
        "sampleid": 1
    }
}

 

10.2:  integration.sample.update

Update a sample with appended data

JSON Input Fields:

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


Example POST:

{
    "sesKey": "5a15852c564933807bbd36da58071063",
    "sampleid": 1,
    "params": [
        "value1",
        "value2",
        "value3"
    ],
    "identifiers": [
        "130_FNOAHH",
        "131_FNOAHH"
    ],
    "data": [
        [
            1,
            2,
            3
        ],
        [
            4,
            5,
            6
        ]
    ]
}

Example success:

{
    "success": true
}

11:  Session

11.1:  integration.session.get

Get session info using the sessionkey. The return values contain basic data about the session, including project ID, campaign ID, panelist ID, status, start time etc.

JSON Input Fields:

Parameter Type Description Required
sesKey string A valid login hash. yes
sesString string 16 character panelist session string from the URL yes

Example POST:

{
    "sesKey": "5a15852c564933807bbd36da58071063",
    "sesString": "e0197525e7129c5c"
}

JSON Response Data on Success:

Parameter Type Description
projectid integer The project ID
campaignid integer The campaign ID
panelistid integer The panelist ID
status string The session status
starttime timedate The time when the session was started

Example success:

{
    "success": true,
    "data": [
        "projectid": 23,
        "campaignid": 59,
        "panelistid": 34359,
        "status": "started",
        "starttime": "2013-01-01 23:59:59"
    ]
}

 

11.2:  integration.session.update

Update the session status using the sessionkey. Optionally reward points can be distributed. Distributed points will also link the points to the panelist session. Note: Specified reward points will override any other default point values in the campaign manager.

JSON Input Fields:

Parameter Type Description Required
sesKey string A valid login hash. yes
sesString string 16 character panelist session string from the URL yes
status string Set the status of the completing panelist yes
points integer Optional to supply custom number of points no
note string Optional to supply custom note no


Example POST:

{
    "sesKey": "5a15852c564933807bbd36da58071063",
    "sesString": "e0197525e7129c5c",
    "status": "profile",
    "points": 50,
    "note": "Completed survey"
}

Example success:

{
    "success": true
}

12:  Surveys

12.1:  integration.surveys.available

Get a list of available surveys for a panelist

JSON Input Fields:

Parameter Type Description Required
sesKey string A valid login hash. yes
index string Panelist ID or identifier to look up the panelist yes

Example POST:

{
    "sesKey": "5a15852c564933807bbd36da58071063",
    "index": 34359
}

JSON Response Data on Success:

Parameter Type Description
subject string Email subject that was used in the invitation.
body string A more detailed survey description.
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.
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,
    "data": [
                 {
                     subject:    "You have been invited to take part in a Sample Project.",
                     body:       "This survey is about your favorite type of car.",
                     status:     null,
                     time:       "2013-01-01 23:59:59",
                     points:     200,
                     url:        "http://www.example.com/panelinstall/receiver.pro?seskey=e0197525e7129c5c",
                     type:       "emailhtml",
                     endtime:    "2013-01-01 23:59:59",
                     invited:    "2013-01-01 23:59:59",
                     purpose:    "invitation",
                     projectid:  10
                 }
             ]
}
  • Was this article helpful?