Skip to main content

Kinesis Support

All the topics, resources needed for Kinesis.

FocusVision Knowledge Base

Panel Integration REST API 4.6.0

Auth

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

Example failure:

{
    "success": false,
    "error": "Session has expired.  You must start a new session." 
    "errno": 30100
}

Possible Failures:

Message Code Error Description
Login credentials invalid. Make sure the username and password are correct, and that the user is assigned the "Web Services Only" role. 20101 Username incorrect The supplied username is not found.
Login credentials invalid. Make sure the username and password are correct, and that the user is assigned the "Web Services Only" role. 20101 Password incorrect The password entered is not correct.
Login credentials invalid. Make sure the username and password are correct, and that the user is assigned the "Web Services Only" role. 20101 User invalid The supplied user is not “Web Services Only” role.
You must supply a valid username and password 20102 Missing username or password The username and/or password supplied are/is empty.
We’re sorry, but access to these web services is not allowed from your IP address. 30400 IP invalid The IP address is not allowed access.
Too many failed login attempts. Account locked. 30400 IP locked There have been 5 failed attempts from this IP address within the past 15 minutes.

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
}

Example failure:

{
    "success": false,
    "error": "Session has expired.  You must start a new session." 
    "errno": 30100
}

Possible Failures:

Message Code Error Description
Session has expired. You must start a new session. 30100 Session expired Session has expired.
sessionkey not found 30200 Session not found Session is not found for supplied session key.
userid for sessionkey not found 30200 Session not found User ID not found for supplied session key.
sessionkey is invalid 30300 Session invalid Session key is not in correct format.
Panel ID not found. Call setPanel() to choose a different panel. 40001 Panel not found The supplied panel ID is not found.

Campaign

integration.campaign.create

Schedule campaign for the panelists. Campaigns are typically used to send email invitations to the panelists.

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


JSON Input messages array:

Parameter Description Default Required
subject Subject text.   yes
content Message content (must be CAN-SPAM compliant http://www.ftc.gov/spam/)   yes
locale The corresponding locale ID for this message or an array of locales. 1 no

Example POST:

{
    sessKey: "5a15852c564933807bbd36da58071063",
    settings: {
        name: "Test Campaign",
        startTime: "2011-12-22 17:50:00",
        type: "html"
    },
    messages: [
        {
            subject: "Test Email",
            content: "This is the Test Email.",
            locale: [
                1,
                2
            ]
        },
        {
            subject: "Test Email 2",
            content: "This is the Second Test Email."
            locale: 3
        }
    ],
    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
    }
}

Example failure:

{
    "success": false,
    "error": "Session has expired.  You must start a new session." 
    "errno": 30100
}

Possible Failures:

Message Code Error Description
The "campaignData" parameter is of an unexpected type. Please use an appropriate object or array, as described in the documentation. 20102 Settings invalid The supplied settings are not an array.
The following required schedule properties are missing: (properties) 20102 Settings parameters not found The supplied settings array does not contain all required parameters: name, type, startTime.
(Campaign) is not a valid invitation type. Choose one of (SMS, html). 20102 Settings type invalid. The supplied settings type is not valid. Type must be “SMS” or “html”.
The "message" parameter is of an unexpected type. Please use an array, as described in the documentation. 20103 Messages invalid The supplied messages are not an array.
The "message" parameter cannot be empty. Please use an array, as described in the documentation. 20103 Empty messages The supplied messages array is empty.
The following required invitation properties are missing: (properties) 20103 Messages parameters not found The supplied messages array does not contain all required parameters: subject, content.
You have more than one message defined for locale Message locales must be unique. 20103 Messages locale duplicate One or more of the supplied messages has the same locale.
The following sample ids were not found for project 20104 Sample IDs not found Sample with supplied sample IDs are not found for selected project.
The "sampleIds" parameter is of an unexpected type. Please use an array, as described in the documentation. 20104 Sample IDs invalid The supplied sample IDs are not an array.
The "sampleIds" array is empty. The array must contain at least one valid sample id. 20204 Empty Sample IDs The supplied sample IDs array is empty.
Session has expired. You must start a new session. 30100 Session expired Session has expired.
sessionkey not found 30200 Session not found Session is not found for supplied session key.
userid for sessionkey not found 30200 Session not found User ID not found for supplied session key.
sessionkey is invalid 30300 Session invalid Session key is not in correct format.
You must select a panel before you can use this method. 40001 Panel not found A panel needs to be selected before creating a campaign.
You must select a project before you can use this method. 40002 Project not found A project needs to be selected before creating a campaign.

integration.campaign.createWithCommunity

This call works similarly to integration.campaign.create, but it also allows for creation of links that will show up in the community.
It is available as of version 4.6.0.1854 (released on July 26th 2016).

JSON Input Fields:

Parameter Type Description Required
sesKey string A valid login hash. yes
settings array An array of settings (name => value) yes
communityMessages array An array of community messages. These values are displayed to community users and are always required, even when the campaign is not published to any community. yes
messages array An array of invitation messages (email and/or SMS). Not required when publishing to the community only. yes
sampleids array An array of sample IDs (obtained via integration.sample.create) yes


Settings array

Parameter Description Type Default Required
name Name of the campaign. string   yes
startTime When to start sending out invitations. (Format: YYYY-MM-DD hh:mm:ss) string   yes
endTime When this campaign expires. (Format: YYYY-MM-DD hh:mm:ss) string   no
messageTypes Message types used by campaign. An array consisting of email and/or (if available) sms, or an empty array for community-only campaigns. array [email] no
description The description of the campaign. string   no
purpose The purpose of the campaign. (Acceptable values: invitation, profiler) string invitation no
includePortal Whether or not to display this invitation to portal members (Acceptable values: yes, no, exclusively). string yes no
pointsCompleted Amount of points a panelist will receive upon completion. integer (setting in project) no
pointsProfile Amount of points a panelist will receive when profile terminating. integer (setting in project) no
pointsQuota Amount of points a panelist will receive when quota terminating. integer (setting in project) no
maxParticipation Amount of times a panelist is allowed to participate. integer (setting in project) no
pointsTermination Reward panelist every time he participates or only the first time. (Acceptable values: every, first) string every no


Community messages array

The community messages array must contain individual arrays in the format listed below.
The locale parameter is an array, because multiple languages are allowed to share the same subject/content.
Subject and content are returned as subject and body by the integration.surveys.available call.

Parameter Description Type Required
communitySubject Community subject text string yes
communityContent Community message content string yes
locale Array of locale ids array yes


Messages array

The messages array must contain individual arrays in the format listed below.
The locale parameter is an array, because multiple languages are allowed to share the same subject/content.
The messages array must be empty or omitted when creating a community-only campaign with settings.includePortal = exclusively and settings.messageTypes = [].
Keep in mind that the message content is going to be incorporated in the selected email template for campaigns.

Parameter Description Type Required
subject Email subject text string no, yes when settings.messageTypes contains email
content Email message content string no, yes when settings.messageTypes contains email
sms SMS message content (if available) string no, yes when settings.messageTypes contains sms
locale Array of locale ids array yes


Example POST (community-only campaign)

