openapi: 3.1.1 info: title: Integration API version: '' servers: - url: https://{server} description: Replace server with your instance domain. variables: server: default: staging.panel.dev.focusvision.com/ description: Server domain paths: /api/integration/sessions: post: operationId: createSession summary: Create a new session description: | Create a new session token that can be used to authenticate later requests. The session remains active for 30 minutes. For existing sessions, any new request to the API resets the session timer back to 30 minutes. In order to obtain credentials, you must create an API key in “API Key Management” under the user icon menu. tags: - Auth security: [] requestBody: content: application/json: schema: type: object required: - username - password properties: username: description: The Client Id you get from API key manager module. type: string example: 3e159fcb-d2e6-4581-a1bb-c2d934c0aaaa password: description: The secret you get from API key manager module. type: string example: 677621b3-a999-4ec9-8d04-49452eb57777 responses: '201': description: OK content: application/json: schema: type: object properties: session_key: description: | The `session_key` value returned in the response can be used as the `sessionKey` parameter in `DELETE /api/integration/sessions/{sessionKey}`. example: 5a15852c564933807bbd36da58071063 type: string examples: success: summary: Success value: session_key: 5a15852c564933807bbd36da58071063 '400': description: | Bad request. Check that the "username" and "password" fields are present. '401': description: | Unauthorized. Could be one of the following: - The supplied client id was not found. - The supplied secret was empty or incorrect. - There have been too many failed attempts from this IP address within a certain time frame. '403': description: | Forbidden. The IP address is not allowed access. /api/integration/sessions/{sessionKey}: delete: operationId: terminateSession summary: Terminate an existing session description: | Terminate an existing session by invalidating a `session_key` tags: - Auth security: - BearerAuth: [] parameters: - name: sessionKey in: path required: true description: sessionKey schema: type: string responses: '204': description: No Content '401': description: Access token is missing or invalid '404': description: The supplied resource id was not found /api.pro#method=integration.campaign.createWithCommunity: post: operationId: campaignCreateWithCommunity summary: Create a campaign with community description: | Schedule campaign for the panelists. Campaigns are typically used to send email invitations to the panelists. This 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). tags: - Campaign security: - ApiKey: [] parameters: - $ref: '#/components/parameters/method' schema: enum: - integration.campaign.createWithCommunity requestBody: required: true content: application/json: schema: type: object required: - sesKey - settings - communityMessages - messages - sampleids properties: sesKey: type: string description: A valid login hash. settings: type: object description: An array of settings (name => value) properties: name: type: string description: Name of the campaign. startTime: type: string description: When to start sending out invitations. pattern: ^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}$ endTime: type: string description: When this campaign expires. pattern: ^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}$ messageTypes: type: array enum: - - email - - sms - - email - sms - [] description: 'Message types used by campaign. An array consisting of email and/or (if available) sms, or an empty array for community-only campaigns. (Default: [email])' default: - email items: type: string description: type: string description: The description of the campaign. purpose: type: string enum: - invitation - profiler default: invitation description: The purpose of the campaign. includePortal: type: string enum: - 'yes' - 'no' - exclusively default: 'yes' description: Whether or not to display this invitation to portal members pointsCompleted: type: integer description: Amount of points a panelist will receive upon completion. pointsProfile: type: integer description: Amount of points a panelist will receive when profile terminating. pointsQuota: type: integer description: Amount of points a panelist will receive when quota terminating. maxParticipation: type: integer description: Amount of times a panelist is allowed to participate. pointsTermination: type: string enum: - every - first default: every description: Reward panelist every time he participates or only the first time. required: - name - startTime communityMessages: type: array description: 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. items: type: object properties: communitySubject: type: string description: Community subject text communityContent: type: string description: Community message content locale: type: array description: Array of locale ids items: type: integer required: - communitySubject - communityContent - locale messages: type: array description: An array of invitation messages (email and/or SMS). Not required when publishing to the community only. items: type: object properties: subject: type: string description: Email subject text content: type: string description: Email message content sms: type: string description: SMS message content (if available) locale: type: array description: Array of locale ids items: type: integer required: - locale sampleids: type: array description: An array of sample IDs (obtained via integration.sample.create) items: type: integer example: sesKey: 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 responses: '200': description: OK content: application/json: schema: oneOf: - $ref: '#/components/schemas/error' - type: object properties: success: type: boolean data: properties: campaignid: type: integer examples: success: summary: Success value: success: true data: campaignid: 2 error-0: description: The supplied settings name is not a string between 0-100 characters. summary: Settings name invalid value: success: false error: Name invalid errno: '0' error-1: description: The supplied settings description is not a string between 0-65535 characters. summary: Settings description invalid value: success: false error: Description invalid errno: '0' error-2: description: 'The supplied settings start time is not a string or is formatted incorrectly. Format: YYYY-MM-DD hh:mm:ss' summary: Settings start time invalid value: success: false error: Start time invalid errno: '0' error-3: description: 'The supplied settings end time is not a string or is formatted incorrectly. Format: YYYY-MM-DD hh:mm:ss' summary: Settings end time invalid value: success: false error: End time invalid errno: '0' error-4: description: The supplied settings purpose is not a valid string. The settings purpose parameter must be "invitation" or "profile". summary: Settings purpose invalid value: success: false error: Purpose invalid errno: '0' error-5: description: The supplied include portal is not a valid string. The settings include portal parameter must be "invitation" or "profile". summary: Settings include portal invalid value: success: false error: Include portal invalid errno: '0' error-6: description: The supplied settings points completed is not an integer. summary: Settings points completed value: success: false error: Points completed invalid errno: '0' error-7: description: The supplied settings points profile is not an integer. summary: Settings points profile invalid value: success: false error: Points profile invalid errno: '0' error-8: description: The supplied settings points quota is not an integer. summary: Settings points quota invalid value: success: false error: Points quota invalid errno: '0' error-9: description: The supplied settings max participation is not an integer. summary: Settings max participation invalid value: success: false error: Max participation invalid errno: '0' error-10: description: The supplied settings points termination is not a valid string. The settings points termination parameter must be "first" or "every". summary: Settings points termination invalid value: success: false error: Points termination invalid errno: '0' error-11: description: The supplied settings message types is not an array. summary: Settings message types invalid value: success: false error: Message types invalid errno: '0' error-12: description: The supplied settings message type is not a valid string. The settings message type parameter must be "sms" or "email". summary: Settings message type invalid value: success: false error: Message type invalid errno: '0' error-13: description: Settings message types cannot be supplied for community only campaigns. summary: Message invalid value: success: false error: Message types can not be set for community only campaign errno: '0' error-14: description: The supplied community messages is not an array. summary: Community messages invalid value: success: false error: Malformed community message array errno: '0' error-15: description: One or more of the supplied community messages subject is not a string. summary: Community message subject invalid value: success: false error: Invalid community message subject errno: '0' error-16: description: One or more of the supplied community messages content is not a string. summary: Community message content invalid value: success: false error: Invalid community message content errno: '0' error-17: description: One or more of the supplied community messages subject is not a string between 1-65535 characters. summary: Community message subject invalid value: success: false error: Subject out of bounds errno: '0' error-18: description: One or more of the supplied community messages content is not a string between 1-65535 characters. summary: Community message content invalid value: success: false error: Content out of bounds errno: '0' error-19: description: One or more of the supplied community messages or messages locale is not an array. summary: Community messages/Messages locale invalid value: success: false error: Invalid locale array errno: '0' error-20: description: One or more of the supplied community messages or messages locale is not a valid locale for the panel. summary: Community messages/Messages locale invalid value: success: false error: Invalid locale errno: '0' error-21: description: The amount of community messages or messages are not equal to the amount of locales for panel. summary: Community messages/Messages invalid value: success: false error: Missing locales errno: '0' error-22: description: The supplied messages is not an array. summary: Messages invalid value: success: false error: Malformed message array errno: '0' error-23: description: One or more of the supplied messages subject is not a string. summary: Message subject invalid value: success: false error: Invalid message subject errno: '0' error-24: description: One or more of the supplied messages content is not a string. summary: Message content invalid value: success: false error: Invalid message content errno: '0' error-25: description: One or more of the supplied messages sms content is not a string. summary: Message sms content invalid value: success: false error: Invalid sms content errno: '0' error-26: description: SMS messaging is not set up for this panel. summary: SMS gateway provider not found value: success: false error: No SMS gateway provider available errno: '0' error-27: description: The messages parameter cannot be specified when the supplied settings include portal is set to "exclusively". summary: Messages invalid value: success: false error: Can not use messages for community exclusive campaign errno: '0' error-28: description: The supplied sample IDs is empty. summary: Empty sample IDs value: success: false error: Invalid number of samples provided errno: '0' error-29: description: Sample with supplied sample ID is not found. summary: Sample IDs not found value: success: false error: Invalid sample provided errno: '0' error-30: description: Session has expired. summary: Session expired value: success: false error: Session has expired. You must start a new session. errno: '30100' error-31: description: Session is not found for supplied session key. summary: Session not found value: success: false error: sessionkey not found errno: '30200' error-32: description: User ID not found for supplied session key. summary: Session not found value: success: false error: userid for sessionkey not found errno: '30200' error-33: description: Session key is not in correct format. summary: Session invalid value: success: false error: sessionkey is invalid errno: '30300' error-34: description: A panel needs to be selected before calling this method. summary: Panel not found value: success: false error: You must select a panel before you can use this method. errno: '40001' error-35: description: A project needs to be selected before calling this method. summary: Project not found value: success: false error: You must select a project before you can use this method. errno: '40002' /api.pro#method=integration.campaign.listing: post: operationId: campaignListing summary: List scheduled campaign description: | Read listing of all campaign scheduled for the current project. tags: - Campaign security: - ApiKey: [] parameters: - $ref: '#/components/parameters/method' schema: enum: - integration.campaign.listing requestBody: content: application/json: schema: type: object required: - sesKey properties: sesKey: description: A valid login hash. type: string example: 5a15852c564933807bbd36da58071063 responses: '200': description: OK content: application/json: schema: oneOf: - $ref: '#/components/schemas/error' - type: object properties: success: example: true type: boolean data: type: array items: type: object properties: id: type: integer description: Id of the campaign. name: type: string description: Name of the campaign. description: type: string description: Description of the campaign. starttime: type: string pattern: ^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}$ description: Start time of the campaign. endtime: type: - string - 'null' pattern: ^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}$ description: End time of the campaign. purpose: type: string description: | Purpose of the campaign. portalinvitation: type: string description: | Was this campaign launched to the community (yes/no) pointscompleted: description: Amount of points given for completing. type: integer pointsprofile: description: Amount of points given for profile terminating. type: integer pointsquota: description: Amount of points given for quota terminating. type: integer maxparticipation: description: Amount of times the campaign can be taken (0 = unlimited). type: integer pointstermination: description: When points are received terminating ("every"/"first"). type: string created_by: type: string description: Name of the user who created the campaign. created: type: string description: Time and date of the creation of the campaign. examples: success: summary: Success value: 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: Panelsis Tester created: '2011-10-14 12:46:52' error-0: description: Session has expired. summary: Session expired value: success: false error: Session has expired. You must start a new session. errno: '30100' error-1: description: Session is not found for supplied session key. summary: Session not found value: success: false error: sessionkey not found errno: '30200' error-2: description: User ID not found for supplied session key. summary: Session not found value: success: false error: userid for sessionkey not found errno: '30200' error-3: description: Session key is not in correct format. summary: Session invalid value: success: false error: sessionkey is invalid errno: '30300' error-4: description: A panel needs to be selected before calling this method. summary: Panel not found value: success: false error: You must select a panel before you can use this method. errno: '40001' error-5: description: A project needs to be selected before calling this method. summary: Project not found value: success: false error: You must select a project before you can use this method. errno: '40002' /api.pro#method=integration.campaign.get: post: operationId: campaignGet summary: Get campaign description: | Get info on one specific campaign in the current project. tags: - Campaign security: - ApiKey: [] parameters: - $ref: '#/components/parameters/method' schema: enum: - integration.campaign.get requestBody: content: application/json: schema: type: object required: - sesKey - campaingid properties: sesKey: description: A valid login hash. type: string example: 5a15852c564933807bbd36da58071063 campaingid: description: The id of the campaign. type: integer example: 42 responses: '200': description: OK content: application/json: schema: oneOf: - $ref: '#/components/schemas/error' - type: object properties: success: type: boolean data: type: object properties: id: type: integer description: Id of the campaign. name: type: string description: Name of the campaign. description: type: string description: Description of the campaign. starttime: type: string description: Start time of the campaign. endtime: type: - string - 'null' description: End time of the campaign. purpose: type: string description: Purpose of the campaign. portalinvitation: type: string description: Was this campaign launched to the community (yes/no). pointscompleted: type: integer description: Amount of points given for completing. pointsprofile: type: integer description: Amount of points given for profile terminating. pointsquota: type: integer description: Amount of points given for quota terminating. maxparticipation: type: integer description: Amount of times the campaign can be taken (0 = unlimited). pointstermination: type: string description: When points are received terminating ("every"/"first"). created_by: type: string description: Name of the user who created the campaign. created: type: string description: Time and date of the creation of the campaign. examples: success: summary: Success value: 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' error-0: description: Session has expired. summary: Session expired value: success: false error: Session has expired. You must start a new session. errno: '30100' error-1: description: Session is not found for supplied session key. summary: Session not found value: success: false error: sessionkey not found errno: '30200' error-2: description: User ID not found for supplied session key. summary: Session not found value: success: false error: userid for sessionkey not found errno: '30200' error-3: description: Session key is not in correct format. summary: Session invalid value: success: false error: sessionkey is invalid errno: '30300' error-4: description: A panel needs to be selected before calling this method. summary: Panel not found value: success: false error: You must select a panel before you can use this method. errno: '40001' error-5: description: A project needs to be selected before calling this method. summary: Project not found value: success: false error: You must select a project before you can use this method. errno: '40002' /api.pro#method=integration.campaign.schedule: post: operationId: scheduleCampaign summary: Lists all samples and reminders scheduled for a campaign description: | Outputs a list of all samples and reminders that were scheduled for a specific campaign. tags: - Campaign security: - ApiKey: [] parameters: - $ref: '#/components/parameters/method' schema: enum: - integration.campaign.schedule requestBody: content: application/json: schema: type: object required: - sesKey - campaignid properties: sesKey: description: A valid login hash. type: string example: 5a15852c564933807bbd36da58071063 campaignid: type: integer description: | The campaignid of the campaign to list the schedule of. example: 1 responses: '200': description: OK content: application/json: schema: oneOf: - $ref: '#/components/schemas/error' - type: object properties: success: example: true type: boolean data: type: object properties: name: type: string type: description: The type (reminder, sample) type: string scheduled: description: The date and time it was scheduled. type: string sampleid: type: - integer - 'null' description: If type is "sample", the sampleid will be listed here. created_by: description: The user the reminder or sample was created by. type: string examples: success: summary: Success value: 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 error-0: description: The supplied campaign ID is not numeric. summary: Campaign ID invalid value: success: false error: The supplied campaign id is invalid. errno: '20102' error-1: description: Campaign with supplied campaign ID is not found. summary: Campaign ID not found value: success: false error: 'No data found for Campaign ID: (campaign ID)' errno: '20302' error-2: description: Session has expired. summary: Session expired value: success: false error: Session has expired. You must start a new session. errno: '30100' error-3: description: Session is not found for supplied session key. summary: Session not found value: success: false error: sessionkey not found errno: '30200' error-4: description: User ID not found for supplied session key. summary: Session not found value: success: false error: userid for sessionkey not found errno: '30200' error-5: description: Session key is not in correct format. summary: Session invalid value: success: false error: sessionkey is invalid errno: '30300' error-6: description: A panel needs to be selected before calling this method. summary: Panel not found value: success: false error: You must select a panel before you can use this method. errno: '40001' error-7: description: A project needs to be selected before calling this method. summary: Project not found value: success: false error: You must select a project before you can use this method. errno: '40002' /api.pro#method=integration.category.listing: post: operationId: categoryListing summary: List all categories description: | This call retrieves a list of defined categories for the selected panel. tags: - Category security: - ApiKey: [] parameters: - $ref: '#/components/parameters/method' schema: enum: - integration.category.listing requestBody: content: application/json: schema: type: object required: - sesKey properties: sesKey: description: A valid login hash. type: string example: 5a15852c564933807bbd36da58071063 responses: '200': description: OK content: application/json: schema: oneOf: - $ref: '#/components/schemas/error' - type: object properties: success: example: true type: boolean data: type: array items: type: object properties: id: type: integer description: The category id (used in integration.project.create and integration.project.listing) name: type: string description: The name of the category examples: success: summary: Success value: success: true data: - id: 1 name: New category - id: 2 name: Second category error-0: description: Session has expired. summary: Session expired value: success: false error: Session has expired. You must start a new session. errno: '30100' error-1: description: Session is not found for supplied session key. summary: Session not found value: success: false error: sessionkey not found errno: '30200' error-2: description: User ID not found for supplied session key. summary: Session not found value: success: false error: userid for sessionkey not found errno: '30200' error-3: description: Session key is not in correct format. summary: Session invalid value: success: false error: sessionkey is invalid errno: '30300' error-4: description: A panel needs to be selected before calling this method. summary: Panel not found value: success: false error: You must select a panel before you can use this method. errno: '40001' /api.pro#method=integration.community.createSession: post: operationId: communityCreateSession summary: Create a session by username/email address description: | Creates an active session using the panelist username/email address for use with Portal API, without the need for a panelist password. tags: - Community security: - ApiKey: [] parameters: - $ref: '#/components/parameters/method' schema: enum: - integration.community.createSession requestBody: content: application/json: schema: type: object required: - sesKey - username properties: sesKey: description: A valid login hash. type: string example: 5a15852c564933807bbd36da58071063 username: description: The username of the panelist the session is created for. type: string example: test@kinesissurvey.com responses: '200': description: OK content: application/json: schema: oneOf: - $ref: '#/components/schemas/error' - type: object properties: success: example: true type: boolean data: properties: seskey: description: A valid login hash. type: string panelistid: description: The id of the panelist that the session was created for. type: integer email: description: The email address of the panelist that the session was created for. type: string fullname: description: The full name of the panelist that the session was created for. type: string examples: success: summary: Success value: success: true data: seskey: 672ef56f6a475fedb0fcf8f109e3f410 panelistid: 1 email: test@kinesissurvey.com fullname: '' error-0: description: The supplied email address is not valid or a panelist with supplied email address is not found. summary: Email invalid or not found value: success: false error: The supplied email is invalid errno: '20102' error-1: description: Session has expired. summary: Session expired value: success: false error: Session has expired. You must start a new session. errno: '30100' error-2: description: Session is not found for supplied session key. summary: Session not found value: success: false error: sessionkey not found errno: '30200' error-3: description: User ID not found for supplied session key. summary: Session not found value: success: false error: userid for sessionkey not found errno: '30200' error-4: description: Session key is not in correct format. summary: Session invalid value: success: false error: sessionkey is invalid errno: '30300' error-5: description: A panel needs to be selected before calling this method. summary: Panel not found value: success: false error: You must select a panel before you can use this method. errno: '40001' /api.pro#method=integration.community.createSessionWithPID: post: operationId: communityCreateSessionWithPID summary: Create a session using the panelist pid description: | Creates an active session using the panelist pid (panelist id) for use with Portal API, without the need for a panelist password. tags: - Community security: - ApiKey: [] parameters: - $ref: '#/components/parameters/method' schema: enum: - integration.community.createSessionWithPID requestBody: content: application/json: schema: type: object required: - sesKey - pid properties: sesKey: description: A valid login hash. type: string example: 5a15852c564933807bbd36da58071063 pid: description: The pid (panelist id) of the panelist the session is created for. type: integer example: 1 responses: '200': description: OK content: application/json: schema: oneOf: - $ref: '#/components/schemas/error' - type: object properties: success: example: true type: boolean data: properties: seskey: description: A valid login hash. type: string panelistid: description: The id of the panelist that the session was created for. type: integer email: description: The email address of the panelist that the session was created for. type: string fullname: description: The full name of the panelist that the session was created for. type: string examples: success: summary: Success value: success: true data: seskey: 672ef56f6a475fedb0fcf8f109e3f410 panelistid: 1 email: test@kinesissurvey.com fullname: '' error-0: description: The supplied panelist ID is not numeric or a panelist with supplied panelist ID is not found. summary: PID invalid or not found value: success: false error: The supplied pid is invalid errno: '20102' error-1: description: Session has expired. summary: Session expired value: success: false error: Session has expired. You must start a new session. errno: '30100' error-2: description: Session is not found for supplied session key. summary: Session not found value: success: false error: sessionkey not found errno: '30200' error-3: description: User ID not found for supplied session key. summary: Session not found value: success: false error: userid for sessionkey not found errno: '30200' error-4: description: Session key is not in correct format. summary: Session invalid value: success: false error: sessionkey is invalid errno: '30300' error-5: description: A panel needs to be selected before calling this method. summary: Panel not found value: success: false error: You must select a panel before you can use this method. errno: '40001' /api.pro#method=integration.community.createSessionWithIdentifier: post: operationId: communityCreateSessionWithIdentifier summary: Creates an active session using the panelist identifier description: | Creates an active session using the panelist identifier for use with Portal API, without the need for a panelist password. tags: - Community security: - ApiKey: [] parameters: - $ref: '#/components/parameters/method' schema: enum: - integration.community.createSessionWithIdentifier requestBody: content: application/json: schema: type: object required: - sesKey - identifier properties: sesKey: description: A valid login hash. type: string example: 5a15852c564933807bbd36da58071063 identifier: description: The identifier of the panelist the session is created for. type: string example: K_a1b2c3d4e5 responses: '200': description: OK content: application/json: schema: oneOf: - $ref: '#/components/schemas/error' - type: object properties: success: example: true type: boolean data: properties: seskey: description: A valid login hash. type: string panelistid: description: The id of the panelist that the session was created for. type: integer email: description: The email address of the panelist that the session was created for. type: string fullname: description: The full name of the panelist that the session was created for. type: string examples: success: summary: Success value: success: true data: seskey: 672ef56f6a475fedb0fcf8f109e3f410 panelistid: 1 email: test@kinesissurvey.com fullname: '' error-0: description: The supplied identifier is not a string or a Panelist with supplied identifier (username) is not found. summary: Identifier invalid or not found value: success: false error: The supplied identifier is invalid errno: '20102' error-1: description: Session has expired. summary: Session expired value: success: false error: Session has expired. You must start a new session. errno: '30100' error-2: description: Session is not found for supplied session key. summary: Session not found value: success: false error: sessionkey not found errno: '30200' error-3: description: User ID not found for supplied session key. summary: Session not found value: success: false error: userid for sessionkey not found errno: '30200' error-4: description: Session key is not in correct format. summary: Session invalid value: success: false error: sessionkey is invalid errno: '30300' error-5: description: A panel needs to be selected before calling this method. summary: Panel not found value: success: false error: You must select a panel before you can use this method. errno: '40001' /api.pro#method=integration.community.getLandingPage: post: operationId: communityGetLandingPage summary: Get landing page info description: | 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 $sesKey, // We must be authenticated to use this! (see: /api/integration/sessions) '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, ['data' => $dataJSON]); curl_setopt($client, CURLOPT_RETURNTRANSFER, true); // Submit request $result = curl_exec($client); // JSON decode result data $result = json_decode($result); ?> <?php echo $result->data->title; ?> data->message; ?> ``` tags: - Community security: - ApiKey: [] parameters: - $ref: '#/components/parameters/method' schema: enum: - integration.community.getLandingPage requestBody: content: application/json: schema: type: object required: - sesKey - encStr properties: sesKey: description: A valid login hash. type: string example: 5a15852c564933807bbd36da58071063 encStr: description: | 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. type: string example: mLBVh8xap8EmpdilvnTSh3gMY3Yxg1Y08FifDcH64mydZf6klHFAidAq0CjIzTi_uZDtCQJEtLnHPl_NjmXDwktJDJqCiTIdiUx1UVyM2psBWjzfDm1qcTG-1VGQnR-P3AVC_kNVdGQFcfMc7kB3NQ responses: '200': description: OK content: application/json: schema: oneOf: - $ref: '#/components/schemas/error' - type: object properties: success: example: true type: boolean data: properties: title: description: The landing page title type: string message: description: The landing page content type: string examples: success: summary: Success value: 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<' error-0: description: The supplied encrypted string includes a panel ID that cannot be found. summary: Internal error value: success: false error: Unable to successfully select database (database name)! errno: '0' error-1: description: The supplied encrypted string is not a valid or it is empty. summary: Encrypted string invalid value: success: false error: The supplied data could not be decrypted errno: '20102' error-2: description: The supplied encrypted string is not a valid. summary: Encrypted string invalid value: success: false error: The decrypted data could not be verified errno: '20102' error-3: description: Session has expired. summary: Session expired value: success: false error: Session has expired. You must start a new session. errno: '30100' error-4: description: Session is not found for supplied session key. summary: Session not found value: success: false error: sessionkey not found errno: '30200' error-5: description: User ID not found for supplied session key. summary: Session not found value: success: false error: userid for sessionkey not found errno: '30200' error-6: description: Session key is not in correct format. summary: Session invalid value: success: false error: sessionkey is invalid errno: '30300' /api.pro#method=integration.community.isUniqueOpenend: post: operationId: communityisUniqueOpened summary: Checks uniqueness of open end data point description: | 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. tags: - Community security: - ApiKey: [] parameters: - $ref: '#/components/parameters/method' schema: enum: - integration.community.isUniqueOpenend requestBody: content: application/json: schema: type: object required: - sesKey - label - value properties: sesKey: description: A valid login hash. type: string example: 5a15852c564933807bbd36da58071063 label: description: | The data point label type: string example: Qfirstname value: description: The data point value to check for type: string example: John responses: '200': description: OK content: application/json: schema: oneOf: - $ref: '#/components/schemas/error' - type: object properties: success: type: boolean unique: type: boolean examples: success: summary: Success value: success: true unique: false error-0: description: Data point with supplied label is not found or supplied label is invalid. summary: Label invalid or not found value: success: false error: Invalid label - data point not found or not open-end. errno: '20102' error-1: description: The supplied value is not a string. summary: Value invalid value: success: false error: Supplied value is invalid. errno: '20103' error-2: description: Session has expired. summary: Session expired value: success: false error: Session has expired. You must start a new session. errno: '30100' error-3: description: Session is not found for supplied session key. summary: Session not found value: success: false error: sessionkey not found errno: '30200' error-4: description: User ID not found for supplied session key. summary: Session not found value: success: false error: userid for sessionkey not found errno: '30200' error-5: description: Session key is not in correct format. summary: Session invalid value: success: false error: sessionkey is invalid errno: '30300' error-6: description: A panel needs to be selected before calling this method. summary: Panel not found value: success: false error: You must select a panel before you can use this method. errno: '40001' /api.pro#method=integration.datapoint.create: post: operationId: datapointCreate summary: Create datapoints description: | This function is used to add new datapoints to the panel. All datapoint types are supported. tags: - Datapoint security: - ApiKey: [] parameters: - $ref: '#/components/parameters/method' schema: enum: - integration.datapoint.create requestBody: content: application/json: schema: type: object required: - sesKey - settings properties: sesKey: description: A valid login hash. type: string example: 5a15852c564933807bbd36da58071063 settings: type: object description: | An associative array that differs based on the datapoint type. required: - label - qtext - type properties: label: description: The label of the datapoint. type: string qtext: description: The question text of the datapoint. type: string type: description: The datapoint type. type: string enum: - radio - checkbox - date - openend - number - float choices: description: RADIO/CHECKBOX only! A zero based array of associative arrays, with the size equal to the number of choices. type: array items: type: object required: - choiceid - name properties: choiceid: type: integer description: The Choice ID (1 - ...) name: type: string description: The Choice Name examples: Openend datapoint: value: sesKey: 5a15852c564933807bbd36da58071063 settings: label: Q3 qtext: This is datapoint three type: openend Checkbox datapoint: value: sesKey: 5a15852c564933807bbd36da58071063 settings: label: Q4 qtext: This is datapoint four type: checkbox choices: - choiceid: 1 name: Choice one - choiceid: 2 name: Choice two responses: '200': description: OK content: application/json: schema: oneOf: - $ref: '#/components/schemas/error' - type: object properties: success: type: boolean data: properties: datapointid: description: The id of the new datapoint. type: integer examples: success: summary: Success value: success: true data: datapointid: 3 error-0: description: The supplied settings label is used for the selected panel. summary: Settings label invalid value: success: false error: Datapoint label (datapoint label) is already being used! errno: '0' error-1: description: 'The supplied settings type is not one of the predefined types: "openend", "checkbox", "date", "radio", "number", "float".' summary: Settings type invalid value: success: false error: Datapoint type (datapoint type) is invalid! errno: '0' error-2: description: The supplied settings choices are empty. summary: Empty settings choices value: success: false error: Choice is missing 'choiceid'!" errno: '0' error-3: description: The supplied settings choices was empty or not provided. The question type requires choices to be created. summary: Settings choices not found value: success: false error: 'The question type: (datapoint type) cannot be added without choices!' errno: '0' error-4: description: Session has expired. summary: Session expired value: success: false error: Session has expired. You must start a new session. errno: '30100' error-5: description: Session is not found for supplied session key. summary: Session not found value: success: false error: sessionkey not found errno: '30200' error-6: description: User ID not found for supplied session key. summary: Session not found value: success: false error: userid for sessionkey not found errno: '30200' error-7: description: Session key is not in correct format. summary: Session invalid value: success: false error: sessionkey is invalid errno: '30300' error-8: description: A panel needs to be selected before calling this method. summary: Panel not found value: success: false error: You must select a panel before you can use this method. errno: '40001' /api.pro#method=integration.datapoint.delete: post: operationId: datapointDelete summary: Delete existing datapoint description: | Delete existing datapoint by using its unique datapoint ID. # WARNING This will also delete stored data for the datapoint tags: - Datapoint security: - ApiKey: [] parameters: - $ref: '#/components/parameters/method' schema: enum: - integration.datapoint.delete requestBody: content: application/json: schema: type: object required: - sesKey - datapointid properties: sesKey: description: A valid login hash. type: string example: 5a15852c564933807bbd36da58071063 datapointid: description: Datapoint ID. type: integer example: 1 responses: '200': description: OK content: application/json: schema: oneOf: - $ref: '#/components/schemas/error' - type: object properties: success: example: true type: boolean examples: success: summary: Success value: success: true error-0: description: The supplied datapoint ID is not numeric. summary: Datapoint ID invalid value: success: false error: Invalid data ID errno: '0' error-1: description: Datapoint with supplied datapoint ID is not found. summary: Datapoint ID not found value: success: false error: Datapoint object doesn't contain dataid! errno: '0' error-2: description: Session has expired. summary: Session expired value: success: false error: Session has expired. You must start a new session. errno: '30100' error-3: description: Session is not found for supplied session key. summary: Session not found value: success: false error: sessionkey not found errno: '30200' error-4: description: User ID not found for supplied session key. summary: Session not found value: success: false error: userid for sessionkey not found errno: '30200' error-5: description: Session key is not in correct format. summary: Session invalid value: success: false error: sessionkey is invalid errno: '30300' error-6: description: A panel needs to be selected before calling this method. summary: Panel not found value: success: false error: You must select a panel before you can use this method. errno: '40001' /api.pro#method=integration.datapoint.idFromLabel: post: operationId: datapointIdFromLabel summary: Get datapoint by label description: | This utility function allows retrieval of datapoint ID by using the label for the datapoint i.e. QAGE -> 22 tags: - Datapoint security: - ApiKey: [] parameters: - $ref: '#/components/parameters/method' schema: enum: - integration.datapoint.idFromLabel requestBody: content: application/json: schema: type: object required: - sesKey - label properties: sesKey: description: A valid login hash. type: string example: 5a15852c564933807bbd36da58071063 label: description: The label of the datapoint. type: string example: Q1 responses: '200': description: OK content: application/json: schema: oneOf: - $ref: '#/components/schemas/error' - type: object properties: success: example: true type: boolean data: type: object properties: datapointid: description: Unique id for the given datapoint label example: 1 examples: success: summary: Success value: success: true data: datapointid: 1 error-0: description: The supplied label is empty or contains invalid characters. summary: Label invalid value: success: false error: 'Supplied datapoint label: (datapoint label) contains invalid characters!' errno: '0' error-1: description: Datapoint with supplied label is not found. summary: Datapoint not found value: success: false error: 'The supplied datapoint label: (datapoint label) is unknown.' errno: '0' error-2: description: Session has expired. summary: Session expired value: success: false error: Session has expired. You must start a new session. errno: '30100' error-3: description: Session is not found for supplied session key. summary: Session not found value: success: false error: sessionkey not found errno: '30200' error-4: description: User ID not found for supplied session key. summary: Session not found value: success: false error: userid for sessionkey not found errno: '30200' error-5: description: Session key is not in correct format. summary: Session invalid value: success: false error: sessionkey is invalid errno: '30300' error-6: description: A panel needs to be selected before calling this method. summary: Panel not found value: success: false error: You must select a panel before you can use this method. errno: '40001' /api.pro#method=integration.panel.select: post: operationId: panelSelect summary: Select current panel tags: - Panel security: - ApiKey: [] parameters: - $ref: '#/components/parameters/method' schema: enum: - integration.panel.select requestBody: content: application/json: schema: type: object required: - sesKey - panelid properties: sesKey: description: A valid login hash. type: string example: 5a15852c564933807bbd36da58071063 panelid: description: The id of the panel to select.. type: integer example: 1 responses: '200': description: OK content: application/json: schema: oneOf: - $ref: '#/components/schemas/error' - type: object properties: success: example: true type: boolean examples: success: summary: Success value: success: true error-0: description: The supplied panel ID is not numeric. summary: Panel ID invalid value: success: false error: Invalid panel id (panel ID) errno: '20102' error-1: description: Panel with supplied panel ID is not found. summary: Panel not found value: success: false error: Panel (panel ID) not found errno: '20302' error-2: description: Session has expired. summary: Session expired value: success: false error: Session has expired. You must start a new session. errno: '30100' error-3: description: Session is not found for supplied session key. summary: Session not found value: success: false error: sessionkey not found errno: '30200' error-4: description: User ID not found for supplied session key. summary: Session not found value: success: false error: userid for sessionkey not found errno: '30200' error-5: description: Session key is not in correct format. summary: Session invalid value: success: false error: sessionkey is invalid errno: '30300' /api.pro#method=integration.panelist.create: post: operationId: panelistCreate summary: Create a panelist description: | Create a panelist with accompanying data.

