Skip to main content

FV Kinesis Support

All the topics, resources needed for FV Kinesis.

 
FocusVision Knowledge Base

Panel Integration 3.5.2 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:

Name Type Required Description
username string yes The panel username.
password string yes The panel password.
force boolean no Force the login, in case you already have a active session (optional).

Example POST:

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

Response Data:

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

Name Type Required Description
sesKey string yes 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:

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


JSON Input settings array:

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


JSON Input messages array:

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

 

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:

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

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

Example POST:

{
    "sesKey": "5a15852c564933807bbd36da58071063",
}

Response Data: (array)

Name 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.schedule

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

JSON Input Fields:

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

Example POST:

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

Response Data: (array)

Name 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:  Community

3.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:

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

Example POST:

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


Response Data:

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


Response "data":

Name 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": ""
    }
}

3.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:

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

Example POST:

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


Response Data:

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


Response "data":

Name 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>",
    }
}

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:

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


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

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


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

Name Required Description
label yes The label of the datapoint.
qtext yes The question text of the datapoint.
type yes The datapoint type.
choices yes 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

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

Example POST:

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

Example success:

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

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:

Name Type Required Description
sesKey string yes A valid login hash.
datapointid integer yes Datapoint ID

Example POST:

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

Example success:

{
    "success": true
}

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:

Name Type Required Description
sesKey string yes A valid login hash.
label string yes The label of the datapoint.

Example POST:

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

JSON Response Data:

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

Example success:

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

5:  Panel

5.1:  integration.panel.select

JSON Input Fields:

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

Example POST:

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

Example success:

{
    "success": true
}

6:  Panelist

6.1:  integration.panelist.addPoints (DEPRECATED)

Add or deduct points from the panelist account.

JSON Input Fields:

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


Example POST:

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

Example success:

{    
     "success": true    
}

6.2:  integration.panelist.create

Create a panelist with accompanying data

JSON Input Fields:

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

Example POST:

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

JSON Response Data:

Name 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
    }
}

6.3:  integration.panelist.read

Read panelist data from the Kinesis Panel database.


JSON Input Fields:

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

Example POST:

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

JSON Response Data:

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

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"
    }
}

6.4:  integration.panelist.update

Update a panelist data

JSON Input Fields:

Name Type Required Description
sesKey string yes A valid login hash.
settings array[] yes 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.

Example POST:

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

Settings array:

Name 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
}

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:

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

Example POST:

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

Example success:

{
    "success": true
}

7.2:  integration.project.create

Create a new project in the currently selected panel.

JSON Input Fields:

Name Type Required Description
sesKey string yes A valid login hash.
data array yes An associative array containing project settings (listed below).

Example POST:

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

Data array

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


JSON Response Data:

Name Type Description
projectid integer Unique project identifier

Example success:

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

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:

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

Example POST:

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

Example success:

{
    "success": true
}

7.4:  integration.project.read (participation)

Output Project data with an input of participation.


JSON Input Fields:

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

Example POST:

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

Response data:

Name 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
        }
    ]
}

7.5:  integration.project.read (statistics)

Output project data with an input of statistics.


JSON Input Fields:

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

Example POST:

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

7.6:  integration.project.read (all statistics)

Read all project statistics.


JSON Input Fields:

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

Example POST:

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


Returned Project data on Success with an input of allstatistics:

Name 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)
Name 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)
Name 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)
Name 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)
Name 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
            }
        }
    }
}

7.7:  integration.project.listing

List all Projects


JSON Input Fields:

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


Example POST:

{
    "sesKey": "5a15852c564933807bbd36da58071063",

}


JSON Output Fields on Success:

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


JSON Response data on Success

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

Example success:

{
    "success": true
    "data": {
        "id": 1,
        "name": "test's new project",
        "status": "open",
        "created": "2011-10-14 12:13:13",
        "closed": null,
        "created_by": "Kinesis Tester"
    }
}

8:  Reminder

8.1:  integration.reminder.create

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


JSON Input Fields:

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

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:

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

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

Example success:

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

9:  Sample

9.1:  integration.sample.create

Create a sample from panelist identifiers.


JSON Input Fields:

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

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:

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

Example success:

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

9.2:  integration.sample.update

Update a sample with appended data

JSON Input Fields:

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


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
}
  • Was this article helpful?