{
    sessKey: "5a15852c564933807bbd36da58071063",
    settings: {
        name: "Home improvement Campaign",
        startTime: "2016-07-26 17:50:00",
        messageTypes: [],
        includePortal: "exclusively",
        pointsCompleted: 100
    },
    communityMessages: [
        {
            communitySubject: "Home improvement survey",
            communityContent: "Receive up to 100 points for taking this survey!",
            locale: [
                1
            ]
        },
        {
            communitySubject: "Encuesta de mejoras para el hogar",
            communityContent: "Recibe hasta 100 puntos por completar esta encuesta!",
            locale: [
                2
            ]
        }
    ],
        messages: [],
    sampleids: [
        42
    ]
}

Example POST (email-only campaign)

{
    sessKey: "5a15852c564933807bbd36da58071063",
    settings: {
        name: "Pre-owned car Campaign",
        startTime: "2016-07-26 18:50:00",
        includePortal: "no"
    },
    communityMessage: [
        {
            communitySubject: "Pre-owned car buyer's survey",
            communityContent: "Tell us about your recent car buying experience",
            locale: [
                1,
                2
            ]
        }
    ],
    messages: [
        {
            subject: "Pre-owned car buyer's survey",
            content: "Today we have an exciting survey opportunity for you!<br>It's all about your recent car buying experience at: Joe's Premium Pre-Owned Automotive!",
            locale: [
                1,
                2
            ]
        }
    ],
    sampleids: [
        43
    ]
}

Response Data:

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


Example success:

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

Example failure:

{
    "success": false,
    "error": "Session has expired.  You must start a new session." 
    "errno": 30100
}

Possible Failures:

Message Code Error Description
Name invalid 0 Settings name invalid The supplied settings name is not a string between 0-100 characters.
Description invalid 0 Settings description invalid The supplied settings description is not a string between 0-65535 characters.
Start time invalid 0 Settings start time invalid The supplied settings start time is not a string or is formatted incorrectly. Format: YYYY-MM-DD hh:mm:ss
End time invalid 0 Settings end time invalid The supplied settings end time is not a string or is formatted incorrectly. Format: YYYY-MM-DD hh:mm:ss
Purpose invalid 0 Settings purpose invalid The supplied settings purpose is not a valid string. The settings purpose parameter must be “invitation” or “profile”.
Include portal invalid 0 Settings include portal invalid The supplied include portal is not a valid string. The settings include portal parameter must be “invitation” or “profile”.
Points completed invalid 0 Settings points completed The supplied settings points completed is not an integer.
Points profile invalid 0 Settings points profile invalid The supplied settings points profile is not an integer.
Points quota invalid 0 Settings points quota invalid The supplied settings points quota is not an integer.
Max participation invalid 0 Settings max participation invalid The supplied settings max participation is not an integer.
Points termination invalid 0 Settings points termination invalid The supplied settings points termination is not a valid string. The settings points termination parameter must be “first” or “every”.
Message types invalid 0 Settings message types invalid The supplied settings message types is not an array.
Message type invalid 0 Settings message type invalid The supplied settings message type is not a valid string. The settings message type parameter must be “sms” or “email”.
Message types can not be set for community only campaign 0 Message invalid Settings message types cannot be supplied for community only campaigns.
Malformed community message array 0 Community messages invalid The supplied community messages is not an array.
Invalid community message subject 0 Community message subject invalid One or more of the supplied community messages subject is not a string.
Invalid community message content 0 Community message content invalid One or more of the supplied community messages content is not a string.
Subject out of bounds 0 Community message subject invalid One or more of the supplied community messages subject is not a string between 1-65535 characters.
Content out of bounds 0 Community message content invalid One or more of the supplied community messages content is not a string between 1-65535 characters.
Invalid locale array 0 Community messages/Messages locale invalid One or more of the supplied community messages or messages locale is not an array.
Invalid locale 0 Community messages/Messages locale invalid One or more of the supplied community messages or messages locale is not a valid locale for the panel.
Missing locales 0 Community messages/Messages invalid The amount of community messages or messages are not equal to the amount of locales for panel.
Malformed message array 0 Messages invalid The supplied messages is not an array.
Invalid message subject 0 Message subject invalid One or more of the supplied messages subject is not a string.
Invalid message content 0 Message content invalid One or more of the supplied messages content is not a string.
Invalid sms content 0 Message sms content invalid One or more of the supplied messages sms content is not a string.
No SMS gateway provider available 0 SMS gateway provider not found SMS messaging is not set up for this panel.
Can not use messages for community exclusive campaign 0 Messages invalid The messages parameter cannot be specified when the supplied settings include portal is set to “exclusively”.
Invalid number of samples provided 0 Empty sample IDs The supplied sample IDs is empty.
Invalid sample provided 0 Sample IDs not found Sample with supplied sample ID is not found.
Session has expired. You must start a new session. 30100 Session expired Session has expired.
sessionkey not found 30200 Session not found Session is not found for supplied session key.
userid for sessionkey not found 30200 Session not found User ID not found for supplied session key.
sessionkey is invalid 30300 Session invalid Session key is not in correct format.
You must select a panel before you can use this method. 40001 Panel not found A panel needs to be selected before creating a campaign.
You must select a project before you can use this method. 40002 Project not found A project needs to be selected before creating a campaign.

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

Example failure:

{
    "success": false,
    "error": "Session has expired.  You must start a new session." 
    "errno": 30100
}

Possible Failures:

Message Code Error Description
Session has expired. You must start a new session. 30100 Session expired Session has expired.
sessionkey not found 30200 Session not found Session is not found for supplied session key.
userid for sessionkey not found 30200 Session not found User ID not found for supplied session key.
sessionkey is invalid 30300 Session invalid Session key is not in correct format.
You must select a panel before you can use this method. 40001 Panel not found A panel needs to be selected before creating a campaign.
You must select a project before you can use this method. 40002 Project not found A project needs to be selected before creating a campaign.

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

Example failure:

{
    "success": false,
    "error": "Session has expired.  You must start a new session." 
    "errno": 30100
}

Possible Failures:

Message Code Error Description
Campaign ID must be numeric 0 Campaign ID invalid The supplied campaign ID is not numeric.
Campaign ID not found or campaign is not part of selected project. 0 Campaign ID not found Campaign with supplied campaign ID is not found.
Session has expired. You must start a new session. 30100 Session expired Session has expired.
sessionkey not found 30200 Session not found Session is not found for supplied session key.
userid for sessionkey not found 30200 Session not found User ID not found for supplied session key.
sessionkey is invalid 30300 Session invalid Session key is not in correct format.
You must select a panel before you can use this method. 40001 Panel not found A panel needs to be selected before creating a campaign.
You must select a project before you can use this method. 40002 Project not found A project needs to be selected before creating a campaign.

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

Example failure:

{
    "success": false,
    "error": "Session has expired.  You must start a new session." 
    "errno": 30100
}

Possible Failures:

Message Code Error Description
The supplied campaign id is invalid. 20102 Campaign ID invalid The supplied campaign ID is not numeric.
No data found for Campaign ID: (campaign ID) 20302 Campaign ID not found Campaign with supplied campaign ID is not found.
Session has expired. You must start a new session. 30100 Session expired Session has expired.
sessionkey not found 30200 Session not found Session is not found for supplied session key.
userid for sessionkey not found 30200 Session not found User ID not found for supplied session key.
sessionkey is invalid 30300 Session invalid Session key is not in correct format.
You must select a panel before you can use this method. 40001 Panel not found A panel needs to be selected before creating a campaign.
You must select a project before you can use this method. 40002 Project not found A project needs to be selected before creating a campaign.

Category

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": []
}

Example failure:

{
    "success": false,
    "error": "Session has expired.  You must start a new session." 
    "errno": 30100
}

Possible Failures:

Message Code Error Description
Session has expired. You must start a new session. 30100 Session expired Session has expired.
sessionkey not found 30200 Session not found Session is not found for supplied session key.
userid for sessionkey not found 30200 Session not found User ID not found for supplied session key.
sessionkey is invalid 30300 Session invalid Session key is not in correct format.
You must select a panel before you can use this method. 40001 Panel not found A panel needs to be selected before creating a campaign.

Community

integration.community.createSession

Creates an active session using the panelist username/email address 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": ""
    }
}

Example failure:

{
    "success": false,
    "error": "Session has expired.  You must start a new session." 
    "errno": 30100
}

Possible Failures:

Message Code Error Description
The supplied email is invalid 20102 Email invalid or not found The supplied email address is not valid or a panelist with supplied email address is not found.
Session has expired. You must start a new session. 30100 Session expired Session has expired.
sessionkey not found 30200 Session not found Session is not found for supplied session key.
userid for sessionkey not found 30200 Session not found User ID not found for supplied session key.
sessionkey is invalid 30300 Session invalid Session key is not in correct format.
You must select a panel before you can use this method. 40001 Panel not found A panel needs to be selected before creating a campaign.

integration.community.createSessionWithPID

Creates an active session using the panelist pid (panelist id) 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
pid number The pid (panelist id) of the panelist the session is created for. yes

Example POST:

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


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

Example failure:

{
    "success": false,
    "error": "Session has expired.  You must start a new session." 
    "errno": 30100
}

Possible Failures:

Message Code Error Description
The supplied pid is invalid 20102 PID invalid or not found The supplied panelist ID is not numeric or a panelist with supplied panelist ID is not found.
Session has expired. You must start a new session. 30100 Session expired Session has expired.
sessionkey not found 30200 Session not found Session is not found for supplied session key.
userid for sessionkey not found 30200 Session not found User ID not found for supplied session key.
sessionkey is invalid 30300 Session invalid Session key is not in correct format.
You must select a panel before you can use this method. 40001 Panel not found A panel needs to be selected before creating a campaign.

integration.community.createSessionWithIdentifier

Creates an active session using the panelist identifier 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 identifier of the panelist the session is created for. yes

Example POST:

{
    "sesKey": "5a15852c564933807bbd36da58071063",
    "identifier": "K_a1b2c3d4e5"
}


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

Example failure:

{
    "success": false,
    "error": "Session has expired.  You must start a new session." 
    "errno": 30100
}

Possible Failures:

Message Code Error Description
The supplied identifier is invalid 20102 Identifier invalid or not found The supplied identifier is not a string or a Panelist with supplied identifier (username) is not found.
Session has expired. You must start a new session. 30100 Session expired Session has expired.
sessionkey not found 30200 Session not found Session is not found for supplied session key.
userid for sessionkey not found 30200 Session not found User ID not found for supplied session key.
sessionkey is invalid 30300 Session invalid Session key is not in correct format.
You must select a panel before you can use this method. 40001 Panel not found A panel needs to be selected before creating a campaign.

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 pid Integer Panelist ID.
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>",
    }
}

Example failure:

{
    "success": false,
    "error": "Session has expired.  You must start a new session." 
    "errno": 30100
}

Possible Failures:

Message Code Error Description
Unable to successfully select database (database name)! 0 Internal error The supplied encrypted string includes a panel ID that cannot be found.
The supplied data could not be decrypted 20102 Encrypted string invalid The supplied encrypted string is not a valid or it is empty.
The decrypted data could not be verified 20102 Encrypted string invalid The supplied encrypted string is not a valid.
Session has expired. You must start a new session. 30100 Session expired Session has expired.
sessionkey not found 30200 Session not found Session is not found for supplied session key.
userid for sessionkey not found 30200 Session not found User ID not found for supplied session key.
sessionkey is invalid 30300 Session invalid Session key is not in correct format.

integration.community.isUniqueOpenend

This method checks uniqueness of open end data point supplied by searching through the panel database. A datapoint label and a value must be provided to run the check.

JSON Input Fields:

Parameter Type Description Required Since
sesKey string A valid login hash. yes 4.5.2
label string The data point label yes 4.5.2
value string The data point value to check for yes 4.5.2

Example POST:

{
    "sesKey": "5a15852c564933807bbd36da58071063",
    "label" : "Qfirstname",
    "value" : "John"
}

Response Data:

Parameter Type Description Since
success boolean true Creation of the session was successful. 4.5.2
unique boolean True if value was not found, false if the value was found one or more times 4.5.2

Example success:

{
    "success": true,
    "unique" : false
}

Example failure:

{
    "success": false,
    "error": "Session has expired.  You must start a new session." 
    "errno": 30100
}

Possible Failures:

Message Code Error Description
Invalid label - data point not found or not open-end. 20102 Label invalid or not found Data point with supplied label is not found or supplied label is invalid.
Supplied value is invalid. 20103 Value invalid The supplied value is not a string.
Session has expired. You must start a new session. 30100 Session expired Session has expired.
sessionkey not found 30200 Session not found Session is not found for supplied session key.
userid for sessionkey not found 30200 Session not found User ID not found for supplied session key.
sessionkey is invalid 30300 Session invalid Session key is not in correct format.
You must select a panel before you can use this method. 40001 Panel not found A panel needs to be selected before creating a campaign.

Datapoint

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. (Valid values include: "radio", "checkbox", "openend", "number" and "float") - "number" and "float" were introduced in 4.6.0 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." no

Example POST - Openend:

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

}

Example POST - Checkbox:

{
    "sesKey": "5a15852c564933807bbd36da58071063",
    "settings": {
        "label": "Q4",
        "qtext": "This is datapoint four",
        "type": "checkbox",
        "choices": [
            {
                "choiceid": 1,
                "name": "Choice one"
            },
            {
                "choiceid": 2,
                "name": "Choice two"
            }
        ]
    }

}

Example success:

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

Example failure:

{
    "success": false,
    "error": "Session has expired.  You must start a new session." 
    "errno": 30100
}

Possible Failures:

Message Code Error Description
Datapoint label (datapoint label) is already being used! 0 Settings label invalid The supplied settings label is used for the selected panel.
Datapoint type (datapoint type) is invalid! 0 Settings type invalid The supplied settings type is not one of the predefined types: “openend”, “checkbox”, “date”, “radio”, “number”, “float”.
Choice is missing 'choiceid'!" 0 Empty settings choices The supplied settings choices are empty.
The question type: (datapoint type) cannot be added without choices! 0 Settings choices not found The supplied settings choices was empty or not provided. The question type requires choices to be created.
Session has expired. You must start a new session. 30100 Session expired Session has expired.
sessionkey not found 30200 Session not found Session is not found for supplied session key.
userid for sessionkey not found 30200 Session not found User ID not found for supplied session key.
sessionkey is invalid 30300 Session invalid Session key is not in correct format.
You must select a panel before you can use this method. 40001 Panel not found A panel needs to be selected before creating a campaign.

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
}

Example failure:

{
    "success": false,
    "error": "Session has expired.  You must start a new session." 
    "errno": 30100
}

Possible Failures:

Message Code Error Description
Invalid data ID 0 Datapoint ID invalid The supplied datapoint ID is not numeric.
Datapoint object doesn't contain dataid! 0 Datapoint ID not found Datapoint with supplied datapoint ID is not found.
Session has expired. You must start a new session. 30100 Session expired Session has expired.
sessionkey not found 30200 Session not found Session is not found for supplied session key.
userid for sessionkey not found 30200 Session not found User ID not found for supplied session key.
sessionkey is invalid 30300 Session invalid Session key is not in correct format.
You must select a panel before you can use this method. 40001 Panel not found A panel needs to be selected before creating a campaign.

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

Example failure:

{
    "success": false,
    "error": "Session has expired.  You must start a new session." 
    "errno": 30100
}

Possible Failures:

Message Code Error Description
Supplied datapoint label: (datapoint label) contains invalid characters! 0 Label invalid The supplied label is empty or contains invalid characters.
The supplied datapoint label: (datapoint label) is unknown. 0 Datapoint not found Datapoint with supplied label is not found.
Session has expired. You must start a new session. 30100 Session expired Session has expired.
sessionkey not found 30200 Session not found Session is not found for supplied session key.
userid for sessionkey not found 30200 Session not found User ID not found for supplied session key.
sessionkey is invalid 30300 Session invalid Session key is not in correct format.
You must select a panel before you can use this method. 40001 Panel not found A panel needs to be selected before creating a campaign.

Panel

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
}

Example failure:

{
    "success": false,
    "error": "Session has expired.  You must start a new session." 
    "errno": 30100
}

Possible Failures:

Message Code Error Description
Invalid panel id (panel ID) 20102 Panel ID invalid The supplied panel ID is not numeric.
Panel (panel ID) not found 20302 Panel not found Panel with supplied panel ID is not found.
Session has expired. You must start a new session. 30100 Session expired Session has expired.
sessionkey not found 30200 Session not found Session is not found for supplied session key.
userid for sessionkey not found 30200 Session not found User ID not found for supplied session key.
sessionkey is invalid 30300 Session invalid Session key is not in correct format.

Panelist

integration.panelist.create

Create a panelist with accompanying data

NOTE: In most cases, portal.email.sendOptInConfirmation will need to be called after panelist is created successfully.


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

Example failure:

{
    "success": false,
    "error": "Session has expired.  You must start a new session." 
    "errno": 30100
}

Possible Failures:

Message Code Error Description
Supplied choice is invalid 0 Settings checkbox answer invalid The supplied checkbox answer is not a numeric or string integers separated by commas (“1,2,3”).
Supplied choice(answer) is invalid for data point (datapoint label). The value must be an unsigned integer or NULL. 0 Settings radio answer invalid The supplied settings radio answer is not numeric.
Invalid choice(answer) for data point (datapoint label). The value must be either NULL or an unsigned integer between (datapoint choice min) and (datapoint choice max). 0 Settings radio/checkbox answer invalid The supplied radio or checkbox answer is not in choice range.
Unknown datapoint label (label). 20000 Settings label not found One of the supplied settings labels is not found for any datapoints.
The email address you supplied is already in use. You may be registered for this panel under a different login name. 20000 Settings email duplicate The supplied email address is used by another panelist in the panel.
The identifier you supplied is already in use. 20000 Settings identifier duplicate The supplied identifier is used by another panelist in the panel.
No answer data supplied! 20000 Settings invalid The supplied settings is empty.
The supplied value for label 'subscribed' is invalid 20000 Settings subscribed invalid The subscribed is invalid. Subscribed can only be set to “yes” or “no”.
The supplied date (answer) was invalid for (datapoint label) (date) 20000 Settings date answer invalid The supplied date answer was not in valid date format (YYYY-MM-DD).
The data type (answer type) is not valid for (datapoint label) (openend) 20000 Settings openend answer invalid The supplied openend answer is not a string.
Unknown or bad timezone 20000 Settings timezone invalid The supplied timezone is not valid timezone.
Malformed answer data received 20102 Settings invalid The supplied settings is not in valid format. Each datapiont within settings needs to contain a "label" and an "answer".
Session has expired. You must start a new session. 30100 Session expired Session has expired.
sessionkey not found 30200 Session not found Session is not found for supplied session key.
userid for sessionkey not found 30200 Session not found User ID not found for supplied session key.
sessionkey is invalid 30300 Session invalid Session key is not in correct format.
You must select a panel before you can use this method. 40001 Panel not found A panel needs to be selected before creating a campaign.
The supplied email address is invalid 40006 Settings email invalid The supplied email is not a valid email address.

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.

NOTE: It is ALWAYS recommended to specify “indexType” when making this call. If "IndexType" is not specified and the panel allows numeric identifiers for panelists, this call could not find the panelist or find an incorrect panelist.

JSON Input Fields:

Parameter Type Description Required Since
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  
indexType string The type of index being used (Possible values: "identifier", "pid") no 4.5.3

Example POSTs:

{
    sesKey: "5a15852c564933807bbd36da58071063",
    index: "34359",
    indexType: "identifier"
}
{
    sesKey: "5a15852c564933807bbd36da58071063",
    index: "34359",
    datapoints: [
        "Q1",
        "Q2",
        "Q3"
    ]
    indexType: "identifier"
}

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

Example failure:

{
    "success": false,
    "error": "Session has expired.  You must start a new session." 
    "errno": 30100
}

Possible Failures:

Message Code Error Description
Invalid datapoint value(s): (datapoints) 20303 Datapoints invalid The supplied datapoints are not valid datapoint labels or panelist fields.
Invalid index type 20100 Index type invalid The supplied index type is invalid. Index type can only be set to “pid” or “identifier”.
Panelist Id is invalid 20102 Panelist ID invalid The supplied panelist ID is not numeric.
Panelist not found 20203 Panelist not found Panelist with supplied identifier is not found.
Session has expired. You must start a new session. 30100 Session expired Session has expired.
sessionkey not found 30200 Session not found Session is not found for supplied session key.
userid for sessionkey not found 30200 Session not found User ID not found for supplied session key.
sessionkey is invalid 30300 Session invalid Session key is not in correct format.
You must select a panel before you can use this method. 40001 Panel not found A panel needs to be selected before creating a campaign.

 


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"
        },
        {
            "label": "Qopenend",
            "answer": "Test"
        },
        {
            "label": "Qradio",
            "answer": "2"
        },
        {
            "label": "Qcheckbox",
            "answer": "3,4,5"
        }
    ]
}

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
}

Example failure:

{
    "success": false,
    "error": "Session has expired.  You must start a new session." 
    "errno": 30100
}

Possible Failures:

Message Code Error Description
An identifier or email must be provided in order to update a panelist. 0 Identifier/Email missing An identifier or email address needs to be supplied to find the panelist.
Supplied choice is invalid 0 Settings checkbox answer invalid The supplied checkbox answer is not a numeric or string integers separated by commas (“1,2,3”).
Supplied choice(answer) is invalid for data point (datapoint label). The value must be an unsigned integer or NULL. 0 Settings radio answer invalid The supplied settings radio answer is not numeric.
Invalid choice(answer) for data point (datapoint label). The value must be either NULL or an unsigned integer between (datapoint choice min) and (datapoint choice max). 0 Settings radio/checkbox answer invalid The supplied radio or checkbox answer is not in choice range.
Unknown datapoint label (label). 20000 Settings label not found One of the supplied settings labels is not found for any datapoints.
The supplied value for label 'subscribed' is invalid 20000 Settings subscribed invalid The subscribed is invalid. Subscribed can only be set to “yes” or “no”.
The supplied date (answer) was invalid for (datapoint label) (date) 20000 Settings date answer invalid The supplied date answer was not in valid date format (YYYY-MM-DD).
The data type (answer type) is not valid for (datapoint label) (openend) 20000 Settings openend answer invalid The supplied openend answer is not a string.
Unknown or bad timezone 20000 Settings timezone invalid The supplied timezone is not valid timezone.
Panelist datapoint data is malformed! 20102 Settings invalid The supplied settings array does not contain datapoint array(s) with “label” and/or “answer”.
Answer data is in invalid format! 20102 Settings invalid The supplied settings array contains datapoint array(s) with arrays or objects for “answer”.
Session has expired. You must start a new session. 30100 Session expired Session has expired.
sessionkey not found 30200 Session not found Session is not found for supplied session key.
userid for sessionkey not found 30200 Session not found User ID not found for supplied session key.
sessionkey is invalid 30300 Session invalid Session key is not in correct format.
You must select a panel before you can use this method. 40001 Panel not found A panel needs to be selected before creating a campaign.
Invalid email! User not found. 40010 Panelist not found Panelist with supplied email address is not found.
Invalid identifier! User not found. 40010 Panelist not found Panelist with supplied identifier is not found.

integration.panelist.rewardPointsAdd

Add points to the panelist's account.

NOTE: It is ALWAYS recommended to specify “indexType” when making this call. If "IndexType" is not specified and the panel allows numeric identifiers for panelists, this call could not find the panelist or award points to an incorrect panelist.
 

JSON Input Fields:

Parameter Type Description Required Since
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  
indexType string The type of index being used (Possible values: "identifier", "pid") no 4.5.3


Example POST:

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

Example success:

{
     "success": true
}

Example failure:

{
    "success": false,
    "error": "Session has expired.  You must start a new session." 
    "errno": 30100
}

Possible Failures:

Message Code Error Description
Invalid index type 20100 Index type invalid The supplied index type is invalid. Index type can only be set to “pid” or “identifier”.
Panelist Id is invalid 20102 Panelist ID invalid The supplied panelist ID is not numeric.
Panelist not found 20203 Panelist not found Panelist with supplied identifier is not found.
Number of points to add must be positive 20203 Points invalid The supplied points value is not greater than 0.
Session has expired. You must start a new session. 30100 Session expired Session has expired.
sessionkey not found 30200 Session not found Session is not found for supplied session key.
userid for sessionkey not found 30200 Session not found User ID not found for supplied session key.
sessionkey is invalid 30300 Session invalid Session key is not in correct format.
You must select a panel before you can use this method. 40001 Panel not found A panel needs to be selected before creating a campaign.
No data found for Panelist ID: (panelist ID) 40010 Panelist not found Panelist with supplied panelist ID is not found.

integration.panelist.rewardPointsDeduct

Deduct points from the panelist's account.

NOTE: It is ALWAYS recommended to specify “indexType” when making this call. If "IndexType" is not specified and the panel allows numeric identifiers for panelists, this call could not find the panelist or deduct points from an incorrect panelist.
 

JSON Input Fields:

Parameter Type Description Required Since
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  
indexType string The type of index being used (Possible values: "identifier", "pid") no 4.5.3


Example POST:

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

Example success:

{
     "success": true
}

Example failure:

{
    "success": false,
    "error": "Session has expired.  You must start a new session." 
    "errno": 30100
}

Possible Failures:

Message Code Error Description
Invalid index type 20100 Index type invalid The supplied index type is invalid. Index type can only be set to “pid” or “identifier”.
Panelist Id is invalid 20102 Panelist ID invalid The supplied panelist ID is not numeric.
Panelist not found 20203 Panelist not found Panelist with supplied identifier is not found.
Number of points to deduct must be negative 20203 Points invalid The supplied points value is not less than 0.
Session has expired. You must start a new session. 30100 Session expired Session has expired.
sessionkey not found 30200 Session not found Session is not found for supplied session key.
userid for sessionkey not found 30200 Session not found User ID not found for supplied session key.
sessionkey is invalid 30300 Session invalid Session key is not in correct format.
You must select a panel before you can use this method. 40001 Panel not found A panel needs to be selected before creating a campaign.
No data found for Panelist ID: (panelist ID) 40010 Panelist not found Panelist with supplied panelist ID is not found.

integration.panelist.rewardPointsBalance

Get a panelist's current reward point balance

NOTE: It is ALWAYS recommended to specify “indexType” when making this call. If "IndexType" is not specified and the panel allows numeric identifiers for panelists, this call could not find the panelist or return points from an incorrect panelist.

JSON Input Fields:

Parameter Type Description Required Since
sesKey string A valid login hash. yes  
index string Panelist identifier or PID yes  
indexType string The type of index being used (Possible values: "identifier", "pid") no 4.5.3


Example POST:

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

Example success:

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

Example failure:

{
    "success": false,
    "error": "Session has expired.  You must start a new session." 
    "errno": 30100
}

Possible Failures:

Message Code Error Description
Invalid index type 20100 Index type invalid The supplied index type is invalid. Index type can only be set to “pid” or “identifier”.
Panelist Id is invalid 20102 Panelist ID invalid The supplied panelist ID is not numeric.
Panelist not found 20203 Panelist not found Panelist with supplied identifier is not found.
Session has expired. You must start a new session. 30100 Session expired Session has expired.
sessionkey not found 30200 Session not found Session is not found for supplied session key.
userid for sessionkey not found 30200 Session not found User ID not found for supplied session key.
sessionkey is invalid 30300 Session invalid Session key is not in correct format.
You must select a panel before you can use this method. 40001 Panel not found A panel needs to be selected before creating a campaign.

integration.panelist.contactFrequenciesGet

Gets the currently set panelist contact frequencies.

NOTE: It is ALWAYS recommended to specify “indexType” when making this call. If "IndexType" is not specified and the panel allows numeric identifiers for panelists, this call could not find the panelist or returns information for an incorrect panelist.


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

JSON Input Fields:

Parameter Type Description Required Since
seskey string A valid login hash. yes  
index string Panelist identifier or PID yes  
indexType string The type of index being used (Possible values: "identifier", "pid") no 4.5.3

Example POST:

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


JSON Output Fields on Success:

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

Example success:

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

JSON Output Fields on Failure:

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

Example success - no record:

{
    success: false,
    error: 'Panelist not found',
    errno: 20203
}

Example failure:

{
    "success": false,
    "error": "Session has expired.  You must start a new session." 
    "errno": 30100
}

Possible Failures:

Message Code Error Description
Invalid index type 20100 Index type invalid The supplied index type is invalid. Index type can only be set to “pid” or “identifier”.
Panelist Id is invalid 20102 Panelist ID invalid The supplied panelist ID is not numeric.
Panelist not found 20203 Panelist not found Panelist with supplied identifier is not found.
Session has expired. You must start a new session. 30100 Session expired Session has expired.
sessionkey not found 30200 Session not found Session is not found for supplied session key.
userid for sessionkey not found 30200 Session not found User ID not found for supplied session key.
sessionkey is invalid 30300 Session invalid Session key is not in correct format.
You must select a panel before you can use this method. 40001 Panel not found A panel needs to be selected before creating a campaign.

integration.panelist.contactFrequenciesSet

Set the contact frequencies for a specified panelist

NOTE: It is ALWAYS recommended to specify “indexType” when making this call. If "IndexType" is not specified and the panel allows numeric identifiers for panelists, this call could not find the panelist or sets information for an incorrect panelist.

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

 