## NOTE: In most cases, `portal.email.sendOptInConfirmation` will need to be called after panelist is created successfully. tags: - Panelist security: - ApiKey: [] parameters: - $ref: '#/components/parameters/method' schema: enum: - integration.panelist.create requestBody: content: application/json: schema: type: object required: - sesKey - settings properties: sesKey: description: A valid login hash. type: string example: 5a15852c564933807bbd36da58071063 settings: description: Which type of statistics to pull.. type: array items: type: object required: - label - answer properties: label: description: A valid datapoint label or panelist field. type: string example: 5a15852c564933807bbd36da58071063 answer: description: The answer to set for the label. type: string example: 5a15852c564933807bbd36da58071063 example: - name: email url: test@kinesissurvey.com - name: sourceid answer: 335 - name: identifier answer: KS_234234 responses: '200': description: OK content: application/json: schema: oneOf: - $ref: '#/components/schemas/error' - type: object properties: success: type: boolean data: type: object properties: pid: type: number sourceid: type: - string - 'null' localid: type: string portalid: type: string subscribed: type: string identifier: type: string description: Unique panelist identifier created by Panel Management email: type: string password: type: string emailok: type: string phoneok: type: string blacklisted: type: string timezone: type: string dateformat: type: string timeformat: type: string modified: type: string created: type: string joined: type: string first_participation: type: - string - 'null' last_participation: type: - string - 'null' first_invitation: type: - string - 'null' last_invitation: type: - string - 'null' unsubscribed: type: - string - 'null' timeblacklisted: type: - string - 'null' timeunblacklisted: type: - string - 'null' timereferred: type: - string - 'null' first_completed: type: - string - 'null' last_completed: type: - string - 'null' last_pointsearned: type: - string - 'null' last_surveyscreened: type: - string - 'null' responserate: type: - string - 'null' completionrate: type: - string - 'null' invited: type: string responded: type: string completed: type: string md_invited: type: string md_started: type: string md_completed: type: string md_screened: type: string md_finished: type: string md_referredpanelists: type: string points_earned: type: string points_available: type: string points_redeemed: type: string points_survey: type: string points_referral: type: string points_other: type: string examples: success: summary: Success value: 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-01 14:02:15' created: '2011-10-14 11: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' error-0: description: The supplied checkbox answer is not a numeric or string integers separated by commas ("1,2,3"). summary: Settings checkbox answer invalid value: success: false error: Supplied choice is invalid errno: '0' error-1: description: The supplied settings radio answer is not numeric. summary: Settings radio answer invalid value: success: false error: Supplied choice(answer) is invalid for data point (datapoint label). The value must be an unsigned integer or NULL. errno: '0' error-2: description: The supplied radio or checkbox answer is not in choice range. summary: Settings radio/checkbox answer invalid value: success: false error: 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). errno: '0' error-3: description: One of the supplied settings labels is not found for any datapoints. summary: Settings label not found value: success: false error: Unknown datapoint label (label). errno: '20000' error-4: description: The supplied email address is used by another panelist in the panel. summary: Settings email duplicate value: success: false error: The email address you supplied is already in use. You may be registered for this panel under a different login name. errno: '20000' error-5: description: The supplied identifier is used by another panelist in the panel. summary: Settings identifier duplicate value: success: false error: The identifier you supplied is already in use. errno: '20000' error-6: description: The supplied settings is empty. summary: Settings invalid value: success: false error: No answer data supplied! errno: '20000' error-7: description: The subscribed is invalid. Subscribed can only be set to "yes" or "no". summary: Settings subscribed invalid value: success: false error: The supplied value for label 'subscribed' is invalid errno: '20000' error-8: description: The supplied date answer was not in valid date format (YYYY-MM-DD). summary: Settings date answer invalid value: success: false error: The supplied date (answer) was invalid for (datapoint label) (date) errno: '20000' error-9: description: The supplied openend answer is not a string. summary: Settings openend answer invalid value: success: false error: The data type (answer type) is not valid for (datapoint label) (openend) errno: '20000' error-10: description: The supplied timezone is not valid timezone. summary: Settings timezone invalid value: success: false error: Unknown or bad timezone errno: '20000' error-11: description: The supplied settings is not in valid format. Each datapiont within settings needs to contain a "label" and an "answer". summary: Settings invalid value: success: false error: Malformed answer data received errno: '20102' error-12: description: Session has expired. summary: Session expired value: success: false error: Session has expired. You must start a new session. errno: '30100' error-13: description: Session is not found for supplied session key. summary: Session not found value: success: false error: sessionkey not found errno: '30200' error-14: description: User ID not found for supplied session key. summary: Session not found value: success: false error: userid for sessionkey not found errno: '30200' error-15: description: Session key is not in correct format. summary: Session invalid value: success: false error: sessionkey is invalid errno: '30300' error-16: description: A panel needs to be selected before calling this method. summary: Panel not found value: success: false error: You must select a panel before you can use this method. errno: '40001' error-17: description: The supplied email is not a valid email address. summary: Settings email invalid value: success: false error: The supplied email address is invalid errno: '40006' /api.pro#method=integration.panelist.read: post: operationId: panelistRead summary: Read data deprecated: true description: | Read panelist data from the Panel Management 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. tags: - Panelist security: - ApiKey: [] requestBody: content: application/json: schema: type: object properties: sesKey: type: string description: A valid login hash. index: type: string description: The pid or identifier to lookup the panelist by datapoints: type: array description: Array of datapoint labels or panelist fields to return items: type: string indexType: type: string enum: - identifier - pid description: The type of index being used required: - sesKey - index examples: With datapoint labels: value: sesKey: 5a15852c564933807bbd36da58071063 index: '34359' datapoints: - Q1 - Q2 - Q3 indexType: identifier Without datapoint labels: value: sesKey: 5a15852c564933807bbd36da58071063 index: '34359' indexType: identifier responses: '200': description: OK content: application/json: schema: type: object properties: success: type: boolean data: type: object properties: pid: type: integer description: The id of the panelist. sourceid: type: integer description: The id of the source. localid: type: integer description: The localizationid, or language code of the panelist. subscribed: type: string description: Whether the panelist is subscribed or not. identifier: type: string description: The panelist identifier. email: type: string description: The email address of the panelist. password: type: string description: The password of the panelist. emailok: type: string description: Whether the email is valid. phoneok: type: string description: Whether the phone is valid. blacklisted: type: string description: Whether the panelist is blacklisted or not. timezone: type: string description: The timezone of the panelist. dateformat: type: string description: The format of the date. timeformat: type: string description: The format of the time. modified: type: string description: The most recent date/time the panelist was updated. created: type: string description: The date/time the panelist was created. joined: type: string description: The date/time the panelist joined. first_participation: type: string description: The date/time of the panelist's first participation. last_participation: type: string description: The date/time of the panelist's last participation. first_invitation: type: string description: The date/time of the panelist's first invitation. last_invitation: type: string description: The date/time of the panelist's last invitation. unsubscribed: type: string description: The date/time that the panelist was unsubscribed. timeblacklisted: type: string description: The date/time that the panelist was blacklisted. timeunblacklisted: type: string description: The date/time that the panelist was unblacklisteed. timereferred: type: string description: The date/time that the panelist was referred. first_completed: type: string description: The date/time that the panelist first completed a survey. last_completed: type: string description: The date/time that the panelist last completed a survey. last_pointsearned: type: string description: The date/time that the panelist last earned points. last_surveyscreened: type: string description: last date/time that the panelist profiled or quota termed responserate: type: integer description: The number of responses out of the number of invites in a certain period of time (usually 90 days). completionrate: type: integer description: The number of completes out of the number of invites in a certain period of time (usually 90 days). invited: type: integer description: The number of surveys the panelist has been invited to in a certain period of time (usually 90 days). responded: type: integer description: The number of surveys the panelist has responded to in a certain period of time (usually 90 days). completed: type: integer description: The number of surveys the panelist has completed in a certain period of time (usually 90 days). md_invited: type: integer description: The number of surveys the panelist has been invited to. md_started: type: integer description: The number of surveys the panelist has responded to. md_completed: type: integer description: The number of surveys the panelist has completed. md_screened: type: integer description: The number of surveys the panelist has profiled or quota termed. md_finished: type: integer description: The number of surveys the panelist has finished. md_referredpanelists: type: integer description: The number of panelists this panelist has referred. points_earned: type: integer description: The number of points the panelist has earned. points_available: type: integer description: The number of points the panelist has available for redemption. points_redeemed: type: integer description: The number of points the panelist has redeemed. points_survey: type: integer description: The number of points the panelist has earned from completing surveys. points_referral: type: integer description: The number of points the panelist has received from referrals. points_other: type: integer description: The number of points the panelist has received from an administrator. examples: success: summary: Success value: 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' error-0: description: The supplied datapoints are not valid datapoint labels or panelist fields. summary: Datapoints invalid value: success: false error: 'Invalid datapoint value(s): (datapoints)' errno: '20303' error-1: description: The supplied index type is invalid. Index type can only be set to "pid" or "identifier". summary: Index type invalid value: success: false error: Invalid index type errno: '20100' error-2: description: The supplied panelist ID is not numeric. summary: Panelist ID invalid value: success: false error: Panelist Id is invalid errno: '20102' error-3: description: Panelist with supplied identifier is not found. summary: Panelist not found value: success: false error: Panelist not found errno: '20203' error-4: description: Session has expired. summary: Session expired value: success: false error: Session has expired. You must start a new session. errno: '30100' error-5: description: Session is not found for supplied session key. summary: Session not found value: success: false error: sessionkey not found errno: '30200' error-6: description: User ID not found for supplied session key. summary: Session not found value: success: false error: userid for sessionkey not found errno: '30200' error-7: description: Session key is not in correct format. summary: Session invalid value: success: false error: sessionkey is invalid errno: '30300' error-8: description: A panel needs to be selected before calling this method. summary: Panel not found value: success: false error: You must select a panel before you can use this method. errno: '40001' /api.pro#method=integration.panelist.update: post: operationId: panelistUpdate summary: Update a panelist description: | Update a panelist data tags: - Panelist security: - ApiKey: [] parameters: - $ref: '#/components/parameters/method' schema: enum: - integration.panelist.update requestBody: content: application/json: schema: type: object required: - sesKey - settings properties: sesKey: description: A valid login hash. type: string example: 5a15852c564933807bbd36da58071063 settings: type: array description: 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. items: required: - label - name type: object properties: label: type: string description: A valid datapoint label or panelist field. name: type: string description: The answer to set for the label. example: - 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 responses: '200': description: OK content: application/json: schema: oneOf: - $ref: '#/components/schemas/error' - type: object properties: success: type: boolean examples: success: summary: Success value: success: true error-0: description: An identifier or email address needs to be supplied to find the panelist. summary: Identifier/Email missing value: success: false error: An identifier or email must be provided in order to update a panelist. errno: '0' error-1: description: The supplied checkbox answer is not a numeric or string integers separated by commas ("1,2,3"). summary: Settings checkbox answer invalid value: success: false error: Supplied choice is invalid errno: '0' error-2: description: The supplied settings radio answer is not numeric. summary: Settings radio answer invalid value: success: false error: Supplied choice(answer) is invalid for data point (datapoint label). The value must be an unsigned integer or NULL. errno: '0' error-3: description: The supplied radio or checkbox answer is not in choice range. summary: Settings radio/checkbox answer invalid value: success: false error: 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). errno: '0' error-4: description: One of the supplied settings labels is not found for any datapoints. summary: Settings label not found value: success: false error: Unknown datapoint label (label). errno: '20000' error-5: description: The subscribed is invalid. Subscribed can only be set to "yes" or "no". summary: Settings subscribed invalid value: success: false error: The supplied value for label 'subscribed' is invalid errno: '20000' error-6: description: The supplied date answer was not in valid date format (YYYY-MM-DD). summary: Settings date answer invalid value: success: false error: The supplied date (answer) was invalid for (datapoint label) (date) errno: '20000' error-7: description: The supplied openend answer is not a string. summary: Settings openend answer invalid value: success: false error: The data type (answer type) is not valid for (datapoint label) (openend) errno: '20000' error-8: description: The supplied timezone is not valid timezone. summary: Settings timezone invalid value: success: false error: Unknown or bad timezone errno: '20000' error-9: description: The supplied settings array does not contain datapoint array(s) with "label" and/or "answer". summary: Settings invalid value: success: false error: Panelist datapoint data is malformed! errno: '20102' error-10: description: The supplied settings array contains datapoint array(s) with arrays or objects for "answer". summary: Settings invalid value: success: false error: Answer data is in invalid format! errno: '20102' error-11: description: Session has expired. summary: Session expired value: success: false error: Session has expired. You must start a new session. errno: '30100' error-12: description: Session is not found for supplied session key. summary: Session not found value: success: false error: sessionkey not found errno: '30200' error-13: description: User ID not found for supplied session key. summary: Session not found value: success: false error: userid for sessionkey not found errno: '30200' error-14: description: Session key is not in correct format. summary: Session invalid value: success: false error: sessionkey is invalid errno: '30300' error-15: description: A panel needs to be selected before calling this method. summary: Panel not found value: success: false error: You must select a panel before you can use this method. errno: '40001' error-16: description: Panelist with supplied email address is not found. summary: Panelist not found value: success: false error: Invalid email! User not found. errno: '40010' error-17: description: Panelist with supplied identifier is not found. summary: Panelist not found value: success: false error: Invalid identifier! User not found. errno: '40010' /api.pro#method=integration.panelist.bulkupdate: post: operationId: panelistBulkUpdate summary: Update datapoints for multiple panelists description: | Update datapoints for multiple panelists.
Depending on the amount of panelist records that are being changed, this call can take a few minutes to complete. It will, however, immediately return a token that can be used to check the status of the process and verify whether there were any issues. tags: - Panelist security: - ApiKey: [] parameters: - $ref: '#/components/parameters/method' schema: enum: - integration.panelist.bulkupdate requestBody: content: application/json: schema: type: object required: - sesKey - settings properties: sesKey: description: A valid login hash. type: string example: '[your sesKey]' settings: type: array description: An array of panelist records you wish to update.
Each "row" represents a single panelist and must contain label/answer objects.
The included labels must match for all panelists in the list.
The panelist’s identifier or email address must always be included. items: type: array items: required: - label - answer type: object properties: label: type: string description: A valid datapoint label or panelist field. answer: type: string description: The answer to set for the label. example: - - label: identifier answer: identifier_1 - label: Qfirstname answer: Alida - label: Qlastname answer: Beaver - label: Qhouseholdappliances answer: 1,2,5 - label: Qgender answer: 2 - - label: identifier answer: identifier_2 - label: Qfirstname answer: Neil - label: Qlastname answer: Toth - label: Qhouseholdappliances answer: 2,5,6 - label: Qgender answer: 1 responses: '200': description: OK content: application/json: schema: oneOf: - $ref: '#/components/schemas/error' - type: object properties: success: type: boolean description: ' ' token: type: string description: A token which can be used with integration.token.get to check the status of the operation. examples: success-0: summary: Success value: success: true token: 5ix2h091vv8ckg4044sg00c0g error-0: description: '' summary: Label invalid, must be a string. value: success: false error: Invalid label errno: '0' error-1: description: '' summary: Label invalid, must exist. value: success: false error: 'Unknown datapoint label: <label>' errno: '0' error-2: description: '' summary: Data invalid, consult the manual. value: success: false error: 'Invalid data structure (line: nnn)' errno: '0' error-3: description: '' summary: Data invalid. "label" missing in the answer / label object. value: success: false error: 'Invalid data structure: label not found (line: nnn)' errno: '0' error-4: description: '' summary: Data invalid. "answer" missing in the answer / label object. value: success: false error: 'Invalid data structure: answer not found (line: nnn)' errno: '0' error-5: description: '' summary: Data invalid. Label / answer not there. value: success: false error: 'Label / answer array expected (line: %u)' errno: '0' error-6: description: '' summary: All panelist records must include the same "labels". value: success: false error: 'Unexpected label found (line: nnn)' errno: '0' error-7: description: '' summary: One or more choices for a checkbox datapoint are invalid. value: success: false error: 'Invalid choice found (line: nnn)' errno: '0' /api.pro#method=integration.panelist.rewardPointsAdd: post: operationId: panelistRewardPointsAdd summary: Add points description: | 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. tags: - Panelist security: - ApiKey: [] parameters: - $ref: '#/components/parameters/method' schema: enum: - integration.panelist.rewardPointsAdd requestBody: content: application/json: schema: type: object required: - sesKey - index - points - note properties: sesKey: description: A valid login hash. type: string example: 5a15852c564933807bbd36da58071063 index: description: Panelist identifier or PID. type: string example: '34359' points: description: Points to add type: integer example: 50 note: description: Note that will be visible to the panelists and show in the reward history. type: string example: Participation bonus indexType: description: The type of index being used enum: - identifier - pid example: identifier responses: '200': description: OK content: application/json: schema: oneOf: - $ref: '#/components/schemas/error' - type: object properties: success: type: boolean examples: success: summary: Success value: success: true error-0: description: The supplied index type is invalid. Index type can only be set to "pid" or "identifier". summary: Index type invalid value: success: false error: Invalid index type errno: '20100' error-1: description: The supplied panelist ID is not numeric. summary: Panelist ID invalid value: success: false error: Panelist Id is invalid errno: '20102' error-2: description: Panelist with supplied identifier is not found. summary: Panelist not found value: success: false error: Panelist not found errno: '20203' error-3: description: The supplied points value is not greater than 0. summary: Points invalid value: success: false error: Number of points to add must be positive errno: '20203' error-4: description: Session has expired. summary: Session expired value: success: false error: Session has expired. You must start a new session. errno: '30100' error-5: description: Session is not found for supplied session key. summary: Session not found value: success: false error: sessionkey not found errno: '30200' error-6: description: User ID not found for supplied session key. summary: Session not found value: success: false error: userid for sessionkey not found errno: '30200' error-7: description: Session key is not in correct format. summary: Session invalid value: success: false error: sessionkey is invalid errno: '30300' error-8: description: A panel needs to be selected before calling this method. summary: Panel not found value: success: false error: You must select a panel before you can use this method. errno: '40001' error-9: description: Panelist with supplied panelist ID is not found. summary: Panelist not found value: success: false error: 'No data found for Panelist ID: (panelist ID)' errno: '40010' /api.pro#method=integration.panelist.rewardPointsDeduct: post: operationId: panelistRewardPointsDeduct summary: Deduct points description: | 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. tags: - Panelist security: - ApiKey: [] parameters: - $ref: '#/components/parameters/method' schema: enum: - integration.panelist.rewardPointsDeduct requestBody: content: application/json: schema: type: object required: - sesKey - index - points - note properties: sesKey: description: A valid login hash. type: string example: 5a15852c564933807bbd36da58071063 index: description: Panelist identifier or PID. type: string example: '34359' points: description: Points to deduct (must be negative) type: integer example: -50 note: description: Note that will be visible to the panelists and show in the reward history. type: string example: Gift card redemption indexType: description: The type of index being used enum: - identifier - pid example: identifier responses: '200': description: OK content: application/json: schema: oneOf: - $ref: '#/components/schemas/error' - type: object properties: success: type: boolean examples: success: summary: Success value: success: true error-0: description: The supplied index type is invalid. Index type can only be set to "pid" or "identifier". summary: Index type invalid value: success: false error: Invalid index type errno: '20100' error-1: description: The supplied panelist ID is not numeric. summary: Panelist ID invalid value: success: false error: Panelist Id is invalid errno: '20102' error-2: description: Panelist with supplied identifier is not found. summary: Panelist not found value: success: false error: Panelist not found errno: '20203' error-3: description: The supplied points value is not less than 0. summary: Points invalid value: success: false error: Number of points to deduct must be negative errno: '20203' error-4: description: Session has expired. summary: Session expired value: success: false error: Session has expired. You must start a new session. errno: '30100' error-5: description: Session is not found for supplied session key. summary: Session not found value: success: false error: sessionkey not found errno: '30200' error-6: description: User ID not found for supplied session key. summary: Session not found value: success: false error: userid for sessionkey not found errno: '30200' error-7: description: Session key is not in correct format. summary: Session invalid value: success: false error: sessionkey is invalid errno: '30300' error-8: description: A panel needs to be selected before calling this method. summary: Panel not found value: success: false error: You must select a panel before you can use this method. errno: '40001' error-9: description: Panelist with supplied panelist ID is not found. summary: Panelist not found value: success: false error: 'No data found for Panelist ID: (panelist ID)' errno: '40010' /api.pro#method=integration.panelist.rewardPointsBalance: post: operationId: panelistRewardPointsBalance summary: Get reward point balance description: | 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. tags: - Panelist security: - ApiKey: [] parameters: - $ref: '#/components/parameters/method' schema: enum: - integration.panelist.rewardPointsBalance requestBody: content: application/json: schema: type: object required: - sesKey - index - points - note properties: sesKey: description: A valid login hash. type: string example: 5a15852c564933807bbd36da58071063 index: description: Panelist identifier or PID. type: string example: '34359' indexType: description: The type of index being used enum: - identifier - pid example: identifier responses: '200': description: OK content: application/json: schema: oneOf: - $ref: '#/components/schemas/error' - type: object properties: success: type: boolean data: type: object properties: balance: type: number examples: success: summary: Success value: success: true data: balance: 9001 error-0: description: The supplied index type is invalid. Index type can only be set to "pid" or "identifier". summary: Index type invalid value: success: false error: Invalid index type errno: '20100' error-1: description: The supplied panelist ID is not numeric. summary: Panelist ID invalid value: success: false error: Panelist Id is invalid errno: '20102' error-2: description: Panelist with supplied identifier is not found. summary: Panelist not found value: success: false error: Panelist not found errno: '20203' error-3: description: Session has expired. summary: Session expired value: success: false error: Session has expired. You must start a new session. errno: '30100' error-4: description: Session is not found for supplied session key. summary: Session not found value: success: false error: sessionkey not found errno: '30200' error-5: description: User ID not found for supplied session key. summary: Session not found value: success: false error: userid for sessionkey not found errno: '30200' error-6: description: Session key is not in correct format. summary: Session invalid value: success: false error: sessionkey is invalid errno: '30300' error-7: description: A panel needs to be selected before calling this method. summary: Panel not found value: success: false error: You must select a panel before you can use this method. errno: '40001' /api.pro#method=integration.panelist.contactFrequenciesGet: post: operationId: panelistContactFrequenciesGet summary: Get panelist contact frequencies description: | 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 return points from an incorrect panelist.

**Notice:** Panelists don't have a contact frequencies record by default. tags: - Panelist security: - ApiKey: [] parameters: - $ref: '#/components/parameters/method' schema: enum: - integration.panelist.contactFrequenciesGet requestBody: content: application/json: schema: type: object required: - sesKey - index properties: sesKey: description: A valid login hash. type: string example: 5a15852c564933807bbd36da58071063 index: description: Panelist identifier or PID. type: string example: '34359' indexType: description: The type of index being used enum: - identifier - pid example: identifier responses: '200': description: OK content: application/json: schema: oneOf: - $ref: '#/components/schemas/error' - type: object properties: success: type: boolean description: Retrieving the contact frequencies was successful. maxMessages: type: integer description: The number of messages the panelist wants to receive in the specified time frame. nextMessage: type: string description: Date string of the projected time, when panelist is ready to receive the next email invitation. pattern: ^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}$ timeFrame: type: string enum: - week - day description: The time frame. SMSFrom: type: string pattern: ^\d{2}:\d{2}:\d{2}$ description: The time when it is acceptable to start sending SMS to the panelist. SMSTo: type: string pattern: ^\d{2}:\d{2}:\d{2}$ description: The time after which the panelist does not wish to receive SMS. examples: success: summary: Success value: success: true maxMessages: 5 nextMessage: '2014-12-08 11:34:00' timeFrame: week SMSFrom: '09:00:00' SMSTo: '21:00:00' error-0: description: The supplied index type is invalid. Index type can only be set to "pid" or "identifier". summary: Index type invalid value: success: false error: Invalid index type errno: '20100' error-1: description: The supplied panelist ID is not numeric. summary: Panelist ID invalid value: success: false error: Panelist Id is invalid errno: '20102' error-2: description: Panelist with supplied identifier is not found. summary: Panelist not found value: success: false error: Panelist not found errno: '20203' error-3: description: Session has expired. summary: Session expired value: success: false error: Session has expired. You must start a new session. errno: '30100' error-4: description: Session is not found for supplied session key. summary: Session not found value: success: false error: sessionkey not found errno: '30200' error-5: description: User ID not found for supplied session key. summary: Session not found value: success: false error: userid for sessionkey not found errno: '30200' error-6: description: Session key is not in correct format. summary: Session invalid value: success: false error: sessionkey is invalid errno: '30300' error-7: description: A panel needs to be selected before calling this method. summary: Panel not found value: success: false error: You must select a panel before you can use this method. errno: '40001' /api.pro#method=integration.panelist.contactFrequenciesSet: post: operationId: panelistContactFrequenciesSet summary: Set the contact frequencies description: | 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. tags: - Panelist security: - ApiKey: [] parameters: - $ref: '#/components/parameters/method' schema: enum: - integration.panelist.contactFrequenciesSet requestBody: content: application/json: schema: type: object required: - sesKey - index - maxMessages - timeFrame properties: sesKey: description: A valid login hash. type: string example: ce512c91 index: description: Panelist identifier or PID. type: string example: '34359' maxMessages: example: 5 type: integer description: The number of messages the panelist wants to receive in the specified time frame. timeFrame: example: week type: string description: The time frame. SMSFrom: description: The time when it is acceptable to start sending SMS to the panelist. type: string pattern: ^\d{2}:\d{2}:\d{2}$ example: '09:00:00' SMSTo: description: The time after which the panelist does not wish to receive SMS. type: string pattern: ^\d{2}:\d{2}:\d{2}$ example: '21:00:00' indexType: description: The type of index being used enum: - identifier - pid example: identifier responses: '200': description: OK content: application/json: schema: oneOf: - $ref: '#/components/schemas/error' - type: object properties: success: type: boolean examples: success: summary: Success value: success: true error-0: description: The time frame is invalid. The time frame can only be set to "day" or "week". summary: Time frame invalid value: success: false error: Time frame out of range, allowed values are 'day' and 'week' errno: '0' error-1: description: 'Missing a time constraint: SMSFrom or SMSTo.' summary: SMSFrom and SMSTo invalid value: success: false error: Both time constraints must be supplied or none. errno: '0' error-2: description: The supplied SMSFrom needs to be a valid time (HH:MM:SS). summary: SMSFrom invalid value: success: false error: Invalid time stamp received errno: '0' error-3: description: The supplied SMSTo needs to be a valid time (HH:MM:SS). summary: SMSTo invalid value: success: false error: Invalid time stamp received errno: '0' error-4: description: The supplied index type is invalid. Index type can only be set to "pid" or "identifier". summary: Index type invalid value: success: false error: Invalid index type errno: '20100' error-5: description: The supplied panelist ID is not numeric. summary: Panelist ID invalid value: success: false error: Panelist Id is invalid errno: '20102' error-6: description: Panelist with supplied identifier is not found. summary: Panelist not found value: success: false error: Panelist not found errno: '20203' error-7: description: Session has expired. summary: Session expired value: success: false error: Session has expired. You must start a new session. errno: '30100' error-8: description: Session is not found for supplied session key. summary: Session not found value: success: false error: sessionkey not found errno: '30200' error-9: description: User ID not found for supplied session key. summary: Session not found value: success: false error: userid for sessionkey not found errno: '30200' error-10: description: Session key is not in correct format. summary: Session invalid value: success: false error: sessionkey is invalid errno: '30300' error-11: description: A panel needs to be selected before calling this method. summary: Panel not found value: success: false error: You must select a panel before you can use this method. errno: '40001' /api.pro#method=integration.panelist.findByDataPoint: post: operationId: panelistIntegrationFindByDataPoint summary: Find Panelists by datapoint value description: | Finds and returns a list of panelist identifiers based on a datapoint value. # Note Providing checkbox answers will find all panelists who selected the requested choices. tags: - Panelist security: - ApiKey: [] parameters: - $ref: '#/components/parameters/method' schema: enum: - integration.panelist.findByDataPoint requestBody: required: true content: application/json: schema: type: object properties: sesKey: type: string description: A valid login hash label: type: string description: Datapoint label to filter by. answer: oneOf: - type: string - type: integer - type: array description: The answer (answer type depends on the requested datapoint type). required: - sesKey - label - answer examples: Openend example: value: sesKey: 2565b78d2d00414fa2092ba1f89d6576 label: Qfirstname answer: Jim Date example: value: sesKey: 2565b78d2d00414fa2092ba1f89d6576 label: Qbirthday answer: '1965-01-15' Radio example: value: sesKey: 2565b78d2d00414fa2092ba1f89d6576 label: Qgender answer: 1 Checkbox example: value: sesKey: 2565b78d2d00414fa2092ba1f89d6576 label: Qfood answer: - 1 - 2 - 3 responses: '200': description: OK content: application/json: schema: oneOf: - $ref: '#/components/schemas/error' - type: object properties: success: type: boolean identifiers: type: array description: Array of panelist identifiers that matched the criteria items: type: string examples: success: summary: Success value: success: true identifiers: - K_ggwp76rx67 - K_kjns874n38 error-0: description: The label was invalid summary: Datapoint label invalid value: success: false error: Invalid datapoint label errno: '0' error-1: description: The datapoint was not found summary: Datapoint not found value: success: false error: Datapoint not found errno: '0' error-2: description: The answer data type was not suitable for the datapoint summary: Answer invalid value: success: false error: Answer type mismatch errno: '0' error-3: description: The date for a date datapoint is malformed summary: Date answer invalid value: success: false error: Invalid date errno: '0' error-4: description: The supplied choices for a radio/checkbox datapoint were invalid summary: Choice answer invalid value: success: false error: Invalid choice errno: '0' error-5: description: Session has expired summary: Session expired value: success: false error: Session has expired. You must start a new session. errno: '0' error-6: description: Session is not found for supplied session key summary: Session not found value: success: false error: sessionkey not found errno: '30200' error-7: description: User ID not found for supplied session key summary: Session not found value: success: false error: userid for sessionkey not found errno: '30200' error-8: description: Session key is not in correct format summary: Session invalid value: success: false error: sessionkey is invalid errno: '30300' error-9: description: A panel needs to be selected before panelists can be queried summary: Panel not found value: success: false error: You must select a panel before you can use this method. errno: '40001' /api/integration/panels/{panelId}/panelists: get: operationId: panelistGetPanelistById summary: Retrieve Panelists description: | Results are ordered by created time descending. Newest panelists are returned first. Output is limited to 100 panelists. tags: - Panelist security: - BearerAuth: [] parameters: - name: panelId in: path required: true description: A Panel ID schema: type: integer - in: query name: filter[id] description: Filter by panelist id. schema: type: string examples: one panelist by id: value: y36uhip5r8j7 description: One panelist by identifier multiple panelists by id: value: y36uhip5r8j7,oa85aha25i,gjore8o7237,zx69g6ybzue description: Multiple panelists by identifier - in: query name: filter[pid] description: Filter by panelist pid. schema: type: string examples: one panelist by pid: value: '1' description: One panelist by pid multiple panelists by pid: value: 1,2,3,4 description: Multiple panelists by pid - in: query name: filter[email] description: Filter by panelist email. schema: type: string examples: one panelist by email: value: panelist1@forsta.com description: One panelist by email multiple panelists by email: value: panelist2@forsta.com,panelist1@forsta.com description: Multiple panelists by email - $ref: '#/components/parameters/after' responses: '200': description: OK content: application/json: schema: type: array items: type: object properties: id: type: string email: type: string phone_ok: type: boolean email_ok: type: boolean blacklisted: type: boolean subscribed: type: string enum: - 'yes' - 'no' - unconfirmed timezone: type: string joined_at: type: integer description: Unix timestamp of when the panelist opted in. source_id: type: string community_id: type: string language: type: string created_at: type: integer description: Unix timestamp of when the panelist opted in. first_participation_at: type: integer description: Unix timestamp representation of the time when the panelist first participated in a survey. last_participation_at: type: integer description: Unix timestamp representation of the last time when the panelist participated in a survey. first_invitation_at: type: integer description: Unix timestamp representation of the first time the panelist received a survey invitation. last_invitation_at: type: integer description: Unix timestamp representation of the last time the panelist received a survey invitation. unsubscribed_at: type: integer description: Unix timestamp representation of when the panelist unsubscribed. blacklisted_at: type: integer description: Unix timestamp representation of when the panelist was blacklisted. unblacklisted_at: type: integer description: Unix timestamp representation of when the panelist had its blacklisted status removed. referred_at: type: integer description: Unix timestamp representation of when the panelist was referred. first_completed_at: type: integer description: Unix timestamp representation of when the panelist completed their first survey. last_completed_at: type: integer description: Unix timestamp representation of when the panelist completed their last survey. last_points_earned_at: type: integer description: Unix timestamp representation of when the panelist earned their last points. last_survey_screened_at: type: integer description: Unix timestamp representation of the last time the panelist was screened out from a survey. invited: type: integer description: Number of surveys the panelist was invited to. started: type: integer description: Number of surveys the panelist started (regardless of whether they finished). completed: type: integer description: Number of surveys the panelist completed. screened: type: integer description: Number of surveys the panelist was screened out from (profile/quota). finished: type: integer description: Number of surveys the panelist finished (completed/quota/profile). referred_panelists: type: integer description: Number of times the panelist referred somebody else (regardless of outcome). points_earned: type: integer description: Number of points earned by the panelist since they've joined. points_available: type: integer description: Number of points currently available to the panelist. points_redeemed: type: integer description: Number of points used for redemptions. points_survey: type: integer description: Number of points earned by taking surveys. points_referral: type: integer description: Number of points earned by successfully referring other panelists. points_other: type: integer description: Number of points obtained through other means (administrative, signup bonus). example: - id: string email: string phone_ok: true email_ok: true blacklisted: true subscribed: 'yes' timezone: string joined_at: 0 source_id: string community_id: string language: string created_at: 0 first_participation_at: 0 last_participation_at: 0 first_invitation_at: 0 last_invitation_at: 0 unsubscribed_at: 0 blacklisted_at: 0 unblacklisted_at: 0 referred_at: 0 first_completed_at: 0 last_completed_at: 0 last_points_earned_at: 0 last_survey_screened_at: 0 invited: 0 started: 0 completed: 0 screened: 0 finished: 0 referred_panelists: 0 points_earned: 0 points_available: 0 points_redeemed: 0 points_survey: 0 points_referral: 0 points_other: 0 '400': description: Supplied property was invalid. The error message should return more information about what went wrong. content: application/json: schema: type: object properties: error: example: string type: string '401': description: Access token is missing or invalid '404': description: The supplied resource id was not found /api/integration/panels/{panelId}/panelists/{panelistHash}: delete: operationId: panelistDeletePanelistById summary: Delete Panelists description: | Mark panelist to be deleted, allow 24 to 48 hours for full deletion. Panelist will still appear in reports until they have been permanently cleared out by the application. tags: - Panelist security: - BearerAuth: [] parameters: - name: panelId in: path required: true description: A Panel ID schema: type: integer - name: panelistHash in: path required: true description: A Panelist Identifier schema: type: integer responses: '200': description: OK '401': description: Access token is missing or invalid '404': description: The supplied resource id was not found /api/integration/panels/{panelId}/panelists/oidc/{oidcName}/{sub}: delete: operationId: panelistDeletePanelistByOidcSubject summary: Delete Panelist by OIDC subject description: | Mark the panelist identified by the given OIDC login integration name and subject to be deleted, allow 24 to 48 hours for full deletion. Panelist will still appear in reports until they have been permanently cleared out by the application. `oidcName` and `sub` are a composite key: together they identify a single panelist. tags: - Panelist security: - BearerAuth: [] parameters: - name: panelId in: path required: true description: A Panel ID schema: type: integer - name: oidcName in: path required: true description: The name of an OIDC login integration configured for the panel schema: type: string - name: sub in: path required: true description: The OIDC subject identifier of the panelist schema: type: string responses: '200': description: OK content: application/json: schema: type: object properties: success: type: boolean example: success: true '401': description: Access token is missing or invalid '404': description: | The panel id, OIDC login integration name or subject was not found. The error message should provide detail about which parameter failed. content: application/json: schema: type: object properties: error: type: string /api/integration/panels/{panelId}/panelists/{panelistId}/datapoints: get: operationId: panelistGetPanelistDatapoints summary: Retrieve Datapoints description: | Output datapoints. tags: - Panelist security: - BearerAuth: [] parameters: - name: panelId in: path required: true description: A Panel ID schema: type: integer - name: panelistHash in: path required: true description: Panelist's Hash schema: type: string - in: query name: filter[label] required: true description: Labels of datapoint to be retrieved schema: type: string examples: one datapoint: value: Label1 description: One labels multiple datapoint: value: Label1,Label2 description: Multiple labels - in: query name: choice_format required: false description: Format of answers. Allowed values are choice_id, export_values, choice_text. schema: type: string examples: choice id: value: choice_id description: datapoint’s choice ID export values: value: export_values description: datapoint’s export value (if it is not defined choice ID will be returned) choice text: value: choice_text description: datapoint’s text responses: '200': description: OK content: application/json: schema: type: array items: type: object properties: label: type: string answer: type: string example: - label: string answer: string '400': description: Supplied property was invalid. The error message should return more information about what went wrong. content: application/json: schema: type: object properties: error: example: string type: string '401': description: Access token is missing or invalid '404': description: The supplied resource id was not found /api/integration/panels/{panelId}/activities: get: operationId: panelistActivityByPanelId summary: Retrieve Panelist Survey Activity description: | Results are ordered to show most recently created survey activity first. tags: - Panelist security: - BearerAuth: [] parameters: - $ref: '#/components/parameters/panelid' - in: query name: filter[id] required: false description: Filter by activity id schema: type: string - $ref: '#/components/parameters/projectidfilter' - $ref: '#/components/parameters/panelistidfilter' - in: query name: filter[status] required: false description: |- Filter by activity status. Valid values are: - pending - invited - started - profile - quota - completed To filter by multiple statuses, provide them as a comma separated list. schema: type: string examples: Single status: value: filter[status]=completed description: Get only activities which resulted in a complete. summary: Single status Multiple statuses: value: filter[status]=started,profile,quota,completed description: Get only activities where panelists clicked the invite. summary: Multiple statuses - in: query name: filter[status_changed_at][gt] required: false description: |- Filter the `status_changed_at` timestamp by values greater than what you provided. Expected value is a Unix Timestamp. The `gt` filter value is not inclusive, i.e. it is not "greater than or equal". schema: type: integer examples: Example 1: value: filter[status_changed_at][gt]=1619560879 description: 'Get only activities which occurred after (but not including): `1619560879`.' - in: query name: filter[status_changed_at][lt] required: false description: |- Filter the `status_changed_at` timestamp by values less than what you provided. Expected value is a Unix Timestamp. The `lt` filter value is not inclusive, i.e. it is not "less than or equal". schema: type: integer examples: Example 1: value: filter[status_changed_at][lt]=1619560879 description: 'Get only activities which occurred before (but not including): `1619560879`.' - $ref: '#/components/parameters/after' responses: '200': description: OK content: application/json: schema: type: array items: type: object properties: id: type: string status: type: string started_at: type: integer status_changed_at: type: integer panelist_id: type: string project_id: type: string example: - id: string status: pending started_at: 0 status_changed_at: 0 panelist_id: string project_id: string '400': description: Supplied property was invalid. The error message should return more information about what went wrong. content: application/json: schema: type: object properties: error: example: string type: string '401': description: Access token is missing or invalid '404': description: The supplied resource id was not found /api/integration/panels/{panelId}/rewards: get: operationId: panelistGetRewards summary: Retrieve Panelist Survey Rewards description: | Results are ordered by id descending. tags: - Panelist security: - BearerAuth: [] parameters: - $ref: '#/components/parameters/panelid' - $ref: '#/components/parameters/projectidfilter' - $ref: '#/components/parameters/panelistidfilter' - in: query name: filter[id] required: false description: Filter by reward id schema: type: string - $ref: '#/components/parameters/after' responses: '200': description: OK content: application/json: schema: type: array items: type: object properties: id: type: string panelist_id: type: string project_id: type: string points: type: integer awarded_at: type: integer example: - id: string panelist_id: string project_id: string points: 0 awarded_at: 0 '400': description: Supplied property was invalid. The error message should return more information about what went wrong. content: application/json: schema: type: object properties: error: example: string type: string '401': description: Access token is missing or invalid '404': description: The supplied resource id was not found /api/integration/panels/{panelId}/panelist_datapoint_reports: post: operationId: panelistDatapointReports summary: Export datapoints/system fields for a known list of panelists by identifier description: | Export all answers for the list of datapoints and panelists provided. Instead of returning the results in the response, a report is generated with a url of where to download it from. tags: - Panelist security: - BearerAuth: [] parameters: - name: panelId in: path required: true description: A Panel ID schema: type: integer requestBody: required: true content: application/json: schema: type: object properties: panelist_ids: type: array description: An array of panelist identifiers to retrieve data for. Invalid / non-existent identifiers are omitted in the result. items: type: string datapoint_labels: type: array description: An array of datapoint labels or panelist system fields to include. Invalid / non-existent datapoints or panelist fields are ignored and not included in the result. items: type: string csv_labels_only: type: boolean default: true description: Controls if the labels for the `checkbox/multiple options` should be displayed. required: - panelist_ids - datapoint_labels example: panelist_ids: - K_00000000123 - K_00000000456 - K_00000000789 datapoint_labels: - Qfirstname - Qgender - email responses: '201': description: | Ok. The `id` value returned in the response can be used as the `reportId` parameter `GET /api/integration/panels/{panelId}/panelist_datapoint_reports/{reportId}`. content: application/json: schema: type: object properties: id: example: string type: string status: type: string enum: - waiting - running - complete - error example: waiting report_url: type: string example: string description: | URL where to download the finished report (only set when `status` is `complete`) '400': description: Supplied property was invalid. The error message should return more information about what went wrong. content: application/json: schema: type: object properties: error: example: string type: string '401': description: Access token is missing or invalid '404': description: The supplied resource id was not found /api/integration/panels/{panelId}/panelist_datapoint_reports/{reportId}: get: operationId: panelistLoadReportById summary: Load a report by its id description: | The result includes the status of the report and a URL where the report can be downloaded. The generated report will be in CSV format. tags: - Panelist security: - BearerAuth: [] parameters: - $ref: '#/components/parameters/panelid' - name: reportId in: path required: true description: reportId schema: type: integer responses: '200': description: OK content: application/json: schema: type: object properties: id: example: string type: string status: type: string enum: - waiting - running - complete - error example: waiting report_url: type: string example: string description: | URL where to download the finished report (only set when `status` is `complete`) '401': description: Access token is missing or invalid '404': description: The supplied resource id was not found /api.pro#method=integration.project.select: post: operationId: projectSelect summary: Select a project description: | Select a current project for the connection. The project will stay selected for all consecutive actions. Look for standard return for success or failure. tags: - Project security: - ApiKey: [] parameters: - $ref: '#/components/parameters/method' schema: enum: - integration.project.select requestBody: content: application/json: schema: type: object required: - sesKey - projectid properties: sesKey: description: A valid login hash. type: string example: 5a15852c564933807bbd36da58071063 projectid: description: The id of the project to select. type: integer example: 1 responses: '200': description: OK content: application/json: schema: oneOf: - $ref: '#/components/schemas/error' - type: object properties: success: type: boolean examples: success: summary: Success value: success: true error-0: description: The supplied project ID is not numeric. summary: Project ID invalid value: success: false error: Invalid project id (project ID) errno: '20102' error-1: description: Project with supplied project ID is not found in selected panel. summary: Project ID not found value: success: false error: Project (project ID) not found in panel (selected panel ID) errno: '20302' error-2: description: Session has expired. summary: Session expired value: success: false error: Session has expired. You must start a new session. errno: '30100' error-3: description: Session is not found for supplied session key. summary: Session not found value: success: false error: sessionkey not found errno: '30200' error-4: description: User ID not found for supplied session key. summary: Session not found value: success: false error: userid for sessionkey not found errno: '30200' error-5: description: Session key is not in correct format. summary: Session invalid value: success: false error: sessionkey is invalid errno: '30300' error-6: description: A panel needs to be selected before calling this method. summary: Panel not found value: success: false error: You must select a panel before you can use this method. errno: '40001' /api.pro#method=integration.project.rewards: post: operationId: projectRewards summary: Get a list of rewards description: | Get a list of reward points that were given out for the currently selected project. tags: - Project security: - ApiKey: [] parameters: - $ref: '#/components/parameters/method' schema: enum: - integration.project.rewards requestBody: content: application/json: schema: type: object required: - sesKey properties: sesKey: description: A valid login hash. type: string example: 5a15852c564933807bbd36da58071063 responses: '200': description: OK content: application/json: schema: oneOf: - $ref: '#/components/schemas/error' - type: object properties: success: example: true type: boolean data: type: array items: type: object properties: identifier: type: string points: type: integer date: type: string pattern: ^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}$ examples: success: summary: Success value: success: true data: - identifier: K_s93807bx3dt points: 100 date: '2020-12-22 13:43:00' - identifier: K_d36ya580w10 points: 10 date: '2020-12-22 13:43:00' - identifier: K_54er357gw1q points: 100 date: '2020-12-22 13:43:00' /api.pro#method=integration.project.create: post: operationId: projectCreate summary: Create a project description: | Create a new project in the currently selected panel. tags: - Project security: - ApiKey: [] parameters: - $ref: '#/components/parameters/method' schema: enum: - integration.project.create requestBody: required: true content: application/json: schema: type: object properties: sesKey: type: string description: A valid login hash. settings: type: object description: An associative array containing project settings (listed below). properties: name: type: string description: Project name. URL: type: string format: url description: Project URL, including replacable parameters description: type: string description: Project description. clientId: type: integer description: id must already exist in the panel. defaultPointsCompleted: type: integer description: Default number of points awarded for survey completion. defaultPointsProfile: type: integer description: Default number of points awarded when respondent is profile terminated. defaultPointsQuota: type: integer description: Default number of points awarded when respondent is quota terminated. defaultMaxParticipation: type: integer description: Default number of times respondent can take survey. (0 is unlimited) receiveEncryptType: type: string description: invitation link encryption. terminationEncryptType: type: string description: termination link encryption. secret: type: string description: secret key used for encryption. (should be set to the same value for the survey) required: - name - URL categories: type: array description: An array of category IDs that the project will be assigned to. (Category IDs can be obtained by calling `integration.category.listing`) items: type: integer required: - sesKey - settings example: sesKey: 5a15852c564933807bbd36da58071063 settings: name: First Project url: https://web.example.com/?identifier=[IDENTIFIER]&sesskey=[sesskey] categories: - 1 - 2 - 42 responses: '200': description: OK content: application/json: schema: oneOf: - $ref: '#/components/schemas/error' - type: object properties: success: type: boolean data: type: object properties: projectid: type: integer description: Unique project identifier examples: success: summary: Success value: success: true data: projectid: 3 error-0: description: The supplied settings array contains a key that is not valid for project settings. summary: Settings invalid value: success: false error: Invalid property (settings) errno: '10000' error-1: description: The supplied settings default max participation is not numeric. summary: Settings default max participation invalid value: success: false error: defaultmaxparticipation (settings default max participation) must be numeric errno: '10000' error-2: description: The supplied default points quota is not numeric. summary: Settings default points quota invalid value: success: false error: defaultpointsquota (settings default points quota) must be numeric errno: '10000' error-3: description: The supplied default points profile is not numeric. summary: Settings default points profile invalid value: success: false error: defaultpointsprofile (settings default points profile) must be numeric errno: '10000' error-4: description: The supplied default points completed is not numeric. summary: Settings default points completed invalid value: success: false error: default points completed (settings default points completed) must be numeric errno: '10000' error-5: description: The supplied settings name is empty. summary: Empty settings name value: success: false error: Invalid project name. Project name can not be empty. errno: '10000' error-6: description: The supplied settings name is more than 100 characters in length. summary: Settings name invalid value: success: false error: Invalid project name (settings name) length. Can not be longer than 100 characters. errno: '10000' error-7: description: The supplied settings URL is empty. summary: Empty settings URL value: success: false error: Project URL must be set before calling save errno: '10000' error-8: description: The supplied client ID is not numeric. summary: Settings client ID invalid value: success: false error: clientid (settings client ID) must be a positive number or null errno: '10000' error-9: description: Client with supplied client ID is not found. summary: Client not found value: success: false error: Invalid clientid (settings client ID) client does not exist errno: '10000' error-10: description: The supplied settings URL is not a valid URL. summary: Setting URL invalid value: success: false error: URL (settings URL) is not a properly formatted URL errno: '10000' error-11: description: The supplied settings URL does not contain "sesskey" parameter. The URL must contain "sesskey" for activity tracking. summary: Settings URL invalid value: success: false error: 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. errno: '10000' error-12: description: The supplied settings description is more than 65536 characters in length. summary: Settings description invalid. value: success: false error: Invalid project description (settings description) length. Can not be longer than 65k characters errno: '10000' error-13: description: The supplied settings secret is more than 255 characters in length. summary: Settings secret invalid value: success: false error: Invalid secret hash salt (settings secret) can not be longer than 255 characters errno: '10000' error-14: description: The supplied settings receive encrypt type is not valid. Receive encrypt type can only be "md5" or "none". summary: Settings receive encrypt type invalid value: success: false error: 'Invalid recencrypttype (settings receive encrypt type) value. Allowed values are: md5, none' errno: '10000' error-15: description: The supplied settings termination encrypt type is not valid. Termination encrypt type can only be "md5" or "none". summary: Settings termination encrypt type invalid value: success: false error: 'Invalid recencrypttype (settings termination encrypt type) value. Allowed values are: md5, none' errno: '10000' error-16: description: The supplied categories contains one or more values that are not numeric. summary: Categories invalid value: success: false error: Invalid category id(category ID) errno: '20102' error-17: description: One or more categories from supplied categories are not found. summary: Category not found value: success: false error: Supplied category id(category ID) not found. errno: '20103' error-18: description: The supplied settings is not an array. summary: Settings invalid value: success: false error: The "project" parameter is of an unexpected type (settings type). Please use an appropriate object or array, as described in the documentation. errno: '20102' error-19: description: Session has expired. summary: Session expired value: success: false error: Session has expired. You must start a new session. errno: '30100' error-20: description: Session is not found for supplied session key. summary: Session not found value: success: false error: sessionkey not found errno: '30200' error-21: description: User ID not found for supplied session key. summary: Session not found value: success: false error: userid for sessionkey not found errno: '30200' error-22: description: Session key is not in correct format. summary: Session invalid value: success: false error: sessionkey is invalid errno: '30300' error-23: description: A panel needs to be selected before calling this method. summary: Panel not found value: success: false error: You must select a panel before you can use this method. errno: '40001' /api.pro#method=integration.project.close: post: operationId: projectClose summary: Close project description: | 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). tags: - Project security: - ApiKey: [] parameters: - $ref: '#/components/parameters/method' schema: enum: - integration.project.close requestBody: content: application/json: schema: type: object required: - sesKey - projectid properties: sesKey: description: A valid login hash. type: string example: 5a15852c564933807bbd36da58071063 projectid: description: The id of the project to close. type: integer example: 1 responses: '200': description: OK content: application/json: schema: oneOf: - $ref: '#/components/schemas/error' - type: object properties: success: example: true type: boolean examples: success: summary: Success value: success: true error-0: description: Project with supplied project ID is not found in selected panel. summary: Project ID not found value: success: false error: The specified projectid does not exist errno: '10000' error-1: description: The supplied project ID is not numeric. summary: Project ID invalid value: success: false error: Project ID must be numeric! errno: '20102' error-2: description: Session has expired. summary: Session expired value: success: false error: Session has expired. You must start a new session. errno: '30100' error-3: description: Session is not found for supplied session key. summary: Session not found value: success: false error: sessionkey not found errno: '30200' error-4: description: User ID not found for supplied session key. summary: Session not found value: success: false error: userid for sessionkey not found errno: '30200' error-5: description: Session key is not in correct format. summary: Session invalid value: success: false error: sessionkey is invalid errno: '30300' error-6: description: A panel needs to be selected before calling this method. summary: Panel not found value: success: false error: You must select a panel before you can use this method. errno: '40001' /api/integration/panels/{panelId}/projects/{projectId}/stats/delivery: get: operationId: projectStatsDelivery summary: Project delivery statistics. description: | Get stats covering message delivery for one particular project. tags: - Project security: - BearerAuth: [] parameters: - name: panelId in: path required: true description: A Panel ID schema: type: string - name: projectId in: path required: true description: A Project ID schema: type: string responses: '200': description: OK content: application/json: schema: type: object properties: delivered: type: object properties: count: type: boolean percent: type: boolean pending: type: object properties: count: type: boolean percent: type: boolean bounced: type: object properties: count: type: boolean percent: type: boolean deferred: type: object properties: count: type: boolean percent: type: boolean unknown: type: object properties: count: type: boolean percent: type: boolean delayed: type: object properties: count: type: boolean percent: type: boolean example: delivered: count: 28 percent: 0.7 pending: count: 0 percent: 0 bounced: count: 5 percent: 0.125 deferred: count: 3 percent: 0.075 unknown: count: 0 percent: 0 delayed: count: 4 percent: 0.1 '401': description: Access token is missing or invalid '404': description: Panel or project id were not found /api/integration/panels/{panelId}/projects/{projectId}/stats/reward: get: operationId: projectStatsReward summary: Project reward statistics. description: | Get stats covering panelist reward distribution for one particular project. security: - BearerAuth: [] tags: - Project parameters: - name: panelId in: path required: true description: A Panel ID schema: type: string - name: projectId in: path required: true description: A Project ID schema: type: string responses: '200': description: OK content: application/json: schema: type: object properties: completed: type: object properties: points: type: boolean profile: type: object properties: points: type: boolean quota: type: object properties: points: type: boolean example: completed: points: 23000 profile: points: 50 quota: points: 0 '401': description: Access token is missing or invalid '404': description: Panel or project id were not found /api/integration/panels/{panelId}/projects/{projectId}/stats/activity: get: operationId: projectStatsActivity summary: Project activity statistics. description: | Get stats covering panelist activity for one particular project.
The percentages are based on the total number of panelists that were invited to the project. tags: - Project security: - BearerAuth: [] parameters: - name: panelId in: path required: true description: A Panel ID schema: type: string - name: projectId in: path required: true description: A Project ID schema: type: string responses: '200': description: OK content: application/json: schema: type: object properties: completed: type: object properties: count: type: boolean percent: type: boolean profile: type: object properties: count: type: boolean percent: type: boolean quota: type: object properties: count: type: boolean percent: type: boolean started: type: object properties: count: type: boolean percent: type: boolean invited: type: object properties: count: type: boolean percent: type: boolean example: completed": count: 23 percent: 0.153 profile: count: 5 percent: 0.033 quota: count: 0 percent: 0 started: count: 7 percent: 0.047 invited: count: 75 percent: 0.767 '401': description: Access token is missing or invalid '404': description: Panel or project id were not found /api.pro#method=integration.project.listing: post: operationId: projectListing summary: List all Projects description: | List all Projects. tags: - Project security: - ApiKey: [] parameters: - $ref: '#/components/parameters/method' schema: enum: - integration.project.listing requestBody: content: application/json: schema: type: object required: - sesKey properties: sesKey: description: A valid login hash. type: string example: 5a15852c564933807bbd36da58071063 responses: '200': description: OK content: application/json: schema: oneOf: - $ref: '#/components/schemas/error' - type: object properties: success: type: boolean data: type: array description: An array of objects, each of which is a project containing project data. items: properties: id: type: integer description: Project ID. name: type: string description: Project name. status: type: string enum: - open - closed description: Project status. Projects marked as 'completed' are returned as 'open' until they are closed. created: type: string description: The project's date of creation. pattern: ^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}$ completed: type: - string - 'null' description: 'The date and time on which the project marked as completed. Null, if the project was never marked complete. "Completed" projects will not allow panelists to start new sessions, but will allow additional completes until the defined grace period (Default: 2h) has passed.' pattern: ^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}$ closed: type: - string - 'null' description: The date and time on which the project was closed. Null, if the project was never closed or has been reopened. Closed projects will not allow panelists to start new sessions or finish them. pattern: ^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}$ created_by: type: string description: The user who created the project. categories: type: array description: An array of category IDs that the project belongs to. (Category IDs can be obtained by calling integration.category.listing) items: type: integer examples: success: summary: Success value: success: true data: - id: 1 name: foo's new project status: open created: '2011-10-14 12:13:13' completed: null 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' completed: '2020-12-22 15:48:00' closed: '2020-12-22 17:48:00' created_by: Kinesis Tester categories: [] error-0: description: Session has expired. summary: Session expired value: success: false error: Session has expired. You must start a new session. errno: '30100' error-1: description: Session is not found for supplied session key. summary: Session not found value: success: false error: sessionkey not found errno: '30200' error-2: description: User ID not found for supplied session key. summary: Session not found value: success: false error: userid for sessionkey not found errno: '30200' error-3: description: Session key is not in correct format. summary: Session invalid value: success: false error: sessionkey is invalid errno: '30300' error-4: description: A panel needs to be selected before calling this method. summary: Panel not found value: success: false error: You must select a panel before you can use this method. errno: '40001' /api.pro#method=integration.reminder.create: post: operationId: reminderCreate summary: Create a reminder description: | Create a reminder for an existing campaign (requires existing campaign with existing scheduled invitation) tags: - Reminder security: - ApiKey: [] parameters: - $ref: '#/components/parameters/method' schema: enum: - integration.reminder.create requestBody: content: application/json: schema: type: object required: - sesKey - campaignid - messages - startDate - sampleIds properties: sesKey: description: A valid login hash. type: string example: 5a15852c564933807bbd36da58071063 campaignid: description: Name of the sample. type: integer example: 1 messages: description: A zero based array of associative arrays containing localized message data. type: array items: type: object properties: subject: type: string content: type: string locale: type: string example: - subject: The Subject content: This is the message content locale: 1 - subject: The Subject content: This is the message content locale: 2 - subject: The Subject content: This is the message content locale: 3 startDate: description: The date and time when the reminder should be sent. type: string pattern: ^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}$ example: '2011-12-24 17:40:00' sampleIds: description: Specifies which samples to send to. (If empty it will send to all sampleids in the campaign) type: array items: type: number example: - 1 - 2 - 3 responses: '200': description: OK content: application/json: schema: oneOf: - $ref: '#/components/schemas/error' - type: object properties: success: type: boolean data: properties: reminderid: type: integer examples: success: summary: Success value: success: true data: reminderid: 1 error-0: description: Campaign with supplied campaign ID is not found in selected project. summary: Campaign ID not found value: success: false error: 'No data found for Campaign ID: (campaign ID)' errno: '10000' error-1: description: The supplied messages array did not contain messages with all locales for the selected panel. summary: Messages invalid value: success: false error: Localized Reminder data must contain all locales! errno: '10000' error-2: description: The supplied campaign ID is not numeric. summary: Campaign ID invalid value: success: false error: The "campaignId" parameter is of an unexpected type (campaign ID type). Please use an integer, as described in the documentation. errno: '20102' error-3: description: The supplied messages parameter is not an array. summary: Messages invalid value: success: false error: The "messages" parameter is of an unexpected type (messages type). Please use an array, as described in the documentation. errno: '20103' error-4: description: The supplied messages locale is not numeric. summary: Messages locale invalid value: success: false error: Invalid value for locale encountered (message locale type). Please use an integer. errno: '20103' error-5: description: The supplied messages array has multiple messages with the same locale. There can only summary: Messages locale invalid value: success: false error: You have more than one message defined for locale (local ID). Message locales must be unique. errno: '20103' error-6: description: The supplied start date is not valid timestamp (YYYY-MM-DD HH:mm:ss). summary: Start date invalid value: success: false error: The "when" parameter is of an unexpected type (start date type). Please use a valid (UNIX) timestamp, as described in the documentation. errno: '20104' error-7: description: The supplied sample IDs is not an array or is null. summary: Sample IDs invalid value: success: false error: The "sampleIds" parameter is of an unexpected type (sample ID type). Please use an array, as described in the documentation. errno: '20105' error-8: description: One of the supplied sample IDs is not numeric. summary: Sample IDs invalid value: success: false error: Invalid value in "sampleId" encountered (sample ID type). Please use an array of integers, as described in the documentation. errno: '20105' error-9: description: Sample with supplied sample ID is not found. summary: Sample not found value: success: false error: The supplied sample id (sample ID) in "sampleId" is invalid or cannot be used for this campaign. errno: '20105' error-10: description: Session has expired. summary: Session expired value: success: false error: Session has expired. You must start a new session. errno: '30100' error-11: description: Session is not found for supplied session key. summary: Session not found value: success: false error: sessionkey not found errno: '30200' error-12: description: User ID not found for supplied session key. summary: Session not found value: success: false error: userid for sessionkey not found errno: '30200' error-13: description: Session key is not in correct format. summary: Session invalid value: success: false error: sessionkey is invalid errno: '30300' error-14: description: A panel needs to be selected before calling this method. summary: Panel not found value: success: false error: You must select a panel before you can use this method. errno: '40001' error-15: description: A project needs to be selected before calling this method. summary: Project not found value: success: false error: You must select a project before you can use this method. errno: '40002' /api.pro#method=integration.sample.create: post: operationId: sampleCreate summary: Create sample description: | Create a sample from panelist identifiers. tags: - Sample security: - ApiKey: [] parameters: - $ref: '#/components/parameters/method' schema: enum: - integration.sample.create requestBody: content: application/json: schema: type: object required: - sesKey - name - description - identifiers properties: sesKey: description: A valid login hash. type: string example: 5a15852c564933807bbd36da58071063 name: description: Name of the sample. type: string example: First Sample description: description: Description of the sample. type: string example: This is the First Sample identifiers: description: Zero-based array of identifiers to be included in the sample. type: array items: type: string example: - 130_FNOAHH - 131_FNOAHH - 132_FNOAHH - 133_FNOAHH - 134_FNOAHH responses: '200': description: OK content: application/json: schema: oneOf: - $ref: '#/components/schemas/error' - type: object properties: success: example: true type: boolean data: properties: sampleid: type: integer examples: success: summary: Success value: success: true data: sampleid: 1 error-0: description: The supplied name is empty. The name parameter is required. summary: Empty name value: success: false error: Please enter the name for the sample you would like to create. errno: '10000' error-1: description: The supplied identifiers array is empty. The identifiers parameter is required. summary: Empty identifiers value: success: false error: Please enter the information for samples to be added. errno: '10000' error-2: description: The supplied identifiers are not an array. summary: Identifiers invalid value: success: false error: The "identifiers" parameter is of an unexpected type (identifiers type). Please use an array, as described in the documentation. errno: '20104' error-3: description: Session has expired. summary: Session expired value: success: false error: Session has expired. You must start a new session. errno: '30100' error-4: description: Session is not found for supplied session key. summary: Session not found value: success: false error: sessionkey not found errno: '30200' error-5: description: User ID not found for supplied session key. summary: Session not found value: success: false error: userid for sessionkey not found errno: '30200' error-6: description: Session key is not in correct format. summary: Session invalid value: success: false error: sessionkey is invalid errno: '30300' error-7: description: A panel needs to be selected before calling this method. summary: Panel not found value: success: false error: You must select a panel before you can use this method. errno: '40001' error-8: description: A project needs to be selected before calling this method. summary: Project not found value: success: false error: You must select a project before you can use this method. errno: '40002' /api.pro#method=integration.sample.update: post: operationId: sampleUpdate summary: Update a sample description: | Update a sample with appended data tags: - Sample security: - ApiKey: [] parameters: - $ref: '#/components/parameters/method' schema: enum: - integration.sample.update requestBody: content: application/json: schema: type: object properties: sesKey: type: string description: A valid login hash. sampleid: type: integer description: Sample to which you want to append data. (must already exist) params: type: array description: Zero-based array containing parameter names. (i.e. value1,value2) items: type: string identifiers: type: array description: Zero-based array containing identifiers to append data to. items: type: string values: type: array description: Array of arrays, containing values for each param, for each panelist, (same order as identifier array) items: type: array items: oneOf: - type: string - type: integer required: - sesKey - sampleid - params - identifiers - values example: sesKey: 5a15852c564933807bbd36da58071063 sampleid: 1 params: - value1 - value2 - value3 identifiers: - 130_FNOAHH - 131_FNOAHH values: - - 1 - 2 - 3 - - 4 - 5 - 6 responses: '200': description: OK content: application/json: schema: oneOf: - $ref: '#/components/schemas/error' - type: object properties: success: type: boolean examples: success: summary: Success value: success: true error-0: description: The supplied parameter names should not have spaces in supplied params array. summary: Params invalid value: success: false error: Header names cannot contain spaces! (params) errno: '10000' error-1: description: The parameter names should only have numbers (0-9) or letters (A-Z or a-z) in supplied params array. summary: Params invalid value: success: false error: Header names may only contain Latin letters and numbers. (params) errno: '10000' error-2: description: The parameter names should not start with a number (0-9) in supplied params array. summary: Params invalid value: success: false error: Header names cannot start with numbers! (params) errno: '10000' error-3: description: The supplied sample ID is not numeric. summary: Sample ID invalid value: success: false error: The sampleId (sample ID) must be a number greater than zero errno: '20102' error-4: description: The supplied params is not an array. summary: Params invalid value: success: false error: The "params" parameter is of an unexpected type (params type). Please use an array, as described in the documentation. errno: '20103' error-5: description: The supplied identifier is not an array. summary: Identifiers invalid value: success: false error: The "identifiers" parameter is of an unexpected type (identifiers type). Please use an array, as described in the documentation. errno: '20104' error-6: description: The supplied identifiers and values arrays do not contain the same amount of elements. Both of these parameters must have the same element count. summary: Identifiers invalid value: success: false error: Your "identifier" array contains more/fewer elements than your "values" array. They must match. errno: '20104' error-7: description: The supplied values is not an array. summary: Values invalid value: success: false error: The "values" parameter is of an unexpected type (data type). Please use an array, as described in the documentation. errno: '20105' error-8: description: The supplied params array is empty. summary: Empty params value: success: false error: The "params" array is empty, so there is nothing to append errno: '20203' error-9: description: The supplied identifiers array is empty. summary: Empty identifiers value: success: false error: The "identifiers" array is empty, so there is nothing to append errno: '20204' error-10: description: The supplied values array is empty. summary: Empty values value: success: false error: The "values" array is empty, so there is nothing to append errno: '20205' error-11: description: Sample with supplied sample ID is not found for selected project. summary: Sample not found value: success: false error: Sample is empty errno: '20302' error-12: description: The supplied identifiers are not found in sample. summary: Indentifiers invalid value: success: false error: 'The following identifiers were not found in the sample: (identifiers)' errno: '20304' error-13: description: Session has expired. summary: Session expired value: success: false error: Session has expired. You must start a new session. errno: '30100' error-14: description: Session is not found for supplied session key. summary: Session not found value: success: false error: sessionkey not found errno: '30200' error-15: description: User ID not found for supplied session key. summary: Session not found value: success: false error: userid for sessionkey not found errno: '30200' error-16: description: Session key is not in correct format. summary: Session invalid value: success: false error: sessionkey is invalid errno: '30300' error-17: description: A panel needs to be selected before calling this method. summary: Panel not found value: success: false error: You must select a panel before you can use this method. errno: '40001' error-18: description: A project needs to be selected before calling this method. summary: Project not found value: success: false error: You must select a project before you can use this method. errno: '40002' /api.pro#method=integration.session.get: post: operationId: getSessionGet summary: Get session info using the sessionkey description: | 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. tags: - Session security: - ApiKey: [] parameters: - $ref: '#/components/parameters/method' schema: enum: - integration.session.get requestBody: content: application/json: schema: type: object required: - sesKey - sesString properties: sesKey: description: A valid login hash. type: string example: 5a15852c564933807bbd36da58071063 sesString: description: 16 character panelist session string from the URL type: string example: e0197525e7129c5c responses: '200': description: OK content: application/json: schema: oneOf: - $ref: '#/components/schemas/error' - type: object properties: success: example: true type: boolean data: example: projectid: 23 campaignid: 59 panelistid: 34359 status: started starttime: '2013-01-01 23:59:59' type: object properties: projectid: type: integer campaignid: type: integer panelistid: type: integer status: type: string starttime: type: string examples: success: summary: Success value: success: true data: projectid: 23 campaignid: 59 panelistid: 34359 status: started starttime: '2013-01-01 23:59:59' error-0: description: Session with supplied session string is not found. summary: Session string invalid value: success: false error: Session key (sesskey) is not valid errno: '20202' error-1: description: Session has expired. summary: Session expired value: success: false error: Session has expired. You must start a new session. errno: '30100' error-2: description: Session is not found for supplied session key. summary: Session not found value: success: false error: sessionkey not found errno: '30200' error-3: description: User ID not found for supplied session key. summary: Session not found value: success: false error: userid for sessionkey not found errno: '30200' error-4: description: Session key is not in correct format. summary: Session invalid value: success: false error: sessionkey is invalid errno: '30300' /api.pro#method=integration.session.update: post: operationId: getSessionUpdate summary: Update the session status using the sessionkey description: | 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. tags: - Session security: - ApiKey: [] parameters: - $ref: '#/components/parameters/method' schema: enum: - integration.session.update requestBody: content: application/json: schema: type: object required: - sesKey - sesString - status properties: sesKey: description: A valid login hash. type: string example: 5a15852c564933807bbd36da58071063 sesString: description: 16 character panelist session string from the URL type: string example: e0197525e7129c5c status: description: Set the status of the completing panelist. type: string enum: - profile - quota - started - completed example: profile points: description: Optional to supply custom number of points type: integer example: 50 note: description: 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. type: string example: Completed survey responses: '200': description: OK content: application/json: schema: oneOf: - $ref: '#/components/schemas/error' - type: object properties: success: type: boolean examples: success: summary: Success value: success: true error-0: description: Session with supplied session string is not found. summary: Session string invalid value: success: false error: Session key (sesskey) is not valid errno: '20202' error-1: description: The project is closed and status cannot be updated. summary: Project Closed value: success: false error: Project is closed errno: '20203' error-2: description: The campaign is expired and status cannot be updated. summary: Campaign Expired value: success: false error: Campaign is expired errno: '20203' error-3: description: The panelist is opted out. summary: Panelist Opted Out value: success: false error: Panelist opted out errno: '20203' error-4: description: 'The supplied status is invalid. The status must be one of the following: "profile", "quota" or "completed".' summary: Status invalid value: success: false error: Status (status) is unknown errno: '20203' error-5: description: The supplied status in valid. The panelist must have a started status before changing it to this status. summary: Status invalid value: success: false error: 'Somebody is trying to go from status: ‘(current panelist status)’ to ‘(status)’ while bypassing ''started’' errno: '20203' error-6: description: The supplied status is invalid for panelist. summary: Status invalid value: success: false error: Status can only be set higher than its current value of ‘(current panelist status)’ errno: '20203' error-7: description: The supplied status is invalid. The panelist is pending and their status can be changed to invited only. summary: Status invalid value: success: false error: A pending session can only be changed to 'invited' errno: '20203' error-8: description: The panelist exit status is already recorded. Their status cannot be changed. summary: Status invalid value: success: false error: Exit status already recorded errno: '20203' error-9: description: The supplied points value must be positive. summary: Points invalid value: success: false error: Points value must be positive errno: '20204' error-10: description: Session has expired. summary: Session expired value: success: false error: Session has expired. You must start a new session. errno: '30100' error-11: description: Session is not found for supplied session key. summary: Session not found value: success: false error: sessionkey not found errno: '30200' error-12: description: User ID not found for supplied session key. summary: Session not found value: success: false error: userid for sessionkey not found errno: '30200' error-13: description: Session key is not in correct format. summary: Session invalid value: success: false error: sessionkey is invalid errno: '30300' /api.pro#method=integration.surveys.available: post: operationId: getSurveyForPanelist summary: List survey for panelist description: | Get a list of available surveys for a panelist. tags: - Survey security: - ApiKey: [] parameters: - $ref: '#/components/parameters/method' schema: enum: - integration.surveys.available requestBody: content: application/json: schema: type: object required: - sesKey - index properties: sesKey: description: A valid login hash. type: string example: 5a15852c564933807bbd36da58071063 index: description: Panelist ID or identifier to look up the panelist. type: string example: 34359 indexType: description: The type of index being used type: string enum: - identifier - pid example: identifier responses: '200': description: OK content: application/json: schema: oneOf: - $ref: '#/components/schemas/error' - type: object properties: success: type: boolean data: type: object properties: subject: type: string description: Email subject that was used in the invitation. body: type: string description: A more detailed survey description. status: type: - string - 'null' description: '''started'' if the panelist has started, but not completed the survey, otherwise NULL.' time: type: string description: The time this portal invitation was sent. points: type: integer description: The number of points awarded for a completed survey. url: type: string format: url description: URL to take the panelist to the survey, as defined in the project. type: type: - string - 'null' enum: - emailhtml - SMS description: The type of invitation that was used. If the type is not available (portal launch only), this field will be NULL. endtime: type: string description: The time when the campaign expires and the survey links will stop working. invited: type: string description: The time when the panelist was invited. purpose: type: string enum: - invitation - automated - diary - profiler - portal description: The campaign purpose. projectid: type: integer description: The project ID examples: success: summary: Success value: 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/receiver.pro?seskey=e0197525e7129c5c type: emailhtml endtime: '2013-01-01 23:59:59' invited: '2013-01-01 23:59:59' purpose: invitation projectid: 10 error-0: description: The supplied index type is invalid. Index type can only be set to "pid" or "identifier". summary: Index type invalid value: success: false error: Invalid index type errno: '20100' error-1: description: Panelist with supplied identifier or panelist ID is not found. summary: Panelist not found value: success: false error: Panelist not found errno: '20203' error-2: description: Session has expired. summary: Session expired value: success: false error: Session has expired. You must start a new session. errno: '30100' error-3: description: Session is not found for supplied session key. summary: Session not found value: success: false error: sessionkey not found errno: '30200' error-4: description: User ID not found for supplied session key. summary: Session not found value: success: false error: userid for sessionkey not found errno: '30200' error-5: description: Session key is not in correct format. summary: Session invalid value: success: false error: sessionkey is invalid errno: '30300' /api.pro#method=integration.token.get: post: operationId: getToken summary: Get status of long running process description: | Retrieve the result or current status of a long-running import or export process. tags: - Token security: - ApiKey: [] parameters: - $ref: '#/components/parameters/method' schema: enum: - integration.token.get requestBody: content: application/json: schema: type: object required: - sesKey - token properties: sesKey: description: A valid login hash. type: string example: '[your sesKey]' token: description: The token returned by either `integration.panelist.bulkUpdate` or `integration.panelist.bulkRead` type: string example: 28timgls19hcck4sccocc8gg responses: '200': description: OK content: application/json: schema: oneOf: - $ref: '#/components/schemas/error' - type: object properties: success: type: boolean status: type: string description: The status of the process result: type: array description: The result of the process items: type: object properties: success: type: boolean errors: type: array items: type: string warnings: type: array items: type: string examples: success: summary: Success value: success: true status: complete result: [] /api/integration/panels/{panelId}/panelists/{panelistHash}/notes: get: operationId: panelistNoteGetNotes summary: Retrieve Notes for a given panelist. description: Results are ordered by id ascending. Newest notes are returned last. tags: - Notes security: - BearerAuth: [] parameters: - name: panelId in: path description: A panel Id. schema: type: integer required: true - name: panelistHash in: path description: A panelist hash. required: true schema: type: string responses: '200': description: Ok content: application/json: schema: type: array items: type: object properties: id: type: integer note: type: string example: - id: 12 note: note 1 - id: 15 note: note 2 '404': description: The panel id or panelist identifier was not found. The error message should provide detail about which parameter failed. content: application/json: schema: type: object properties: error: type: string example: error: Panel not found post: operationId: panelistNoteCreateNote summary: Create a note for a given panelist. tags: - Notes security: - BearerAuth: [] parameters: - name: panelId in: path description: A panel Id. schema: type: integer required: true - name: panelistHash in: path description: A panelist hash. required: true schema: type: string requestBody: content: application/json: schema: type: object properties: note: type: string description: Note text required: - note example: note: Text to add responses: '201': description: Ok content: application/json: schema: type: object properties: id: type: integer example: id: 12 '400': description: Invalid note was passed. content: application/json: schema: type: object properties: error: type: string example: error: Invalid note '404': description: The panel id, panelist identifier or note id was not found. The error message should provide detail about which parameter failed. content: application/json: schema: type: object properties: error: type: string example: error: Panel not found /api/integration/panels/{panelId}/panelists/{panelistHash}/notes/{noteId}: put: operationId: panelistNoteModifyNote summary: Change the text for a given panelist note. tags: - Notes security: - BearerAuth: [] parameters: - name: panelId in: path description: A panel Id. schema: type: integer required: true - name: panelistHash in: path description: A panelist hash. required: true schema: type: string - name: noteId in: path description: Note Id. required: true schema: type: string requestBody: content: application/json: schema: type: object properties: note: type: string description: Note text required: - note example: note: Text to update responses: '204': description: No response '400': description: Invalid note was passed. content: application/json: schema: type: object properties: error: type: string example: error: Invalid note '404': description: The panel id, panelist identifier or note id was not found. The error message should provide detail about which parameter failed. content: application/json: schema: type: object properties: error: type: string example: error: Panel not found delete: operationId: panelistNoteDeleteNote summary: Delete a given panelist note . tags: - Notes security: - BearerAuth: [] parameters: - name: panelId in: path description: A panel Id. schema: type: integer required: true - name: panelistHash in: path description: A panelist hash. required: true schema: type: string - name: noteId in: path description: Note Id. required: true schema: type: string responses: '204': description: No response. '404': description: The panel id, panelist identifier or note id was not found. The error message should provide detail about which parameter failed. content: application/json: schema: type: object properties: error: type: string example: error: Panel not found components: securitySchemes: BearerAuth: type: http scheme: bearer ApiKey: type: apiKey in: query name: sesKey parameters: method: name: method in: query required: true description: Method schema: type: string after: in: query name: after required: false description: Pagination parameter for cursor based pagination schema: type: string examples: example 1: value: 123 description: Request values after id 123 panelid: name: panelId in: path required: true description: A Panel ID schema: type: integer projectidfilter: in: query name: filter[project_id] description: Filter by project id schema: type: string examples: single: value: 1 summary: Single project multiple: value: 1,2,3,4 summary: Multiple projects panelistidfilter: in: query description: Filter by panelist identifier name: filter[panelist_id] schema: type: string examples: single: value: y36uhip5r8j7 summary: Single panelist multiple: value: y36uhip5r8j7,oa85aha25i,gjore8o7237,zx69g6ybzue summary: Multiple panelists schemas: error: type: object properties: success: type: boolean error: description: The error message. type: string errno: description: The error code. type: string x-tagGroups: - name: Data Input and Output tags: - Auth - Campaign - Category - Community - Datapoint - Panel - Notes - Panelist - Project - Reminder - Sample - Session - Survey - Token