JSON Input Fields:

Parameter Type Description Required Since
seskey string A valid login hash. yes  
index string Panelist identifier or PID. yes  
maxMessages int or NULL Set the number of messages a panelist wants to receive per time frame. A value of NULL means unlimited. yes  
timeFrame string The time frame (week or day) in which we apply the maxMessages limit. yes  
SMSFrom string The time when it is acceptable to start sending SMS to the panelist. The time format is expected in 24 hour HH:MM:SS. If omitted, it will default to 09:00:00. no  
SMSTo string The time after which the panelist does not wish to receive SMS. The time format is expected in 24 hour HH:MM:SS. If omitted, it will default to 21:00:00. no  
indexType string The type of index being used (Possible values: "identifier", "pid") no 4.5.3

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

{
    seskey: "ce512c91",
    index: "34359",
    maxMessages: 5,
    timeFrame: "week",
    indexType: "identifier"
}

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

{
    seskey: "ce512c91",
    index: "34359",
    maxMessages: 1,
    timeFrame: "day",
    SMSFrom: "17:00:00",
    SMSTo: "20:00:00",
    indexType: "identifier"
}

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

{
    seskey: "ce512c91",
    index: "34359",
    maxMessages: null,
    timeFrame: "day",
    indexType: "identifier"
}


JSON Output Fields on Success:

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

Example success:

{
    success:      true,
}


JSON Output Fields on Failure:

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

Example failure:

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

Possible Failures:

Message Code Error Description
Time frame out of range, allowed values are 'day' and 'week' 0 Time frame invalid The time frame is invalid. The time frame can only be set to “day” or “week”.
Both time constraints must be supplied or none. 0 SMSFrom and SMSTo invalid Missing a time constraint: SMSFrom or SMSTo.
Invalid time stamp received 0 SMSFrom invalid The supplied SMSFrom needs to be a valid time (HH:MM:SS).
Invalid time stamp received 0 SMSTo invalid The supplied SMSTo needs to be a valid time (HH:MM:SS).
Invalid index type 20100 Index type invalid The supplied index type is invalid. Index type can only be set to “pid” or “identifier”.
Panelist Id is invalid 20102 Panelist ID invalid The supplied panelist ID is not numeric.
Panelist not found 20203 Panelist not found Panelist with supplied identifier is not found.
Session has expired. You must start a new session. 30100 Session expired Session has expired.
sessionkey not found 30200 Session not found Session is not found for supplied session key.
userid for sessionkey not found 30200 Session not found User ID not found for supplied session key.
sessionkey is invalid 30300 Session invalid Session key is not in correct format.
You must select a panel before you can use this method. 40001 Panel not found A panel needs to be selected before creating a campaign.

integration.panelist.findByDataPoint

Finds and returns a list of panelist identifiers based on a datapoint value.

JSON Input Fields:

Parameter Type Description Required
sesKey string A valid login hash yes
label string Datapoint label to filter by yes
answer mixed The answer (answer type depends on the requested datapoint type) yes

Note: Providing checkbox answers will find all panelists who selected the requested choices.

Querying for choices A and C on a datapoint that has choices A, B, C, D, E will return panelists who have A and C checked regardless of whether B, D or E were also checked.

Example POSTs:

Open-end Example:

{
"sesKey": "2565b78d2d00414fa2092ba1f89d6576",
"label": "Qfirstname",
"answer": "Jim"
}

Date Example:

{
"sesKey": "2565b78d2d00414fa2092ba1f89d6576",
"label": "Qbirthday",
"answer": "1965-01-15"
}

Radio Example:

{
"sesKey": "2565b78d2d00414fa2092ba1f89d6576",
"label": "Qgender",
"answer": 1
}

Checkbox Example:

{
"sesKey": "2565b78d2d00414fa2092ba1f89d6576",
"label": "Qfood",
"answer": [1,2,3]
}

JSON Response Data:

Parameter Description
identifiers Array of panelist identifiers that matched the criteria

Example success:

{
"success": true,
"identifiers": [
"K_ggwp76rx67",
"K_kjns874n38"
]
}

Example failure:

{
"success": false,
"error": "Datapoint not found"
"errno": 0
}

Possible Failures:

Message Code Error Description
Invalid datapoint label

0

Datapoint label invalid The label was invalid
Datapoint not found 0 Datapoint not found The datapoint was not found
Answer type mismatch 0 Answer invalid The answer data type was not suitable for the datapoint
Invalid date 0 Date answer invalid The date for a date datapoint is malformed
Invalid choice 0 Choice answer invalid The supplied choices for a radio/checkbox datapoint were invalid
Session has expired. You must start a new session. 0 Session expired Session has expired
sessionkey not found 30200 Session not found Session is not found for supplied session key
userid for sessionkey not found 30200 Session not found User ID not found for supplied session key
sessionkey is invalid 30300 Session invalid Session key is not in correct format
You must select a panel before you can use this method. 40001 Panel not found A panel needs to be selected before panelists can be queried

Project

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
}

Example failure:

{
    "success": false,
    "error": "Session has expired.  You must start a new session." 
    "errno": 30100
}

Possible Failures:

Message Code Error Description
Invalid project id (project ID) 20102 Project ID invalid The supplied project ID is not numeric.
Project (project ID) not found in panel (selected panel ID) 20302 Project ID not found Project with supplied project ID is not found in selected panel.
Session has expired. You must start a new session. 30100 Session expired Session has expired.
sessionkey not found 30200 Session not found Session is not found for supplied session key.
userid for sessionkey not found 30200 Session not found User ID not found for supplied session key.
sessionkey is invalid 30300 Session invalid Session key is not in correct format.
You must select a panel before you can use this method. 40001 Panel not found A panel needs to be selected before creating a campaign.

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

Example failure:

{
    "success": false,
    "error": "Session has expired.  You must start a new session." 
    "errno": 30100
}

Possible Failures:

Message Code Error Description
Invalid property (settings) 10000 Settings invalid The supplied settings array contains a key that is not valid for project settings.
defaultmaxparticipation (settings default max participation) must be numeric 10000 Settings default max participation invalid The supplied settings default max participation is not numeric.
defaultpointsquota (settings default points quota) must be numeric 10000 Settings default points quota invalid The supplied default points quota is not numeric.
defaultpointsprofile (settings default points profile) must be numeric 10000 Settings default points profile invalid The supplied default points profile is not numeric.
default points completed (settings default points completed) must be numeric 10000 Settings default points completed invalid The supplied default points completed is not numeric.
Invalid project name. Project name can not be empty. 10000 Empty settings name The supplied settings name is empty.
Invalid project name (settings name) length. Can not be longer than 100 characters. 10000 Settings name invalid The supplied settings name is more than 100 characters in length.
Project URL must be set before calling save 10000 Empty settings URL The supplied settings URL is empty.
clientid (settings client ID) must be a positive number or null 10000 Settings client ID invalid The supplied client ID is not numeric.
Invalid clientid (settings client ID) client does not exist 10000 Client not found Client with supplied client ID is not found.
URL (settings URL) is not a properly formatted URL 10000 Setting URL invalid The supplied settings URL is not a valid URL.
The survey URL does not contain the substitution parameter '[sesskey]' as a value. This parameter contains a session key, which is necessary for activity tracking. 10000 Settings URL invalid The supplied settings URL does not contain “sesskey” parameter. The URL must contain “sesskey” for activity tracking.
Invalid project description (settings description) length. Can not be longer than 65k characters 10000 Settings description invalid. The supplied settings description is more than 65536 characters in length.
Invalid secret hash salt (settings secret) can not be longer than 255 characters 10000 Settings secret invalid The supplied settings secret is more than 255 characters in length.
Invalid recencrypttype (settings receive encrypt type) value. Allowed values are: md5, none 10000 Settings receive encrypt type invalid The supplied settings receive encrypt type is not valid. Receive encrypt type can only be “md5” or “none”.
Invalid recencrypttype (settings termination encrypt type) value. Allowed values are: md5, none 10000 Settings termination encrypt type invalid The supplied settings termination encrypt type is not valid. Termination encrypt type can only be “md5” or “none”.
Invalid category id(category ID) 20102 Categories invalid The supplied categories contains one or more values that are not numeric.
Supplied category id(category ID) not found. 20103 Category not found One or more categories from supplied categories are not found.
The "project" parameter is of an unexpected type (settings type). Please use an appropriate object or array, as described in the documentation. 20102 Settings invalid The supplied settings is not an array.
Session has expired. You must start a new session. 30100 Session expired Session has expired.
sessionkey not found 30200 Session not found Session is not found for supplied session key.
userid for sessionkey not found 30200 Session not found User ID not found for supplied session key.
sessionkey is invalid 30300 Session invalid Session key is not in correct format.
You must select a panel before you can use this method. 40001 Panel not found A panel needs to be selected before creating a campaign.

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
}

Example failure:

{
    "success": false,
    "error": "Session has expired.  You must start a new session." 
    "errno": 30100
}

Possible Failures:

Message Code Error Description
The specified projectid does not exist 10000 Project ID not found Project with supplied project ID is not found in selected panel.
Project ID must be numeric! 20102 Project ID invalid The supplied project ID is not numeric.
Session has expired. You must start a new session. 30100 Session expired Session has expired.
sessionkey not found 30200 Session not found Session is not found for supplied session key.
userid for sessionkey not found 30200 Session not found User ID not found for supplied session key.
sessionkey is invalid 30300 Session invalid Session key is not in correct format.
You must select a panel before you can use this method. 40001 Panel not found A panel needs to be selected before creating a campaign.

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

Example failure:

{
    "success": false,
    "error": "Session has expired.  You must start a new session." 
    "errno": 30100
}

Possible Failures:

Message Code Error Description
Unknown type.(type) 0 Type invalid The specified type is not valid. The type can only be: “participation”, “statistics” or “allstatistics”.
Session has expired. You must start a new session. 30100 Session expired Session has expired.
sessionkey not found 30200 Session not found Session is not found for supplied session key.
userid for sessionkey not found 30200 Session not found User ID not found for supplied session key.
sessionkey is invalid 30300 Session invalid Session key is not in correct format.
You must select a panel before you can use this method. 40001 Panel not found A panel needs to be selected before creating a campaign.
You must select a project before you can use this method. 40002 Project not found A project needs to be selected before creating a campaign.

 


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

Example failure:

{
    "success": false,
    "error": "Session has expired.  You must start a new session." 
    "errno": 30100
}

Possible Failures:

Message Code Error Description
Unknown type.(type) 0 Type invalid The specified type is not valid. The type can only be: “participation”, “statistics” or “allstatistics”.
Session has expired. You must start a new session. 30100 Session expired Session has expired.
sessionkey not found 30200 Session not found Session is not found for supplied session key.
userid for sessionkey not found 30200 Session not found User ID not found for supplied session key.
sessionkey is invalid 30300 Session invalid Session key is not in correct format.
You must select a panel before you can use this method. 40001 Panel not found A panel needs to be selected before creating a campaign.
You must select a project before you can use this method. 40002 Project not found A project needs to be selected before creating a campaign.

 


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

Example failure:

{
    "success": false,
    "error": "Session has expired.  You must start a new session." 
    "errno": 30100
}

Possible Failures:

Message Code Error Description
Unknown type.(type) 0 Type invalid The specified type is not valid. The type can only be: “participation”, “statistics” or “allstatistics”.
Session has expired. You must start a new session. 30100 Session expired Session has expired.
sessionkey not found 30200 Session not found Session is not found for supplied session key.
userid for sessionkey not found 30200 Session not found User ID not found for supplied session key.
sessionkey is invalid 30300 Session invalid Session key is not in correct format.
You must select a panel before you can use this method. 40001 Panel not found A panel needs to be selected before creating a campaign.
You must select a project before you can use this method. 40002 Project not found A project needs to be selected before creating a campaign.

 


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": []
        },
    ]
}

Example failure:

{
    "success": false,
    "error": "Session has expired.  You must start a new session." 
    "errno": 30100
}

Possible Failures:

Message Code Error Description
Session has expired. You must start a new session. 30100 Session expired Session has expired.
sessionkey not found 30200 Session not found Session is not found for supplied session key.
userid for sessionkey not found 30200 Session not found User ID not found for supplied session key.
sessionkey is invalid 30300 Session invalid Session key is not in correct format.
You must select a panel before you can use this method. 40001 Panel not found A panel needs to be selected before creating a campaign.

Reminder

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 localized message data. 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",
            locale: 1
        },
        {
            subject: "The Subject",
            content: "This is the message content",
            locale: 2
        }
    ],
    startdate: "2011-12-24 17:40:00",
    sampleids: [
        1,
        2,
        3
    ]
}

JSON Input messages object:

Parameter Description Default Required
subject Subject text.   yes
content Message content (must be CAN-SPAM compliant http://www.ftc.gov/spam/)   yes
locale The corresponding locale ID for this message. 1 no


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

Example failure:

{
    "success": false,
    "error": "Session has expired.  You must start a new session." 
    "errno": 30100
}

Possible Failures:

Message Code Error Description
No data found for Campaign ID: (campaign ID) 10000 Campaign ID not found Campaign with supplied campaign ID is not found in selected project.
Localized Reminder data must contain all locales! 10000 Messages invalid The supplied messages array did not contain messages with all locales for the selected panel.
The "campaignId" parameter is of an unexpected type (campaign ID type). Please use an integer, as described in the documentation. 20102 Campaign ID invalid The supplied campaign ID is not numeric.
The "messages" parameter is of an unexpected type (messages type). Please use an array, as described in the documentation. 20103 Messages invalid The supplied messages parameter is not an array.
Invalid value for locale encountered (message locale type). Please use an integer. 20103 Messages locale invalid The supplied messages locale is not numeric.
You have more than one message defined for locale (local ID). Message locales must be unique. 20103 Messages locale invalid The supplied messages array has multiple messages with the same locale. There can only
The "when" parameter is of an unexpected type (start date type). Please use a valid (UNIX) timestamp, as described in the documentation. 20104 Start date invalid The supplied start date is not valid timestamp (YYYY-MM-DD HH:mm:ss).
The "sampleIds" parameter is of an unexpected type (sample ID type). Please use an array, as described in the documentation. 20105 Sample IDs invalid The supplied sample IDs is not an array or is null.
Invalid value in "sampleId" encountered (sample ID type). Please use an array of integers, as described in the documentation. 20105 Sample IDs invalid One of the supplied sample IDs is not numeric.
The supplied sample id (sample ID) in "sampleId" is invalid or cannot be used for this campaign. 20105 Sample not found Sample with supplied sample ID is not found.
Session has expired. You must start a new session. 30100 Session expired Session has expired.
sessionkey not found 30200 Session not found Session is not found for supplied session key.
userid for sessionkey not found 30200 Session not found User ID not found for supplied session key.
sessionkey is invalid 30300 Session invalid Session key is not in correct format.
You must select a panel before you can use this method. 40001 Panel not found A panel needs to be selected before creating a campaign.
You must select a project before you can use this method. 40002 Project not found A project needs to be selected before creating a campaign.

Sample

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

Example failure:

{
    "success": false,
    "error": "Session has expired.  You must start a new session." 
    "errno": 30100
}

Possible Failures:

Message Code Error Description
Please enter the name for the sample you would like to create. 10000 Empty name The supplied name is empty. The name parameter is required.
Please enter the information for samples to be added. 10000 Empty identifiers The supplied identifiers array is empty. The identifiers parameter is required.
The "identifiers" parameter is of an unexpected type (identifiers type). Please use an array, as described in the documentation. 20104 Identifiers invalid The supplied identifiers are not an array.
Session has expired. You must start a new session. 30100 Session expired Session has expired.
sessionkey not found 30200 Session not found Session is not found for supplied session key.
userid for sessionkey not found 30200 Session not found User ID not found for supplied session key.
sessionkey is invalid 30300 Session invalid Session key is not in correct format.
You must select a panel before you can use this method. 40001 Panel not found A panel needs to be selected before creating a campaign.
You must select a project before you can use this method. 40002 Project not found A project needs to be selected before creating a campaign.

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
values array[] Array of arrays, containing values 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"
    ],
    "values": [
        [
            1,
            2,
            3
        ],
        [
            4,
            5,
            6
        ]
    ]
}

Example success:

{
    "success": true
}

Example failure:

{
    "success": false,
    "error": "Session has expired.  You must start a new session." 
    "errno": 30100
}

Possible Failures:

Message Code Error Description
Header names cannot contain spaces! (params) 10000 Params invalid The supplied parameter names should not have spaces in supplied params array.
Header names may only contain Latin letters and numbers. (params) 10000 Params invalid The parameter names should only have numbers (0-9) or letters (A-Z or a-z) in supplied params array.
Header names cannot start with numbers! (params) 10000 Params invalid The parameter names should not start with a number (0-9) in supplied params array.
The sampleId (sample ID) must be a number greater than zero 20102 Sample ID invalid The supplied sample ID is not numeric.
The "params" parameter is of an unexpected type (params type). Please use an array, as described in the documentation. 20103 Params invalid The supplied params is not an array.
The "identifiers" parameter is of an unexpected type (identifiers type). Please use an array, as described in the documentation. 20104 Identifiers invalid The supplied identifier is not an array.
Your "identifier" array contains more/fewer elements than your "values" array. They must match. 20104 Identifiers invalid The supplied identifiers and values arrays do not contain the same amount of elements. Both of these parameters must have the same element count.
The "values" parameter is of an unexpected type (data type). Please use an array, as described in the documentation. 20105 Values invalid The supplied values is not an array.
The "params" array is empty, so there is nothing to append 20203 Empty params The supplied params array is empty.
The "identifiers" array is empty, so there is nothing to append 20204 Empty identifiers The supplied identifiers array is empty.
The "values" array is empty, so there is nothing to append 20205 Empty values The supplied values array is empty.
Sample is empty 20302 Sample not found Sample with supplied sample ID is not found for selected project.
The following identifiers were not found in the sample: (identifiers) 20304 Indentifiers invalid The supplied identifiers are not found in sample.
Session has expired. You must start a new session. 30100 Session expired Session has expired.
sessionkey not found 30200 Session not found Session is not found for supplied session key.
userid for sessionkey not found 30200 Session not found User ID not found for supplied session key.
sessionkey is invalid 30300 Session invalid Session key is not in correct format.
You must select a panel before you can use this method. 40001 Panel not found A panel needs to be selected before creating a campaign.
You must select a project before you can use this method. 40002 Project not found A project needs to be selected before creating a campaign.

Session

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

Example failure:

{
    "success": false,
    "error": "Session has expired.  You must start a new session." 
    "errno": 30100
}

Possible Failures:

Message Code Error Description
Session key (sesskey) is not valid 20202 Session string invalid Session with supplied session string is not found.
Session has expired. You must start a new session. 30100 Session expired Session has expired.
sessionkey not found 30200 Session not found Session is not found for supplied session key.
userid for sessionkey not found 30200 Session not found User ID not found for supplied session key.
sessionkey is invalid 30300 Session invalid Session key is not in correct format.

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. Valid statuses are: 'profile', 'quota' and 'completed'. yes
points integer Optional to supply custom number of points no
note string Optional to supply custom reward points activity note; note is only saved if a non-zero points value is provided or the campaign is set up to issue points for the status that is provided. no


Example POST:

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

Example success:

{
    "success": true
}

Example failure:

{
    "success": false,
    "error": "Session has expired.  You must start a new session." 
    "errno": 30100
}

Possible Failures:

Message Code Error Description
Session key (sesskey) is not valid 20202 Session string invalid Session with supplied session string is not found.
Project is closed 20203 Project Closed The project is closed and status cannot be updated.
Campaign is expired 20203 Campaign Expired The campaign is expired and status cannot be updated.
Panelist opted out 20203 Panelist Opted Out The panelist is opted out.
Status (status) is unknown 20203 Status invalid The supplied status is invalid. The status must be one of the following: “profile”, “quota” or “completed”.
Somebody is trying to go from status: ‘(current panelist status)’ to ‘(status)’ while bypassing 'started’ 20203 Status invalid The supplied status in valid. The panelist must have a started status before changing it to this status.
Status can only be set higher than its current value of ‘(current panelist status)’ 20203 Status invalid The supplied status is invalid for panelist.
A pending session can only be changed to 'invited' 20203 Status invalid The supplied status is invalid. The panelist is pending and their status can be changed to invited only.
Exit status already recorded 20203 Status invalid The panelist exit status is already recorded. Their status cannot be changed.
Points value must be positive 20204 Points invalid The supplied points value must be positive.
Session has expired. You must start a new session. 30100 Session expired Session has expired.
sessionkey not found 30200 Session not found Session is not found for supplied session key.
userid for sessionkey not found 30200 Session not found User ID not found for supplied session key.
sessionkey is invalid 30300 Session invalid Session key is not in correct format.

Surveys

integration.surveys.available

Get a list of available surveys for a panelist

JSON Input Fields:

Parameter Type Description Required Since
sesKey string A valid login hash. yes  
index string Panelist ID or identifier to look up the panelist yes  
indexType string The type of index being used (Possible values: "identifier", "pid") no 4.5.3

Example POST:

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

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

Example failure:

{
    "success": false,
    "error": "Session has expired.  You must start a new session." 
    "errno": 30100
}

Possible Failures:

Message Code Error Description
Invalid index type 20100 Index type invalid The supplied index type is invalid. Index type can only be set to “pid” or “identifier”.
Panelist not found 20203 Panelist not found Panelist with supplied identifier or panelist ID is not found.
Session has expired. You must start a new session. 30100 Session expired Session has expired.
sessionkey not found 30200 Session not found Session is not found for supplied session key.
userid for sessionkey not found 30200 Session not found User ID not found for supplied session key.
sessionkey is invalid 30300 Session invalid Session key is not in correct format.
  • Was this article helpful?