List of EFS Service-Layer (API) services
This document provides a list of all EFS Service-Layer services. To have general information on the EFS Service-Layer, please go to this page.
As mentioned in the EFS Service-Layer overview, all requests should use the token URL parameter to authenticate the service user, for example GET https://your-efs.com/service/survey/surveys/?token=1234567890. An alternative to using the provided token, is to create a basic authentication request as specified in the HTTP protocol.
REST status codes
When using REST to access the Service Layer, the service will use the following HTTP status codes, 500 being the most common error status code and 200 being used for all successful requests.
Status | Description |
|---|
Status | Description |
|---|---|
200 | The request has been processed, see end point description for expected response body |
400 | The validation of the entity given in the body of the request failed. Can also be caused by a malformed JSON request. |
401 | Can be caused by missing, invalid or expired token or username/password combination. |
403 | The user does not have the permission to execute this service or service is unknown or not enabled/available. |
500 | All regular errors and exceptions will use this status code, please see the message for additional information. In some rare exceptions, the returned value may not be json encoded. |
Example for response body of a error status code:
{
"error": {
"message": "REST route [efs/test] not found, not activated or no access",
"code": 403
}
}The title of the expandable area uses the following format:
Description | {REST method} | {SOAP method}
The examples provided are REST requests, our recommended method for accessing the Service-Layer. The list of services omits the mandatory /service/ base path. All service layer requests need to use this base path, e.g. GET /survey/surveys/ should be GET https://efs-installation.com/service/survey/surveys/ in your application.
When requesting services to be activated through the support, it is best to provide the SOAP method names, as these are unique and avoid confusion.
EFS
Email blocklist, global and survey based
DELETE /efs/mailblacklist/ Deletes a list of email addresses from blocklist Request body {
"emailList": [
{
"email": "example@domain.tld",
"surveyId": 1234
}
]
} Response body [
{
"email": "example@domain.tld",
"surveyId": 1234,
"result": 1
}
]
GET /efs/mailblacklist/ Get a list of all blocklisted email addresses (both global and survey). Global entries have surveyId 0. Response body [
{
"email": "example@domain.tld",
"surveyId": 0,
"createdAt": "2020-07-02T12:53:50+00:00",
"createdBy": "SERVICE"
}
]
POST /efs/mailblacklist/ Add a list of email addresses to blocklist. If surveyId is specified the email will be blocked for given survey, otherwise if omitted or if surveyId is 0, the email will be added to global blocklist. Request body {
"emailList": [
{
"email": "example@domain.tld",
"surveyId": 1234
}
]
} Response body [
{
"email": "example@domain.tld",
"surveyId": 1234,
"result": 1
}
]
POST /efs/mailblacklist/check If surveyId is not specified, or the id is 0, only the global blocklist will be checked. By providing a surveyId, the system will check if the email is blocked in the given survey only. The return value is a boolean. Request body {
"emailAddress": "example@domain.tld",
"surveyId": 1234
} Response body true
POST /efs/mailblacklist/getListByDateRange Get a list of blocklisted email addresses (both global and survey related) restricted by date range. Request body {
"dateRange": {
"from": "2020-07-01T12:53:50+00:00",
"to": "2020-07-03T12:53:50+00:00"
}
} Response body [
{
"email": "example@domain.tld",
"surveyId": 1234,
"result": 1
}
]
POST /efs/mailblacklist/getListByEmailAddress Returns a list of all surveys where given email is blacklisted. In case of global blacklist the surveyId is 0. Request body {
"emailAddress": "example@domain.tld"
} Response body [
{
"email": "example@domain.tld",
"surveyId": 0,
"createdAt": "2020-08-26T11:01:22+00:00",
"createdBy": "SERVICE"
}
]
Mail templates
POST /efs/mailtemplates/ Add mail template. Please see the mail template form in EFS for required and optional information. Returns the id of the newly created mail template. Use GET /efs/mailtemplates/{id} on an existing template, if unsure about the correct parameters and also have a look at the mail template editor in EFS for optional and required parameters and supported wildcards, specific to your mail template type. Option Valid values type default_mail, invitation_mail, reminder_mail, survey_ends_mailtype, welcome_mail, pwrecovery_mail, doub_check_mail, register_check_mail, md_invitation_mail, md_reminder_mail, winner_mail, promotion_mail, bonus_mail, exchange_mail, orgprocessor_mail, website_notifications, system_mail, eat_your_own_dogfood, result_mail, reportnotification_mail site_id ID of Panel Website language version, on installations without Panel Website, please use 0. format TEXT, HTML, TEXT_AND_HTML charset UTF-8, UTF-16, ISO-8859-1, ISO-8859-2, ISO-8859-3, ISO-8859-4, ISO-8859-5, ISO-8859-6, ISO-8859-7, ISO-8859-8, ISO-8859-9, ISO-8859-13, ISO-8859-15, US-ASCII, KOI8-R, GB18030, x-EUC-CN, GBK, x-EUC-TW, Big5, Big5-HKSCS, EUC-JP, Shift_JIS, ISO-2022-JP, EUC-KR, ISO-2022-KR, TIS-620 priority NO_PRIORITY, HIGHEST, HIGH, NORMAL, LOW, LOWEST sensitivity NORMAL, PRIVATE, PERSONAL, COMPANY notify NO_NOTIFICATION, WITH_RETURN_PATH, WITH_FROM_PATH localeString See EFS mail template interface for a current list of locales. from from needs to be one of registered sender email addresses in EFS. See: Libraries > Mail templates > Mail senders. Request body {
"mailtemplate": {
"meta": {
"description": "Example description",
"type": "default_mail",
"site_id": "123",
"active": true
},
"content": {
"from": "example@domain.tld",
"subject": "Example",
"format": "TEXT_AND_HTML",
"text_content": "Example",
"html_content": "<h1>Example</h1>"
},
"options": {
"charset": "UTF-8",
"reply_to": "example@domain.tld",
"return_path": "example@domain.tld",
"to_realname": true,
"send_copy": true,
"cc": "example@domain.tld",
"bcc": "example@domain.tld",
"priority": "NO_PRIORITY",
"sensitivity": "NORMAL",
"notify": "NO_NOTIFICATION",
"sms_from": "+491234567890",
"sms_content": "Example"
},
"translations": [
{
"localeString": "de_DE",
"subject": "Beispiel",
"text_content": "Beispiel",
"html_content": "<h1>Beispiel</h1>",
"sms_content": "Beispiel"
}
]
}
} Response body 1
DELETE /efs/mailtemplates/{id} Delete mail template by id. Successful requests have no response body. URI Parameters Name Type Required Description id integer true The mail-template id Examples: 2.
GET /efs/mailtemplates/{id} Get mail template by id Response body {
"meta": {
"description": "Example message",
"type": "default_mail",
"site_id": "7",
"active": true
},
"content": {
"from": "example@domain.tld",
"subject": "Example message",
"format": "TEXT",
"text_content": "Dear #u_firstname#, \r\n\r\nyou have a new message.",
"attachments": false
},
"options": {
"charset": "ISO-8859-1",
"reply_to": "example@domain.tld",
"return_path": "example@domain.tld",
"to_realname": false,
"send_copy": false,
"priority": "NO_PRIORITY",
"sensitivity": "NORMAL",
"notify": "NO_NOTIFICATION"
},
"id": 1234
} URI Parameters Name Type Required Description id integer true The mail-template id Examples: 2.
GET /efs/mailtemplates/withAttachments/{id} Get mail template by id with attachments. The content of attachment is gzip and base64 encoded. Response body {
"meta": {
"description": "Example message",
"type": "default_mail",
"site_id": "7",
"active": true
},
"content": {
"from": "example@domain.tld",
"subject": "Example message",
"format": "TEXT",
"text_content": "Dear #u_firstname#, \r\n\r\nyou have a new message.",
"attachments": false
},
"options": {
"charset": "ISO-8859-1",
"reply_to": "example@domain.tld",
"return_path": "example@domain.tld",
"to_realname": false,
"send_copy": false,
"priority": "NO_PRIORITY",
"sensitivity": "NORMAL",
"notify": "NO_NOTIFICATION"
},
"attachments": [
{"name":"example.jpg", "content":"skkfdsjksdjkfsd..."}
]
"id": 1234
} URI Parameters Name Type Required Description id integer true The mail-template id Examples: 2.
PUT /efs/mailtemplates/{id} Change mail template data, returns the mail id Request body {
"mailtemplate": {
"meta": {
"description": "Example message",
"type": "default_mail",
"site_id": "7",
"active": true
},
"content": {
"from": "example@domain.tld",
"subject": "Example message",
"format": "TEXT",
"text_content": "Dear #u_firstname#, \r\n\r\nyou have a new message.",
"attachments": false
},
"options": {
"charset": "ISO-8859-1",
"reply_to": "example@domain.tld",
"return_path": "example@domain.tld",
"to_realname": false,
"send_copy": false,
"priority": "NO_PRIORITY",
"sensitivity": "NORMAL",
"notify": "NO_NOTIFICATION"
}
}
} Response body 1234 URI Parameters Name Type Required Description id integer true The mail-template id Examples: 2.
POST /efs/mailtemplates/list Get a list of mailtemplates. You can restrict the list of templates, by providing a POST body with the list of types. Request body {
"mailTemplateTypes": [
"default_mail"
]
} Response body [
{
"meta": {
"description": "Example message",
"type": "default_mail",
"site_id": "7",
"active": true
},
"content": {
"from": "example@domain.tld",
"subject": "Example message",
"format": "TEXT",
"text_content": "Dear #u_firstname#, \r\n\r\nyou have a new message.",
"attachments": false
},
"options": {
"charset": "ISO-8859-1",
"reply_to": "example@domain.tld",
"return_path": "example@domain.tld",
"to_realname": false,
"send_copy": false,
"priority": "NO_PRIORITY",
"sensitivity": "NORMAL",
"notify": "NO_NOTIFICATION"
},
"id": 1234
}
]
POST /efs/mailtemplates/listWithAttachments Get a list of mailtemplates. You can restrict the list of templates, by providing a POST body with the list of types. Request body {
"mailTemplateTypes": [
"default_mail"
]
} Response body [
{
"meta": {
"description": "Example message",
"type": "default_mail",
"site_id": "7",
"active": true
},
"content": {
"from": "example@domain.tld",
"subject": "Example message",
"format": "TEXT",
"text_content": "Dear #u_firstname#, \r\n\r\nyou have a new message.",
"attachments": false
},
"attachments": [
]
"options": {
"charset": "ISO-8859-1",
"reply_to": "example@domain.tld",
"return_path": "example@domain.tld",
"to_realname": false,
"send_copy": false,
"priority": "NO_PRIORITY",
"sensitivity": "NORMAL",
"notify": "NO_NOTIFICATION"
},
"id": 1234
}
]
POST /efs/mailtemplates/send Send a preview email. Similar to the mail template preview send functionality in the EFS UI. Request body {
"id": 353,
"recieverMails":"example@example.tld",
"localeString":"de_DE",
"placeholders": [
{"placeholderName":"#test#", "placeholderValue":"Test"}
]
} Response body {
"success": true
}
Management of EFS organisations
DELETE /efs/organizations/ Deletes an EFS admin organisation. Request body {
"adminOrgIdentifierType": "id",
"adminOrgIdentifierValue": "1234"
} Response body true
PATCH /efs/organizations/ Sets an organization's value. See POST /efs/organizations/ for possible adminOrgField names. Request body {
"adminOrgIdentifierType": "id",
"adminOrgIdentifierValue": "1234",
"adminOrgField": "customer_no_common",
"adminOrgValue": "KD1234"
} Response body true
POST /efs/organizations/ Adds an EFS admin organization. Request body {
"adminOrgRecord": {
"name": "Example",
"description": "Example org",
"contract_start": "2020-07-02T12:53:50+00:00",
"contract_end": "2022-07-02T12:53:50+00:00",
"customer_no_common": "Example",
"max_active_projects_allowed": "Example",
"max_archived_projects_allowed": "Example",
},
"adminOrgIdentifierReturnType": "id"
} Response body 1234
PUT /efs/organizations/ Add an existing staff member to an organization. Request body {
"adminUserIdentifierType": "u_email",
"adminUserIdentifierValue": "example@domain.tld",
"adminOrgIdentifierType": "id",
"adminOrgIdentifierValue": "1234"
} Response body true
POST /efs/organizations/details Returns an organization. Request body {
"adminOrgIdentifierType": "id",
"adminOrgIdentifierValue": "1234"
} Response body {
"name": "Example",
"description": "Example org",
"contract_start": "2019-07-01T00:00:00+00:00",
"contract_end": "2023-12-30T00:00:00+00:00",
"customer_no_common": "KD1234"
}
POST /efs/organizations/list Returns a list of organizations specified by a search value. Request body {
"adminOrgField": "name",
"adminOrgValue": "Example",
"pageFrom": 0,
"pageLimit": 100
} Response body [
{
"name": "Example",
"description": "Example org",
"contract_start": "2019-07-01T00:00:00+00:00",
"contract_end": "2023-12-30T00:00:00+00:00",
"customer_no_common": "KD1234"
}
]
PATCH /efs/organizations/templates Changes an admin organization's Reporting+ export templates configuration for one file type format. Possible values for reportingExportFormat are: html, ppt, pdf, pptx and pptxpdf. To disable an export, send "reportingExportTemplates": [], otherwise provide a list of export template ids to be enabled. Request body {
"adminOrgIdentifierType": "id",
"adminOrgIdentifierValue": "1234",
"reportingExportFormat": "pptxpdf",
"reportingExportTemplates": [
123,
124
]
} Response body true
Management of EFS teams
POST /efs/teams/ Adds a new EFS team, returns the id of the team. Request body {
"team": {
"teamName": "Example",
"teamTitle": "Example",
"teamDesription": "Example description",
"teamAccessability": [
1
],
"areasAccessable": [
"www"
],
"rightTemplateId": 1
}
} Response body 1
POST /efs/teams/list Retrieves a list of teams matching given search criteria Request body {
"identifierType": "teamName",
"identifierValue": "Example",
"page": 0,
"limit": 100
} Response body [
{
"teamId": 1,
"teamName": "Example",
"teamTitle": "Example",
"teamDesription": "Example description"
}
]
DELETE /efs/teams/{teamId} Deletes an EFS team Response body true URI Parameters Name Type Required Description teamId integer true team id Examples: 2.
GET /efs/teams/{teamId} Retrieves the data of an EFS team Response body {
"teamId": 1,
"teamName": "Example",
"teamTitle": "Example",
"teamDesription": "Example description"
} URI Parameters Name Type Required Description teamId integer true team id Examples: 2.
PATCH /efs/teams/{teamId} Changes the EFS team details Request body {
"team": {
"teamName": "Example",
"teamTitle": "Example",
"teamDescription": "Example",
"teamAccessability": [
1
],
"areasAccessable": [
"www"
],
"rightTemplateId": 1
}
} Response body true URI Parameters Name Type Required Description teamId integer true team id Examples: 2.
Object rights
DELETE /efs/privileges/ Removes the right from the object for the given team. Request body {
"objectId": 1,
"groupId": 1,
"right": "read"
} Response body true
PATCH /efs/privileges/ Sets a right on an object for given team, replaces any existing condition Request body {
"objectId": 1,
"groupId": 1,
"right": "read"
} Response body true
POST /efs/privileges/addright Adds the right to the object for the given team. Request body {
"objectId": 1,
"groupId": 1,
"right": "read"
} Response body true
POST /efs/privileges/features Tells if current user has access to a specific access right (team rights). Valid parameters for right: read, write. The parameter feature accepts a string containing the name of an act right, please see team rights management in System > Users > Teams in EFS or the online manual. Request body {
"feature": "ct42partadm",
"right": "read"
} Response body true
POST /efs/privileges/object Tells if current user has access to an object. See Options > ACL Rights > Object instances Request body {
"objectId": 1,
"right": "read"
} Response body true
EFS admin user management
DELETE /efs/staff/ Deletes a staff member. A successful request has no response body. Request body {
"identifierType": "email",
"identifier": "example@domain.tld"
}
GET /efs/staff/ Return information about the current admin user thats using the service. This method also keeps admin-session alive. Response body {
"adminUserId": 1234,
"accountName": "Example",
"firstName": "First",
"lastName": "Last",
"email": "example@domain.tld",
"language": "EN",
"expireDate": "2020-07-02T12:53:50+00:00",
"organisation": 1,
"primaryGroup": 1,
"groups": [
1
]
}
PATCH /efs/staff/ Changes a staff members data. You only need to provide the fields you want to change. Request body {
"identifierType": "email",
"identifier": "example@domain.tld",
"changes": {
"firstName": "First",
"lastName": "Last",
"email": "example@domain.tld",
"password": "New Password",
"gender": "NOT_SPECIFIED",
"street": "None",
"zip": "12345",
"city": "Example",
"phone": "+491234567890",
"country": "Germany",
"mobile": "+491234567890",
"language": "EN",
"expireDate": "2024-07-02T12:53:50+00:00",
"organisation": 1,
"primaryTeam": 1,
"teams": [
1
],
"enabled": true,
"mobile2": "+491234567891",
"www": "Some URL",
"comment": "Additional Comment",
"department": "Department info"
}
}
POST /efs/staff/ Create a new staff member for the EFS admin interface. To set the staff members organization you need to have the appropriate right. If no organization is set the staff member will inherit the creating staff members organization. Returns the user id. Request body {
"staffMember": {
"identifierType": "email",
"identifier": "example@domain.tld",
"changes": {
"account": "Example",
"firstName": "First",
"lastName": "Last",
"email": "example@domain.tld",
"password": "New Password",
"gender": "NOT_SPECIFIED",
"street": "None",
"zip": "12345",
"city": "Example",
"phone": "+491234567890",
"country": "Germany",
"mobile": "+491234567890",
"language": "EN",
"expireDate": "2024-07-02T12:53:50+00:00",
"organisation": 1,
"primaryTeam": 1,
"teams": [
1
],
"enabled": true,
"mobile2": "+491234567891",
"www": "Some URL",
"comment": "Additional Comment",
"department": "Department info"
}
}
} Response body 1234
POST /efs/staff/details Return information about a staff member Request body {
"identifierType": "email",
"identifier": "example@domain.tld"
} Response body {
"userId": 1234,
"account": "Example",
"firstName": "First",
"lastName": "Last",
"email": "example@domain.tld",
"password": "New Password",
"gender": "NOT_SPECIFIED",
"street": "None",
"zip": "12345",
"city": "Example",
"phone": "+491234567890",
"country": "Germany",
"mobile": "+491234567890",
"language": "EN",
"expireDate": "2020-07-02T12:53:50+00:00",
"organisation": 1,
"primaryTeam": 1,
"teams": [
1
],
"enabled": true,
"mobile2": "Example",
"www": "Example",
"comment": "Example",
"department": "Example"
}
GET /efs/staff/list Returns a list of all EFS staff members Response body [
{
"adminUserId": 1234,
"accountName": "Example",
"firstName": "First",
"lastName": "Last",
"email": "example@domain.tld",
"language": "EN",
"expireDate": "2020-07-02T12:53:50+00:00",
"organisation": 1,
"primaryGroup": 1,
"groups": [
1
]
}
]
POST /efs/staff/mail Sends email to the specified EFS admin user Request body {
"identifierType": "email",
"identifierValue": "example@domain.tld",
"mailTemplateData": {
"meta": {
"description": "Example message",
"type": "default_mail",
"site_id": "7",
"active": true
},
"content": {
"from": "example@domain.tld",
"subject": "Example message",
"format": "TEXT",
"text_content": "Dear user, \r\n\r\nyou have a new message.",
"attachments": false
},
"options": {
"charset": "ISO-8859-1",
"reply_to": "example@domain.tld",
"return_path": "example@domain.tld",
"to_realname": false,
"send_copy": false,
"priority": "NO_PRIORITY",
"sensitivity": "NORMAL",
"notify": "NO_NOTIFICATION"
}
}
} Response body true
PATCH /efs/staff/role Alters a staff members role within a given team Request body {
"userId": 1,
"teamId": 1,
"newRole": "MEMBER",
"newOwnerUserId": 1
} Response body true
System information
GET /efs/system/ determine the version number of the EFS installation Response body "20.1"
POST /efs/system/ Returns the current server time, use format to provide a formatting string (see PHP date() formatting options), otherwise the current unix timestamp will be returned. Request body { "format": "Y-m-d H:i:s" } Response body "2020-08-26 13:35:26"
GET /efs/system/load query the current system's 1-minute load average Response body 1.345
Other
GET /efs/session/{sessionId} Get the admin user id for an admin session id Will throw an exception if the session id is invalid or the session is expired Response body 1234 URI Parameters Name Type Required Description sessionId string true id of admin session.
GET /efs/taskqueue/{taskId} Returns json encoded array with either execution-status or (if available) result of asynchronous service-calls for given taskId. Possible values for status: 1 - Task is pending for execution, 2 - Task is currently running, 3 - Task execution failed; Response body "2" URI Parameters Name Type Required Description taskId integer true id of taskqueue task Examples: 2.
GET /efs/jobs/{jobId} Query the status of a single EFS job maker job. This service is only enabled in certain use cases for customers. Response body "2" URI Parameters Name Type Required Description jobId string true job id, Example: 10898768285f48e49c0d49f.
Employee
POST /employee/reports/ Adds a report Request body {
"report": {
"report_definition_id": 1234,
"pid": 1234,
"lang_id": 1234,
"report_type": "pdf",
"unit_metaname": "Example",
"file_content": "QmFzZTY0IGVuY29kZWQgYmluYXJ5IGRhdGE=",
"report_label": "Example",
"replace": true,
"report_filename": "Example.pdf"
}
} Response body {
"report_definition_id": 1234,
"pid": 1234,
"lang_id": 1234,
"report_type": "pdf",
"unit_metaname": "Example",
"file_content": "QmFzZTY0IGVuY29kZWQgYmluYXJ5IGRhdGE=",
"report_label": "Example",
"replace": true,
"report_filename": "Example.pdf",
"rid": "1234"
}
GET /employee/reports/{surveyId} Returns the List of Report definitions including report versions for surveyId Response body [
{
"report_id": 1234,
"pid": 1234,
"name": "Example",
"title_pattern": "Example",
"template": "Example",
"cat": "Example",
"download_status": "Example",
"file_download_pattern": "Example",
"report_type": 1234,
"number_of_reports": 1234,
"min_participants": 1234,
"min_item": 1234
}
] URI Parameters Name Type Required Description surveyId integer true id of the panel or masterdata survey Examples: 2.
GDPR
GET /gdpr/panel/getConsentForm/{localeString} Returns GDPR consent for given locale string Response body {
"content_value": "Example",
"welcome_text_value": "Example",
"title_headline": "Example",
"contact_us_headline_headline": "Example",
"company_name_value": "Example",
"contact_detail_value": "Example",
"representative_headline": "Example",
"representative_value": "Example",
"data_scope_headline": "Example",
"data_scope_value": "Example",
"data_category_headline": "Example",
"data_category_value": "Example",
"legal_basis_headline": "Example",
"legal_basis_value": "Example",
"recipient_headline": "Example",
"recipient_value": "Example",
"transfer_data_headline": "Example",
"transfer_data_value": "Example",
"contractual_requirement_headline": "Example",
"contractual_requirement_value": "Example",
"auto_decision_headline": "Example",
"auto_decision_value": "Example",
"info_subject_headline": "Example",
"info_subject_value": "Example",
"info_withdrawal_headline": "Example",
"info_withdrawal_value": "Example",
"info_supervisor_headline": "Example",
"info_supervisor_value": "Example",
"contact_officer_headline": "Example",
"contact_officer_value": "Example",
"data_retention_headline": "Example",
"data_retention_value": "Example"
} URI Parameters Name Type Required Description localeString string true Language string, Examples: de_DE, en_GB.
POST /gdpr/panel/setConsentForm Set content of GDPR consent for given locale string Request body {
"localeString": "de_DE",
"consentData": {
"content_value": "Example",
"welcome_text_value": "Example",
"title_headline": "Example",
"contact_us_headline_headline": "Example",
"company_name_value": "Example",
"contact_detail_value": "Example",
"representative_headline": "Example",
"representative_value": "Example",
"data_scope_headline": "Example",
"data_scope_value": "Example",
"data_category_headline": "Example",
"data_category_value": "Example",
"legal_basis_headline": "Example",
"legal_basis_value": "Example",
"recipient_headline": "Example",
"recipient_value": "Example",
"transfer_data_headline": "Example",
"transfer_data_value": "Example",
"contractual_requirement_headline": "Example",
"contractual_requirement_value": "Example",
"auto_decision_headline": "Example",
"auto_decision_value": "Example",
"info_subject_headline": "Example",
"info_subject_value": "Example",
"info_withdrawal_headline": "Example",
"info_withdrawal_value": "Example",
"info_supervisor_headline": "Example",
"info_supervisor_value": "Example",
"contact_officer_headline": "Example",
"contact_officer_value": "Example",
"data_retention_headline": "Example",
"data_retention_value": "Example"
}
} Response body true
GET /gdpr/survey/{surveyId}/{languageId} Returns GDPR consent for given surveyId and languageId Response body {
"content_value": "Example",
"welcome_text_value": "Example",
"title_headline": "Example",
"contact_us_headline_headline": "Example",
"company_name_value": "Example",
"contact_detail_value": "Example",
"representative_headline": "Example",
"representative_value": "Example",
"data_scope_headline": "Example",
"data_scope_value": "Example",
"data_category_headline": "Example",
"data_category_value": "Example",
"legal_basis_headline": "Example",
"legal_basis_value": "Example",
"recipient_headline": "Example",
"recipient_value": "Example",
"transfer_data_headline": "Example",
"transfer_data_value": "Example",
"contractual_requirement_headline": "Example",
"contractual_requirement_value": "Example",
"auto_decision_headline": "Example",
"auto_decision_value": "Example",
"info_subject_headline": "Example",
"info_subject_value": "Example",
"info_withdrawal_headline": "Example",
"info_withdrawal_value": "Example",
"info_supervisor_headline": "Example",
"info_supervisor_value": "Example",
"contact_officer_headline": "Example",
"contact_officer_value": "Example",
"data_retention_headline": "Example",
"data_retention_value": "Example",
"data_retention_type": "YEAR",
"data_retention_amount": 1
} URI Parameters Name Type Required Description surveyId integer true Survey Id Examples: 2. languageId integer true Language Id Examples: 2.
POST /gdpr/survey/{surveyId}/{languageId} Set content of GDPR consent for given surveyId and languageId Request body {
"consentData": {
"content_value": "Example",
"welcome_text_value": "Example",
"title_headline": "Example",
"contact_us_headline_headline": "Example",
"company_name_value": "Example",
"contact_detail_value": "Example",
"representative_headline": "Example",
"representative_value": "Example",
"data_scope_headline": "Example",
"data_scope_value": "Example",
"data_category_headline": "Example",
"data_category_value": "Example",
"legal_basis_headline": "Example",
"legal_basis_value": "Example",
"recipient_headline": "Example",
"recipient_value": "Example",
"transfer_data_headline": "Example",
"transfer_data_value": "Example",
"contractual_requirement_headline": "Example",
"contractual_requirement_value": "Example",
"auto_decision_headline": "Example",
"auto_decision_value": "Example",
"info_subject_headline": "Example",
"info_subject_value": "Example",
"info_withdrawal_headline": "Example",
"info_withdrawal_value": "Example",
"info_supervisor_headline": "Example",
"info_supervisor_value": "Example",
"contact_officer_headline": "Example",
"contact_officer_value": "Example",
"data_retention_headline": "Example",
"data_retention_value": "Example",
"data_retention_type": "YEAR",
"data_retention_amount": 1
}
} Response body true URI Parameters Name Type Required Description surveyId integer true Survey Id Examples: 2. languageId integer true Language Id Examples: 2.
DELETE /gdpr/survey/{surveyId} Deletes personal data of all participants for given surveyId Response body true URI Parameters Name Type Required Description surveyId integer true Survey Id Examples: 2.
Leadership
POST /loft/participants/pool/{sampleId} add multiple feedback-participants from a CSV file to the participants pool using data from a CSV file. note this operation works on surveys of type "leadership" only Request body {
"csvData": "CSV content",
"returnIdentifierType": "u_email",
"mappingColumn": "u_email"
} Response body {
"successful": 1,
"failed": 1,
"failedRows": [
{
"line": 1234,
"value": "Example",
"errors": [
{
"column": "Example",
"value": "Example",
"details": [
{
"code": "Example",
"translated": "Example",
"type": 1234
}
]
}
]
}
],
"returnIdentifiers": [
{
"internalReturnValue": "u_email",
"externalReturnValue": "u_email"
}
]
} URI Parameters Name Type Required Description sampleId integer true id of sample to add the participants to Examples: 2.
POST /loft/participants/{sampleId} add multiple feedback-provider and -receiver from a CSV file to a feedback-wave using data from a CSV file. note this operation works on surveys of type "leadership" only Request body {
"waveId": 1,
"csvData": "CSV Import data",
"returnIdentifierType": "u_email",
"mappingColumn": "Mail"
} Response body {
"successful": 1,
"failed": 1,
"failedRows": [
{
"line": 1,
"value": "Example",
"errors": [
{
"column": "Example",
"value": "Example",
"details": [
{
"code": "Example",
"translated": "Example",
"type": 1234
}
]
}
]
}
],
"returnIdentifiers": [
{
"internalReturnValue": "u_email",
"externalReturnValue": "Mail"
}
]
} URI Parameters Name Type Required Description sampleId integer true id of sample to add the participants to Examples: 2.
GET /loft/participants/{project_id}/{fid} Get feedback center user data Response body "Encoded Feedback Center data" URI Parameters Name Type Required Description project_id integer true Efs project id Examples: 2. fid integer true Feedback center user id Examples: 2.
GET /loft/participants/{project_id}/{fid}/{token} Check if user has access to feedback center for project Response body true URI Parameters Name Type Required Description project_id integer true Efs project id Examples: 2. fid integer true Feedback center user id Examples: 2. token string true token to validate request at data voyager Examples: Example.
MySight
PATCH /mysight/groups/{instanceId} Updates additional data of configured panel groups for given mySight instance Response body true URI Parameters Name Type Required Description instanceId integer true mySight instanceId Examples: 2.
People Module / Panel
Panel circles
POST /panel/circles/ Adds a new panel circle (portals group), used in Portals Request body {
"circleInitData": {
"title": "People in my organization",
"circleAccessType": "PRIVATE",
"matchVar": "m_gcid_recode",
"matchAgainstVar": "m_gcid_recode",
"panelGroupId": 1,
"startDateTime": "2021-01-09 09:00:00",
"intervalType": "DAY",
"intervalValue": 1
}
} Response body {
"circleId": 123,
"title": "People in my organization",
"circleType": "COMPANY_MANAGED",
"circleAccessType": "PRIVATE",
"circleProcessStatus": "IDLE"
}
POST /panel/circles/generate/{id} Generates a company managed panel circle (portals group) Response body true URI Parameters Name Type Required Description id integer true id of panel circle Examples: 2.
POST /panel/circles/listByCondition Returns a list of panel circle objects to given logical condition. See filtering results with conditions for help on building conditions. Request body {
"condition": {
"join": {
"operator": "AND",
"condition1": {
"comparison": {
"variable" : "circleType",
"operator" : "EQUAL",
"value" : "USER_MANAGED"
}
},
"condition2": {
"inComparison": {
"variable": "circleAccessType",
"operator": "IN",
"value": ["PUBLIC", "PRIVATE"]
}
}
}
},
"offset": 0,
"limit": 10
} Response body [
{
"circleId": 1,
"title": "Example",
"circleType": "USER_MANAGED",
"circleAccessType": "PRIVATE",
"circleProcessStatus": "IDLE"
}
]
DELETE /panel/circles/{id} Deletes a panel circle Response body true URI Parameters Name Type Required Description id integer true id of panel circle Examples: 2.
GET /panel/circles/{id} Returns panel circle object to given circle ID Response body {
"circleId": 1,
"title": "Example",
"circleType": "USER_MANAGED",
"circleAccessType": "PRIVATE",
"circleProcessStatus": "IDLE"
} URI Parameters Name Type Required Description id integer true id of panel circle Examples: 2.
External surveys management
DELETE /panel/externalsurveys/ Deletes an external study with all its participation data. Request body {
"identifierType": "internal_id",
"identifierValue": "Example"
} Response body true
GET /panel/externalsurveys/ Retrieves a list of all external surveys. Response body [
{
"externalSurveyId": 1,
"externalSurveyExternalId": "1234",
"externalSurveyTitle": "Example",
"externalSurveyType": 1234,
"externalSurveyAttributes": [
{
"attributeName": "Name",
"attributeValue": "Example"
}
],
"externalSurveyModificationDate": "2020-07-02T12:53:50+00:00"
}
]
PATCH /panel/externalsurveys/ Updates an existing external survey with new attributes. The survey's external ID cannot be changed. Request body {
"identifierType": "internal_id",
"identifierValue": "Example",
"title": "Example",
"type": 1234,
"attributes": [
{
"attributeName": "Name",
"attributeValue": "Example"
}
]
} Response body true
POST /panel/externalsurveys/ Retrieves a list of external surveys that were modified since a given timestamp Request body {
"timestamp": "2020-07-02T12:53:50+00:00"
} Response body [
{
"externalSurveyId": 1,
"externalSurveyExternalId": "1234",
"externalSurveyTitle": "Example",
"externalSurveyType": 1234,
"externalSurveyAttributes": [
{
"attributeName": "Name",
"attributeValue": "Example"
}
],
"externalSurveyModificationDate": "2020-07-02T12:53:50+00:00"
}
]
POST /panel/externalsurveys/add Adds a new external survey, returns ID Request body {
"title": "Example",
"type": 1234,
"attributes": [
{
"attributeName": "some_attribute",
"attributeValue": "Example"
}
]
} Response body 1
POST /panel/externalsurveys/data Retrieves the data of the external survey Request body {
"identifierType": "internal_id",
"identifierValue": "Example"
} Response body {
"externalSurveyId": 1,
"externalSurveyExternalId": "123",
"externalSurveyTitle": "Example",
"externalSurveyType": 1234,
"externalSurveyAttributes": [
{
"attributeName": "Name",
"attributeValue": "Example"
}
],
"externalSurveyModificationDate": "2020-07-02T12:53:50+00:00"
}
POST /panel/externalsurveys/participants Adds or updates the participation status of multiple participants in an external survey Request body {
"identifierType": "internal_id",
"identifierValue": "Example",
"panelistIdentifierType": "u_email",
"surveyParticipations": [
{
"panelistIdentifierValue": "example@domain.tld",
"participationStatus": "10",
"participationDate": "2020-07-02T12:53:50+00:00",
"participationPoints": 1.345,
"participationScore": 1.345
}
]
} Response body true
Group categories
POST /panel/groups/category adds a new panel group category Request body {
"categoryName": "Example",
"categoryDescription": "Example description"
} Response body {
"categoryId": 123,
"categoryName": "Example",
"categoryDescription": "Example description"
}
GET /panel/groups/category/{categoryId} returns group category data Response body {
"categoryId": 2,
"categoryName": "Example",
"categoryDescription": "Example description"
} URI Parameters Name Type Required Description categoryId integer true id of panel group category Examples: 2.
POST /panel/groups/categoryByName returns group category data Request body {
"categoryName": "Example"
} Response body {
"categoryId": 2,
"categoryName": "Example",
"categoryDescription": "Example description"
}
Groups
DELETE /panel/groups/ Removes panelist from group (id) Request body {
"id": 1234,
"identifierType": "u_email",
"identifierValues": [
"example@domain.tld"
]
} Response body true
POST /panel/groups/ add a new panel group, returns id of group Request body {
"name": "Example",
"description": "Example",
"categoryId": 1
} Response body 123
POST /panel/groups/list gets a list of panel groups, optionally restricted to a specific panel group category Request body {
"restrictCategoryId": 2
} Response body [
{
"groupId": 123,
"name": "Example",
"description": "Example description",
"size": 1234,
"categoryId": 2,
"categoryName": "Example"
}
]
DELETE /panel/groups/{id} Delete a panel group along with any panelist-group membership records plus any update rules for group. Panelist data of group members will not be deleted. Response body true URI Parameters Name Type Required Description id integer true id of the panel group to be deleted Examples: 2.
PATCH /panel/groups/{id} add panelists to an existing panel group Request body {
"identifierType": "uid",
"identifierValues": [
123, 124, 125
]
} Response body true URI Parameters Name Type Required Description id integer true id of the panel group to be deleted Examples: 2.
POST /panel/groups/{id} Supplies a list of panelists which are members in a given group Request body {
"returnIdentifierType": "uid"
} Response body [ "123", "124", "125" ] URI Parameters Name Type Required Description id integer true id of the panel group to be deleted Examples: 2.
PUT /panel/groups/{id} empty a panel group by deleting all members from it Response body true URI Parameters Name Type Required Description id integer true id of the panel group to be deleted Examples: 2.
Lotteries
POST /panel/lotteries/{gid} Create prize draw, returns id Request body { "title": "Example", "description": "Description" } Response body 1234 URI Parameters Name Type Required Description gid integer true Panel group id Examples: 2.
DELETE /panel/lotteries/{id} Delete prize draw. Includes deletion of prizes and winners. Response body true URI Parameters Name Type Required Description id integer true Lottery id Examples: 2.
GET /panel/lotteries/{id} Get prize draw by prize draw ID. Provides prize draw object to access gratification and other parameters. Response body {
"id": 2,
"title": "Example",
"description": "Example",
"status": "Created",
"groupId": 1
} URI Parameters Name Type Required Description id integer true Lottery id Examples: 2.
PATCH /panel/lotteries/{id} Update status of prize draw with given prize draw ID. Request body { "status": "ARCHIVED" } Response body true URI Parameters Name Type Required Description id integer true Lottery id Examples: 2.
DELETE /panel/lotteries/{id}/winners Delete winner Response body true URI Parameters Name Type Required Description id integer true Lottery id Examples: 2.
GET /panel/lotteries/{id}/winners Get winners by prize draw id Response body [
{
"grid": 1234,
"prid": 1234,
"uid": 1234,
"status": "Example",
"u_firstname": "Example",
"u_name": "Example",
"u_email": "example@domain.tld",
"pricetitle": "Example"
}
] URI Parameters Name Type Required Description id integer true Lottery id Examples: 2.
Master data
GET /panel/masterdata/ returns the panel's master data variables along with their predefined answer codes Response body [
{
"varname": "m_0000",
"label": "Country",
"type": "int",
"typeGroup": "numeric",
"recoded": false,
"categories": [
{
"code": 3,
"label": "USA"
},
{
"code": 2,
"label": "United Kingdom"
},
{
"code": 1,
"label": "Germany"
},
{
"code": 0,
"label": "Please select"
}
]
},
{...}
]
POST /panel/masterdata/ add masterdata variable Request body {
"name": "m_9988",
"label": "m_9988 Label",
"type": "tinyint",
"category": 1,
"optional": true
} Response body "m_9988"
GET /panel/masterdata/{modificationDate}/list returns the panel's master data variables along with their predefined answer codes, which were modified after modificationDate. Response body [
{
"varname": "m_9988",
"label": "Example",
"type": "smallint",
"typeGroup": "Example",
"recoded": true,
"categories": [
{
"code": 1234,
"label": "Example",
"isMissing": true
}
]
}
] URI Parameters Name Type Required Description modificationDate integer true variables with modification date newer than given parameter will be respected (timestamp) Examples: 1599147158.
Panelists
DELETE /panel/panelists/ Delete panelist Request body {
"identifierType": "uid",
"identifierValue": "123"
} Response body true
PATCH /panel/panelists/ change multiple panelists' account data from a CSV file (batch operation) Request body {
"identifierType": "u_email",
"csvData": "csv content"
} Response body {
"successful": 1,
"failed": 1,
"failedRows": [
{
"line": 2,
"errors": [
{
"column": "Example",
"value": "Example",
"details": [
{
"code": "Example",
"translated": "Example",
"type": 1234
}
]
}
]
}
],
"returnIdentifiers": [
{
"internalReturnValue": "Example",
"externalReturnValue": "Example"
}
]
}
POST /panel/panelists/v1 Adds a panelist to the panel. Fields u_email, u_firstname, u_name, u_passwd are required.
Please note, that POST /panel/panelists (without v1) is deprecated and should no longer be used. Request body {
"returnIdentifierType": "uid",
"panelistData": {
"u_account": "Example",
"u_firstname": "First",
"u_name": "Last",
"u_street": "Example",
"u_zip": "12345",
"u_city": "Example",
"u_phone": "+4912345",
"u_email": "example@domain.tld",
"u_www": "Example",
"u_address": "Example",
"u_country": "Example",
"u_other_id": "123",
"u_gender": "NOT_SPECIFIED",
"u_address2": "Example",
"u_address3": "Example",
"u_mobile": "Example",
"u_mobile2": "Example",
"pci": 127,
"masterDataValues": [
{
"key": "m_0000",
"value": "12"
}
],
"u_sec_quest": "Example",
"u_sec_quest_answer": "Example",
"site_id": 1,
"u_timezone": "+0:00",
"gc_id": 1,
"u_passwd": "Example",
"gid": 1
}
} Response body "123"
POST /panel/panelists/csv add multiple panelists from a CSV file to the panel (batch operation) Request body {
"returnIdentifierType": "uid",
"csvData": "Csv Data here",
"mappingColumn": "email"
} Response body {
"successful": 1,
"failed": 1,
"failedRows": [
{
"line": 2,
"errors": [
{
"column": "Email",
"value": "example@domain.tld",
"details": [
{
"code": "Example",
"translated": "Example",
"type": 1234
}
]
}
]
}
],
"returnIdentifiers": [
{
"internalReturnValue": "123",
"externalReturnValue": "example@domain.tld"
}
]
}
POST /panel/panelists/details get information about a panelist If no panelist is found, this service will return a 500 error. Request body {
"identifierType": "uid",
"identifierValue": "123"
} Response body {
"u_account": "Example",
"u_firstname": "First",
"u_name": "Last",
"u_street": "Example",
"u_zip": "12345",
"u_city": "Example",
"u_phone": "+4912345",
"u_email": "example@domain.tld",
"u_www": "Example",
"u_address": "Example",
"u_country": "Example",
"u_other_id": "12345",
"u_gender": "NOT_SPECIFIED",
"u_address2": "Example",
"u_address3": "Example",
"u_mobile": "+4912345",
"u_mobile2": "+4912345",
"masterDataValues": [
{
"key": "m_0000",
"value": "1"
}
],
"site_id": 1,
"u_timezone": "+0:00",
"gc_id": 10,
"uid": 123
}
PUT /panel/panelists/details Change an existing panelist's data Request body {
"identifierType": "uid",
"identifierValue": "123",
"panelistData": {
"u_firstname": "NewFirst",
"u_name": "NewLast",
"masterDataValues": [
{
"key": "m_0001",
"value": "2"
}
]
}
} Response body true
DELETE /panel/panelists/external Deletes an external authentication mapping from EFS. Please note: Only the mapping will be deleted. The panelist will not be removed from EFS. Request body {
"externalServiceId": 1234,
"externalAuthenticationValue": "Example"
} Response body true
POST /panel/panelists/external Establishes a mapping between a member of an external system (specified by the external_service_id and the external_service_authentication_value) and an EFS panelist. This can be used to implement seamless logins for EFS panelists coming from external web applications. Request body {
"externalServiceId": 1,
"externalAuthenticationValue": "Example",
"identifierType": "uid",
"identifierValue": "123"
} Response body true
POST /panel/panelists/external/{externalServiceId} Returns the EFS identifier for a member of an external system. If the member has not been registered in EFS using the save_external_panelist_authentication web service before, this service will throw an exception. Request body {
"externalAuthenticationValue": "Example",
"identifierReturnType": "Example"
} Response body "Example" URI Parameters Name Type Required Description externalServiceId integer true The external ID. Examples: 2.
POST /panel/panelists/group/{groupId}/list returns a list of panelists in a specific panel group Request body { "returnDataFields": [ "Example" ] } Response body [ [ "Example" ] ] URI Parameters Name Type Required Description groupId integer true id of panel group Examples: 2.
POST /panel/panelists/groups Returns a list of panel groups in which the panelist is a member Request body {
"identifierType": "uid",
"identifierValue": "123"
} Response body [
{
"panelGroupId": 10,
"panelGroupName": "Example",
"panelGroupStatus": "ACTIVE"
}
]
POST /panel/panelists/list returns a list of panelists matched by a specific panel survey sample Request body {
"sampleId": 1,
"returnDataFields": [
"u_email",
"uid"
]
} Response body [
[
"example@domain.tld",
"123"
]
]
POST /panel/panelists/list/find returns a list of actual panelists from a list of possible panelist identifiers using this service it can be checked if specific panelists are already contained in the panel or not Request body {
"identifierType": "u_email",
"identifierList": [
"example@domain.tld", "example2@domain.tld"
],
"returnDataFields": [
"uid",
"u_email"
]
} Response body [
[
"215",
"example2@domain.tld"
],
[
"214",
"example@domain.tld"
]
]
POST /panel/panelists/login Checks whether a panelist can login to the panel website with the login data specified. Login types: login_type_interviewer, login_type_email or login_type_account Request body {
"loginType": "login_type_account",
"account": "example",
"password": "Example123"
} Response body true
POST /panel/panelists/mail Sends mails to one or more panelists by a specific identifier Request body {
"identifierType": "uid",
"identifierValues": [
"123"
],
"mailTemplate": {
"subject": "Example",
"textContent": "Example",
"htmlContent": "Example",
"charset": "UTF-8",
"replyTo": "example@domain.tld",
"priority": "NO_PRIORITY",
"sensitivity": "NORMAL",
"notify": "NO_NOTIFICATION",
"toRealname": true,
"from": "example@domain.tld",
"fromRealname": "Example"
},
"dispcodes": [
"10"
],
"sendOptions": {
"sendDate": "2020-07-02T12:53:50+00:00",
"useRecipientTimezone": true
}
} Response body true
PATCH /panel/panelists/masterdata increment/decrement a master data variable's value for one or multiple panelists Request body {
"identifierType": "uid",
"identifierList": [
"123"
],
"variableName": "m_starcount",
"step": 1
} Response body 1234
POST /panel/panelists/masterdata Get a master data variable's value for panelist Request body {
"identifierType": "uid",
"identifierValue": "123",
"variableName": "m_starcount"
} Response body "12"
POST /panel/panelists/modified Returns the identifiers of all panelists whose data (participant data plus master data) has changed since this given timestamp. Request body {
"identifierType": "uid",
"modificationDate": "2020-07-02T12:53:50+00:00",
"excludeModifier": 0
} Response body [ { "identifier": "123" } ]
POST /panel/panelists/online Returns the panelists who are online on the website. Panelists are returned as an array of e-mail addresses, pseudonyms, panelist codes etc. together with the language ID of the website they are active on. A panelist might be active in multiple languages at the same time (e.g. by viewing the English version of the website and then changing to the French version). In this case, the panelist will be returned twice in the result array, but with different language IDs each. The interval for counting as being online can be specified in the global configuration of the website in the EFS admin area. Request body {
"identifierReturnType": "uid",
"languageIds": [
{
"langId": 1234
}
]
} Response body [
{
"panelist_identifier_value": "123",
"language_id": 1234
}
]
POST /panel/panelists/status Returns the current panel status of a panelist and accepts single uid only if given. Request body { "identifierType": "uid", "identifierValue": "123" } Response body 2
PATCH /panel/panelists/setstatus Updates the panel status of a panelist. Request body {
"identifierType": "u_email",
"identifierValue": "example@domain.tld",
"status": 2
} Response body true
POST /panel/panelists/survey/{surveyId} Add a panelist to a panel or master data survey. Valid options for resetParticipation: reset_if_completed, reset_always, reset_delete_if_completed, reset_delete_always, reset_no_change Request body {
"identifierType": "uid",
"identifierValue": "123",
"resetParticipation": "reset_if_completed"
} Response body {
"sampleId": 1,
"dispositionCode": "10",
"code": "Example",
"isTester": false,
"link": "http://Example"
} URI Parameters Name Type Required Description surveyId integer true id of the panel or masterdata survey Examples: 2.
POST /panel/panelists/{sampleId} Add a panelist to a sample. Valid options for resetParticipation: reset_if_completed, reset_always, reset_delete_if_completed, reset_delete_always, reset_no_change Request body {
"identifierType": "uid",
"identifierValue": "123",
"resetParticipation": "reset_if_completed"
} Response body {
"sampleId": 1,
"dispositionCode": "10",
"code": "Example",
"isTester": false,
"link": "http://Example"
} URI Parameters Name Type Required Description sampleId integer true id of panel survey sample Examples: 2.
POST /panel/panelists/{filterId}/list returns a list of panelists matched by a specific panel grouping filter Request body { "returnDataFields": [ "u_email" ] } Response body [ [ "example@domain.tld" ] ] URI Parameters Name Type Required Description filterId integer true id of panel grouping filter Examples: 2.
Bonus points
PATCH /panel/panelists/bonuspoints Reset the bonus points of one or multiple panelists to zero. This action will also add a note to each panelists' bonus points balance so panelists get informed about the nullification. If a panelist already has a balance of zero points, no additional note will be added to his/her points log Request body {
"identifierType": "uid",
"identifierList": [
"123"
],
"description": "Example bonus points reset"
}
POST /panel/panelists/bonuspoints Returns the bonus points of a given panelist. Request body {
"identifierType": "uid",
"identifierValue": "123"
} Response body 1345
PUT /panel/panelists/bonuspoints Adds or subtracts bonus points for a panelist's account. The panelist can be identified by different criteria (uid, panelist code, pseudonym etc.). The transaction will be shown in the panelists' account balance history afterwards. Request body {
"identifierType": "uid",
"identifierValue": "123",
"pointsValue": 10,
"pointsReason": "Example"
} Response body 1355
POST /panel/panelists/bonuspoints/balance Returns the account balance/bonus points positions for all panelists of the installation that happened since the last call to the service. This method can be used to do a regular, incremental replication of the panel's bonus points to another application (where EFS is used as the master system for managing the points). The panelist identifier for the returned balance positions can be uid, panelist code, pseudonym etc. Request body {
"returnIdentifierType": "uid",
"fetchAll": true,
"logTransfer": true
} Response body [
{
"panelist_identifier_value": "123",
"item_type": 0,
"survey_id": 1701,
"points_id": 6,
"description": "Participation in survey Demo",
"credit_points": 10,
"date": "2018-07-05T08:37:57+00:00",
"paid": 0,
"paid_date": "",
"alt_address": ""
}
]
POST /panel/panelists/bonuspoints/balance/find Returns the account balance/bonus points positions for a panelist that happened in the last months. The panelist can be identified by different criteria (user_id, panelist code, pseudonym etc.). Request body {
"identifierType": "uid",
"identifierValue": "123,
"monthsRange": 1,
"skipEmpty": true
} Response body [
{
"panelist_identifier_value": "123",
"item_type": 0,
"survey_id": 1701,
"points_id": 6,
"description": "Participation in survey Demo",
"credit_points": 10,
"date": "2018-07-05T08:37:57+00:00",
"paid": 0,
"paid_date": "",
"alt_address": ""
}
]
POST /panel/panelists/bonuspoints/{surveyId} Manually grants bonus points to a list of panelists for participation in a panel or master data survey. Successful requests have no response body. Request body {
"identifierType": "uid",
"identifierList": [
"123", "124", "125"
],
"points": 10,
"description": "Example bonus points"
} URI Parameters Name Type Required Description surveyId integer true Id of the panel or master data survey. Examples: 2.
POST /panel/panelists/redemption Returns the bonus points redemption positions for all panelists of the installation that happened since the last call to the service. This method can be used to do a regular, incremental replication of the panel's bonus points redemption to another application (where EFS is used as the master system for managing the points). The panelist identifier for the returned redemption can be user_id, panelist code, pseudonym etc. Request body {
"identifierType": "uid",
"fetchAll": true,
"logTransfer": true
} Response body [
{
"panelist_identifier_value": "Example",
"item_type": 1234,
"survey_id": 1234,
"points_id": 1234,
"description": "Example",
"credit_points": 1.345,
"date": "Example",
"paid": 1234,
"paid_date": "Example",
"alt_address": "Example",
"voucher_code": "Example"
}
]
POST /panel/promotions/ This service can be used to check whether an e-mail address has already been entered into the promotional system and what its status is. Invited only or already converted into a panelist. Request body { "recipientEmail": "example@domain.tld" } Response body [
{
"status": 1234,
"code": "Example",
"date_invited": "2018-07-05T08:37:57+00:00",
"date_converted": "2018-07-05T08:40:00+00:00"
}
]
PUT /panel/promotions/ Sends an invitation as e-mail to a friend. Request body {
"promotionId": 1234,
"recipientEmail": "example@domain.tld",
"header": "Example text",
"footer": "Example text",
"panelistUid": 123
} Response body true
POST /panel/samples/ Sends mails to every panelist in the sample Request body {
"sampleId": 1,
"mailTemplate": {
"subject": "Example",
"textContent": "Example",
"htmlContent": "Example",
"charset": "UTF-8",
"replyTo": "Example",
"returnPath": "Example",
"priority": "NO_PRIORITY",
"sensitivity": "NORMAL",
"notify": "NO_NOTIFICATION",
"toRealname": true,
"from": "Example",
"sms_from": "Example",
"sms_content": "Example",
"cc": "Example",
"bcc": "Example",
"fromRealname": "Example"
},
"dispcodes": [
"10"
],
"sendOptions": {
"sendDate": "2020-07-02T12:53:50+00:00",
"useRecipientTimezone": true
}
} Response body true
Panel statistics
GET /panel/statistics/status Panel status distribution Response body [
{
"code": "1",
"label": "Admitted temporarily",
"value": 26,
"ratio": 0.19259259259259
},
{
"code": "2",
"label": "Active",
"value": 93,
"ratio": 0.68888888888889
}, ...
]
POST /panel/statistics/status Dynamic panel status distribution Request body {
"panelStatisticsFilter": {
"panelCategoryId": 1234,
"panelGroupId": 1234,
"siteId": 1234,
"filterId": 1234,
"from": "2020-07-01T12:53:50+00:00",
"to": "2020-07-03T12:53:50+00:00",
"panelistStatus": [
1234
],
"attributes": [
"Example"
],
"masterdata": [
"Example"
]
}
} Response body [
[
{
"code": "Example",
"label": "Example",
"value": 1234,
"ratio": 1.345
}
]
]
POST /panel/surveys/ get the list of surveys for a panelist Request body { "identifierType": "uid", "identifierValue": "123" } Response body [
{
"id": 1234,
"title": "Example",
"titleGlobal": "Example",
"description": "Example",
"author": "Example",
"staff": "Example",
"comment": "Example",
"url": "http://qb-feedback.com/",
"fieldTime": {
"startTime": "2020-07-02T12:53:50+00:00",
"endTime": "2020-07-02T12:53:50+00:00"
},
"type": "ANONYMOUS",
"bonusPoints": {
"label": "Example",
"value": 1.345
},
"participantsLeft": 1234
}
]
POST /panel/surveys/list Returns the list of EFS Panel surveys (surveys of type panel survey or master data survey) a panelist has completed so far Request body { "identifierType": "uid", "identifierValue": "123" } Response body [
{
"surveyId": 1234,
"surveyTitle": "Some Title",
"surveyDescription": "Example",
"surveyType": "ANONYMOUS",
"completionReward": 1.345,
"completionDate": "2020-07-02T12:53:50+00:00"
}
]
GET /panel/variables/ returns the panel's variables along with their predefined answer codes (if any) Response body [
{
"varname": "m_0000",
"label": "Country",
"type": "int",
"typeGroup": "numeric",
"recoded": false,
"categories": [
{
"code": 3,
"label": "USA"
},
{
"code": 2,
"label": "United Kingdom"
},
{
"code": 1,
"label": "Germany"
},
{
"code": 0,
"label": "Please select"
}
]
}, ...
]
GET /panel/websites/ Returns a list of panel websites Response body [
{
"id": 4,
"name": "Panel Website",
"description": "",
"isDefault": true,
"languages": [
{
"id": 7,
"name": "english",
"isDefault": true
}
]
}
]
Portals
GET /portal/portal/export/{portalId} Get portal export by portalId Response body "{\"isPortalCopy\":true,\"metaData\":{\"name\":\"[...]" URI Parameters Name Type Required Description portalId integer true Export portal with this ID Examples: 2.
POST /portal/portal/import Import portal by using previous export Request body { "portalData": "{\"isPortalCopy\":true,\"metaData\":{\"name\":\"[...]" } Response body "123"
POST /portal/users/getUserDataByToken Checks whether API-token is valid (not expired). Returns userId and portalId. Otherwise will throw an exception. Request body { "apiToken": "Example123" } Response body { "portalUserId": "123", "portalId": "123" }
PUT /portal/users/invitePanelistToPortal Invite Panelists to Portal Request body {
"identifierType": "uid",
"identifierList": [
"123"
],
"portalId": 1234,
"mailTemplateId": 1234
} Response body true
POST /portal/users/logincode Get tmp login code Request body { "identifierType": "uid", "identifierValue": "123" } Response body "1233ffaa123..."
POST /portal/users/setUserRoles Set role(s) for user(s) in portal Request body {
"portalUsersRolesList": [
{
"portalUserId": "123",
"userRoleList": [
"1", "3"
]
}
],
"portalId": "1"
} Response body true
Survey
Languages
GET /survey/languages/{surveyId} get a list of all languages in a survey Response body [
{
"label": "German",
"localestring": "de_DE",
"languageId": 1,
"isStandard": true
}
] URI Parameters Name Type Required Description surveyId integer true surveyId Examples: 2.
GET /survey/languages/{surveyId}/{languageId} get a language Response body {
"label": "German",
"localestring": "de_DE",
"languageId": 1,
"isStandard": true
} URI Parameters Name Type Required Description surveyId integer true surveyId Examples: 2. languageId integer true languageId Examples: 2.
POST /survey/languages/{surveyId} adds a new language Request body {
"language": {
"label": "English",
"localestring": "en_GB",
"adoptTranslationFromId": 1
}
} Response body 1 URI Parameters Name Type Required Description surveyId integer true surveyId Examples: 2.
PATCH /survey/languages/{surveyId} change language data Request body {
"language": {
"label": "Deutsch",
"localestring": "de_DE",
"languageId": 1
}
} Response body true URI Parameters Name Type Required Description surveyId integer true surveyId Examples: 2.
DELETE /survey/languages/{surveyId} deletes a language Request body { "languageId": 1 } Response body true URI Parameters Name Type Required Description surveyId integer true surveyId Examples: 2.
Layouts
GET /survey/layouts/ returns a list of all survey layouts the user has access to Response body [ { "layoutId": 1, "name": "Example" } ]
POST /survey/layouts/find returns a list of survey layouts the user has access to, based on search criteria. See filtering results with conditions for help on building conditions. Request body {
"logicalCondition": {
"comparison": {
"variable": "title",
"operator": "CONTAINS",
"value": "Example"
}
}
} Response body [ { "layoutId": 1, "name": "Example Layout" } ]
PATCH /survey/layouts/{surveyId} Applies a survey layout in a specific survey. Request body { "layoutId": 1 } Response body true URI Parameters Name Type Required Description surveyId integer true survey id Examples: 2.
Static lists
GET /survey/lists/{surveyId} Returns the list of available static lists for a survey Response body [ { "listId": 1234, "label": "Example" } ] URI Parameters Name Type Required Description surveyId integer true id of survey Examples: 2.
POST /survey/lists/{surveyId} Returns the ID of the created static list Request body {
"label": "Example",
"placeholder": "example",
"delimiter": ", ",
"lastDelimiter": " and "
} Response body 123 URI Parameters Name Type Required Description surveyId integer true id of survey Examples: 2.
DELETE /survey/lists/{surveyId}/{listId} Deletes a list URI Parameters Name Type Required Description surveyId integer true id of survey Examples: 2. listId integer true list id Examples: 2.
PUT /survey/lists/{surveyId} Adds an array of static list elements Request body {
"listId": 1,
"items": [
{
"number": 1,
"label": "Apples"
},
{
"number": 2,
"label": "Oranges"
}
]
} Response body [ 1, 2 ] URI Parameters Name Type Required Description surveyId integer true id of survey Examples: 2.
PUT /survey/lists/{surveyId}/{listId} Adds a static list element Request body {
"label": "Pears",
"number": 3
} Response body 1 URI Parameters Name Type Required Description surveyId integer true id of survey Examples: 2. listId integer true list id Examples: 2.
DELETE /survey/lists/{surveyId}/{listId}/elements Clears a list URI Parameters Name Type Required Description surveyId integer true id of survey Examples: 2. listId integer true id of list Examples: 2.
Participants
POST /survey/participants/v2/{sampleId} Add multiple participants to a survey. Only u_email is required and you can skip all other fields. Additional participant variables can be filled through additionalFields. When providing u_passwd, please note that this field needs to be unique. Valid options for returnIdentifierType are u_email, code and uid. u_email is only available if allowDuplicateEmails is set to false. POST /survey/participants/{sampleId}, without v2, should no longer be used, as it was replaced with this call. To migrate your application to the new call, add allowDuplicateEmails to the old request and change the end point to …/v2/. Also, in personalised projects, the sampleId is the surveyId plus 1. Request body {
"returnIdentifierType": "code",
"participantList": [
{
"u_passwd": "123456",
"u_firstname": "First",
"u_name": "Last",
"u_email": "example@domain.tld",
"u_mobile": "0049123456",
"u_title": "Dr.",
"u_gender": "NOT_SPECIFIED",
"u_group": 1,
"u_language": 1,
"u_timezone": "+0:00",
"additionalFields": [
{
"key": "u_example",
"value": "test"
}
]
}
],
"allowDuplicateEmails": true
} Response body [ "fd68114f34314916" ] URI Parameters Name Type Required Description sampleId integer true id of sample to add the participants to Examples: 2.
POST /survey/participants/v3/{sampleId} Add multiple participants to a survey via task queue. Returns taskId which has to be used to get results via GET /efs/taskqueue/{taskId}. This is the recommended call for importing bigger batches of participants to a survey and this call is request body compatible to /v2. Request body {
"returnIdentifierType": "u_email",
"participantList": [
{
"u_passwd": "123456",
"u_firstname": "First",
"u_name": "Last",
"u_email": "example@domain.tld",
"u_mobile": "0049123456",
"u_title": "Dr.",
"u_gender": "NOT_SPECIFIED",
"u_group": 1,
"u_language": 1,
"u_timezone": "+0:00",
"additionalFields": [
{
"key": "u_example",
"value": "test"
}
]
}
],
"allowDuplicateEmails": true
} Response body 1234 URI Parameters Name Type Required Description sampleId integer true id of sample to add the participants to Examples: 2.
POST /survey/participants/{sampleId}/csv Add multiple participants from a CSV file to a survey or update existing participants using data from a CSV file. Note: this operation works on surveys of type "personalized" only. Unlike in the interface, the first row of the CSV data needs to have the correct column labels from the import template of the project. Only u_email is required. This call corresponds to the participant import of the participant administration. returnIdentifierType returns the specified identifier variable as internalReturnValue, usually you will want to know the “uid” of the participant. mappingColumn returns the specified participant variable as externalReturnValue. This can used to store back information in your system, e.g. by uploading u_crm_id in your CSV data and using that variable as a mappingColumn. Request body {
"csvData": "u_email,u_first,u_name\nexample@domain.tld,First,Last\nexample2@domain.tld,First2,Last2",
"returnIdentifierType": "uid",
"allowDuplicateEmails": true,
"mappingColumn": "u_email"
} Response body {
"successful": 3,
"failed": -1,
"failedRows": [],
"returnIdentifiers": [
{
"internalReturnValue": "1",
"externalReturnValue": "example@domain.tld"
},
{
"internalReturnValue": "2",
"externalReturnValue": "example2@domain.tld"
}
]
} URI Parameters Name Type Required Description sampleId integer true id of sample to add the participants to or to update the participants in Examples: 2.
POST /survey/participants/{sampleId}/csv2 Add multiple participants and optionally survey results from a CSV file to a survey or update existing participants using data from a CSV file. Note: this operation works on surveys of type “personalized” or “employee” only. Unlike in the interface, the first row of the CSV data needs to have the correct column labels from the import template of the project. Unless status is specified, the disposition code will be automatically set to 31 - Completed. This call corresponds to the results import of the participant administration. returnIdentifierType returns the specified identifier variable as internalReturnValue, usually you will want to know the “uid” of the participant. mappingColumn returns the specified participant variable as externalReturnValue. This can used to store back information in your system, e.g. by uploading u_crm_id in your CSV data and using that variable as a mappingColumn. Request body {
"csvData": "u_email,u_first,u_name,v_1\nexample@domain.tld,First,Last,2\nexample2@domain.tld,First2,Last2,1",
"returnIdentifierType": "uid",
"allowDuplicateEmails": true,
"mappingColumn": "u_email"
} Response body {
"successful": 3,
"failed": -1,
"failedRows": [],
"returnIdentifiers": [
{
"internalReturnValue": "1",
"externalReturnValue": "example@domain.tld"
},
{
"internalReturnValue": "2",
"externalReturnValue": "example2@domain.tld"
}
]
} URI Parameters Name Type Required Description sampleId integer true id of sample to add the participants to Examples: 2.
PUT /survey/participants/{sampleId}/updateParticipantVariablesList Updates user's participant variables for given sample ID. Only available for personalized surveys. Returns list of participation data with updated values. Unknown participations and unknown variables are removed, invalid values will be replaced by standard values. Request body {
"participantVariablesList": [
{
"uid": 1,
"variables": [
{
"variable": "u_example",
"value": "Example"
}
]
}
]
} Response body [
{
"uid": 1,
"variables": [
{
"variable": "u_example",
"value": "Example"
}
]
}
] URI Parameters Name Type Required Description sampleId integer true id of survey Examples: 2.
GET /survey/participants/v2/{sampleId}/{additionalInfo} Returns a list of participants. The operation is allowed for personalized surveys only. If the parameter withAdditionalFields is set to true, additional variables for participant will be returned. Response body [
{
"uid": 1,
"u_passwd": "ZDhjNDA2OGY=",
"u_firstname": "First",
"u_name": "Last",
"u_email": "example@domain.tld",
"u_mobile": "",
"u_title": "",
"u_gender": "NOT_SPECIFIED",
"u_group": 0,
"m_date": "2020-02-18T12:33:19+00:00",
"c_date": "2020-02-18T11:39:29+00:00",
"u_timezone": "+0:00"
}, ...
] URI Parameters Name Type Required Description sampleId integer true sample to query Examples: 2. additionalInfo boolean true Flag for the additional information to participant Examples: true.
POST /survey/participants/{sampleId}/find Returns a list of participants according to the specified sample. The operation is allowed for personalized surveys only. The size of result set can be limited by using parameter 'offset' and 'limit'. Use parameter 'withAdditionalFields' in order to get the additional information for participant or suppress it. See filtering results with conditions for help on building conditions. Request body {
"logicalCondition": {
"comparison": {
"variable": "u_email",
"operator": "CONTAINS",
"value": "example"
}
},
"offset": 0,
"limit": 10,
"additionalInfo": false
} Response body [
{
"uid": 19,
"u_passwd": "MjRkM2ZiZWE=",
"u_firstname": "First",
"u_name": "Last",
"u_email": "example@domain.tld",
"u_mobile": "",
"u_title": "",
"u_gender": "NOT_SPECIFIED",
"u_group": 0,
"m_date": "2020-08-28T08:24:11+00:00",
"c_date": "2020-08-28T08:24:11+00:00",
"u_timezone": "+0:00"
}
] URI Parameters Name Type Required Description sampleId integer true sample to query Examples: 2.
DELETE /survey/participants/{sampleId} Deletes all participants from sample of a personalised or anonymous survey project, including their already collected survey results. Response body true URI Parameters Name Type Required Description sampleId integer true id of sample Examples: 2.
DELETE /survey/participants/{sampleId}/{userId} delete a participant from a survey sample, along with any already collected survey results for the participant Response body true URI Parameters Name Type Required Description sampleId integer true id of sample Examples: 2. userId integer true id of participant Examples: 2.
PATCH /survey/participants/{surveyId}/reset Resets a survey participation for participant. Existing survey data can be kept or deleted. The operation is allowed for personalized surveys only. Valid options for resetType are keepData, deleteData. Request body {
"participantIdentifierType": "u_email",
"participantIdentifierValue": "example@domain.tld",
"resetType": "keepData"
} Response body true URI Parameters Name Type Required Description surveyId integer true Survey id Examples: 2.
PATCH /survey/participants/{sampleId} Sends mails to participants in a sample. Request is not available for anonymous surveys. With dis-codes you can decide which participants will receive the mail, e.g. when sending a reminder email, use codes 11 and 12 (and 10 in GDPR enabled projects). Request body {
"uids": [
1
],
"mailTemplateId": 1234,
"dispcodes": [
"11", "12"
],
"sendOptions": {
"sendDate": "2020-07-02T12:53:50+00:00",
"useRecipientTimezone": true
}
} URI Parameters Name Type Required Description sampleId integer true id of sample Examples: 2.
PUT /survey/participants/{surveyId} Sends mails to every participiant in a survey. Please note This service will fail on anonymous surveys and sending of SMS is not supported by this service. Request body {
"mailTemplate": {
"subject": "Example",
"textContent": "Example",
"htmlContent": "Example",
"charset": "UTF-8",
"replyTo": "Example",
"returnPath": "Example",
"priority": "NO_PRIORITY",
"sensitivity": "NORMAL",
"notify": "NO_NOTIFICATION",
"toRealname": true,
"from": "Example",
"sms_from": "Example",
"sms_content": "Example",
"cc": "Example",
"bcc": "Example",
"fromRealname": "Example"
},
"uids": [
1
],
"dispcodes": [
"10"
],
"sendOptions": {
"sendDate": "2020-07-02T12:53:50+00:00",
"useRecipientTimezone": true
}
} URI Parameters Name Type Required Description surveyId integer true Survey id Examples: 2.
Samples
GET /survey/samples/ return the list of samples for all surveys Response body [
{
"sampleId": 2287,
"title": "(internal)",
"desc": "",
"cdate": "2020-02-13T10:11:11+00:00",
"isInternal": true,
"surveyId": 2286
}, ...
]
GET /survey/samples/survey/{surveyId} return the list of samples for a survey Response body [
{
"sampleId": 2287,
"title": "(internal)",
"desc": "",
"cdate": "2020-02-13T10:11:11+00:00",
"isInternal": true,
"surveyId": 2286
}
] URI Parameters Name Type Required Description surveyId integer true id of survey Examples: 2.
GET /survey/samples/sample/{sampleId} return information about a survey sample Response body {
"sampleId": 2287,
"title": "(internal)",
"desc": "",
"cdate": "2020-02-13T10:11:11+00:00",
"isInternal": true,
"surveyId": 2286
} URI Parameters Name Type Required Description sampleId integer true id of the sample Examples: 2.
POST /survey/samples/{pid} Add a sample to a survey Request body { "title": "Example", "description": "Example sample" } Response body 1234 URI Parameters Name Type Required Description pid integer true project id Examples: 2.
Placeholders
GET /survey/placeholders/{surveyId} Returns a list of all survey wildcards for a given survey id, text is using default survey language. Response body [
{
"id": 3,
"key": "#example#",
"text": "Hello Example"
}
] URI Parameters Name Type Required Description surveyId integer true id of survey Examples: 2.
GET /survey/placeholders/{surveyId}/{languageId} Returns a list of all translated survey wildcards for a given survey id and survey language id Response body [
{
"id": 3,
"key": "#example#",
"text": "Hello Example"
}
] URI Parameters Name Type Required Description surveyId integer true id of survey Examples: 2. languageId integer true survey language id the placeholder texts should be returned for Examples: 2.
PATCH /survey/placeholders/{surveyId}/{id} Change an existing survey wildcard text in the default survey language Request body { "text": "Hallo Example" } Response body true URI Parameters Name Type Required Description surveyId integer true id of survey Examples: 2. id integer true id of placeholder to change Examples: 2.
PUT /survey/placeholders/{surveyId}/{languageId} Change an existings survey wildcards text in a certain survey language Request body { "id": 1, "text": "Example" } Response body true URI Parameters Name Type Required Description surveyId integer true id of survey Examples: 2. languageId integer true survey language id the placeholder texts should be returned for Examples: 2.
Questionnaire
GET /survey/questionnaire/{surveyId} Return the questionnaire structure for a survey Response body [
{
"title": "System",
"pgid": 1712,
"type": "SYSTEM",
"questions": [
{
"questiontext": "",
"variables": []
}
],
"subPages": []
},
{
"title": "End page",
"pgid": 1714,
"type": "ENDPAGE",
"questions": [],
"subPages": []
}
] URI Parameters Name Type Required Description surveyId integer true survey id Examples: 2.
GET /survey/questionnaire/withIds/{surveyId} Return the questionnaire structure for a survey with internal IDs for all elements Response body [
{
"title": "System",
"pgid": 1712,
"type": "SYSTEM",
"questions": [
{
"questiontext": "",
"variables": []
}
],
"subPages": []
},
{
"title": "End page",
"pgid": 1714,
"type": "ENDPAGE",
"questions": [],
"subPages": []
}
] URI Parameters Name Type Required Description surveyId integer true survey id Examples: 2.
POST /survey/questionnaire/{surveyId} create a questionnaire page Request body {
"pageTitle": "Example",
"pageType": "STANDARD",
"options": {
"hideSubmit": false,
"hideBackbutton": true,
"autoPost": false,
"parentPageId": -1,
"previousPageId": 1
}
} Response body 1 URI Parameters Name Type Required Description surveyId integer true survey id Examples: 2.
DELETE /survey/questionnaire/{surveyId} delete a questionnaire page Request body { "pageId": 1, "force": true } Response body true URI Parameters Name Type Required Description surveyId integer true survey id Examples: 2.
GET /survey/questionnaire/{surveyId}/list Returns the configured bonus points for all end pages to the given surveyId, panel or master data surveys only. Response body [ { "pageId": 1234, "points": 10.0 } ] URI Parameters Name Type Required Description surveyId integer true Survey ID Examples: 2.
PUT /survey/questionnaire/{surveyId}/setPageBonusPoints Applies bonus points to survey end-pages for the given surveyId, panel or master data surveys only. Request body {
"pageBonusPoints": [
{
"pageId": 1234,
"points": 10.0
}
]
} Response body [ { "pageId": 1234, "points": 10.0 } ] URI Parameters Name Type Required Description surveyId integer true id of survey Examples: 2.
GET /survey/questions/{surveyId}/{varname} Get response-categories by variable name and survey id Response body [
{
"code": 0,
"rcat": "Unspecified"
},
{
"code": 1,
"rcat": "Male"
},
{
"code": 2,
"rcat": "Female"
},
{
"code": 3,
"rcat": "Other"
}
] URI Parameters Name Type Required Description surveyId integer true id of survey Examples: 2. varname string true variable name Examples: Example.
Reporting+
POST /survey/reports/{surveyId} Create a standard Reporting+ report for a survey Request body { "title": "Example", "description": "Example" } Response body 1 URI Parameters Name Type Required Description surveyId integer true id of survey Examples: 2.
POST /survey/reports/v2/{reportId}/publication Create a Reporting+ export, valid options for reportType: html, xls, pdf, ppt, pptx, pptxpdf Request body {
"reportType": "html",
"fileName": "Example.html",
"languageId": 1,
"guiLanguage": "en"
} Response body 1 URI Parameters Name Type Required Description reportId integer true id of survey report (to be created with createStandardReport) Examples: 2.
DELETE /survey/reports/{reportId} Delete a Reporting+ export Response body true URI Parameters Name Type Required Description reportId integer true id of survey report (to be created with createStandardReport) Examples: 2.
GET /survey/reports/{reportId}/publication/{reportPublicationId} return the data for a publication Response body "QmFzZTY0IGVuY29kZWQgYmluYXJ5IGRhdGE=" URI Parameters Name Type Required Description reportId integer true id of report Examples: 2. reportPublicationId integer true id of publication Examples: 2.
GET /survey/reports/{reportId}/published/{reportPublicationId} Check if report is available Response body true URI Parameters Name Type Required Description reportId integer true id of report Examples: 2. reportPublicationId integer true id of publication Examples: 2.
Survey participations
POST /survey/results/{surveyId}/configured Returns the survey results as raw data in CSV format. dateRange, sort, config and individual config options are optional.
Valid options for exportTemplate: COMPLETE_SURVEY, WITHOUT_TIMESTAMP, TEXT_ONLY, NUMBER_ONLY, PARTICIPANT, PARTICIPANT_RESULT, PARTICIPANT_MASTER_RESULT, LOFT_COMBINED, LOFT_COMBINED_ANONYM.
Valid options for compression: NONE, ZIP, TAR. Note: POST /survey/results/{surveyId}/completed and POST /survey/results/{surveyId} are deprecated. Please migrate to this call by adding /configured to your endpoint and supplying relevant config options. Request body {
"exportTypes": [
"QUESTIONNAIRE"
],
"includeVariables": [
"v_1", "v_2"
],
"dateRange": {
"from": "2020-07-01T12:53:50+00:00",
"to": "2020-07-02T12:53:50+00:00"
},
"sort": [
{
"column": "lfdn",
"direction": "ASC"
}
],
"config": {
"exportTemplate": "COMPLETE_SURVEY",
"charset": "UTF-8",
"compression": "NONE",
"missingValueText": "-66",
"missingValueNumeric": "-77",
"missingValueTimestamp": "0",
"missingValueDatetime": "0000-00-00 00:00:00",
"skipLoopVars": true,
"dispositionCodeList": [
"31"
],
"useCommaDelimiter": true
}
} Response body "QmFzZTY0IGVuY29kZWQgYmluYXJ5IGRhdGE=" URI Parameters Name Type Required Description surveyId integer true id of survey Examples: 2.
GET /survey/results/{surveyId}/participations Return frequencies for all disposition codes allocated in a survey, thus basic information about the survey's participation statuses. Response body [
{
"code": 11,
"count": 8
},
{
"code": 12,
"count": 2
},
{
"code": 31,
"count": 6
}
] URI Parameters Name Type Required Description surveyId integer true id of survey Examples: 2.
GET /survey/results/{surveyId}/statistics return frequency statistics for all closed-ended questions of a survey Response body [
{
"singleResultStatistic": {
"varname": "v_2",
"codeResultList": [
{
"code": 1,
"count": 1,
"pct": 0
},
{
"code": 2,
"count": 1,
"pct": 0
}
]
}
},
{
"multiResultStatistic": {
"varname": "v_4",
"codeResult": {
"code": 1,
"count": 3,
"pct": 0
}
}
}
] URI Parameters Name Type Required Description surveyId integer true id of survey Examples: 2.
POST /survey/results/{surveyId}/statistics Get simple statistics for given panelist and variable list. Only available in panel and master data variables. Request body {
"identifierType": "uid",
"identifierValue": "123",
"includeVariables": [
"v_1"
]
} Response body [
{
"singleResultStatistic": {
"varname": "v_1",
"codeResultList": [
{
"code": 1,
"count": 3,
"pct": 33
},
{
"code": 2,
"count": 3,
"pct": 33
},
{
"code": 3,
"count": 3,
"pct": 33
}
],
"mean": 2,
"median": 2
}
}
] URI Parameters Name Type Required Description surveyId integer true id of survey Examples: 2.
PUT /survey/results/{surveyId}/updateSurveyResults Updates participation data for given survey ID. Participations are matched by lfdn (id). Only available for anonymous, personalized and employee surveys. Supports update of user- and survey-variables and not loop-variables. If parameter executeTriggers is set to true, then only 100 records can be processed due to performance reasons, more records will cause an error. Returns list of participation data with updated values. Unknown participations or unknown variables will be removed, invalid values will be replaced by standard values. Request body {
"surveyResults": [
{
"id": 1234,
"results": [
{
"variable": "v_1",
"value": "2"
}
]
}
],
"executeTriggers": true
} Response body [
{
"id": 1234,
"results": [
{
"variable": "v_1",
"value": "2"
}
]
}
] URI Parameters Name Type Required Description surveyId integer true id of survey Examples: 2.
Field report / Statistics
POST /survey/statistics/{surveyId}/chart Returns the png graph which represents the participation. Valid values for lang: EN, DE, FR, FI, IT, NB, SV Request body {
"lang": "EN",
"restriction": [
{
"field_name": "v_2",
"field_link": " IN ",
"field_value": "1, 2, 3"
}
]
} Response body "QmFzZTY0IGVuY29kZWQgYmluYXJ5IGRhdGE=" URI Parameters Name Type Required Description surveyId integer true The survey ID Examples: 2.
POST /survey/statistics/{surveyId}/abs Returns the absolute number of participation for a single disposition code and optionally limited by restriction. Valid values for field_link: IN, BETWEEN, LIKE, NOT LIKE, =, !=, <>, <, <=, >, >=. Values LIKE, NOT LIKE should only be applied to text variables and to search for a substring, append “%”: E.g. “%world” will map “Hello World” but not “World, Hello”, search for “%world%” will find both occurrences. Please note, contrary to the RAML and WSDL documentations, the use of splitVariable in criteria is not supported and returns erroneous result. An updated service will be provided shortly. Request body {
"criteria": {
"dispositionCodes": [
"31"
]
},
"restriction": [
{
"field_name": "v_2",
"field_link": "IN",
"field_value": "1, 2, 3"
}
]
} Response body 1234 URI Parameters Name Type Required Description surveyId integer true The survey ID Examples: 2.
POST /survey/statistics/{surveyId}/abs/all Returns the absolute number of participation for all disposition codes, optionally restricted by condition.
Valid values for field_link: IN, BETWEEN, LIKE, NOT LIKE, =, !=, <>, <, <=, >, >=. Values LIKE, NOT LIKE should only be applied to text variables and to search for a substring, append “%”: E.g. “%world” will map “Hello World” but not “World, Hello”, search for “%world%” will find both occurrences. Request body {
"restriction": [
{
"field_name": "v_2",
"field_link": "IN",
"field_value": "1, 2, 3"
}
]
} Response body [ { "code": "10", "count": 1234 } ] URI Parameters Name Type Required Description surveyId integer true The survey ID Examples: 2.
POST /survey/statistics/{surveyId}/abs/filter Returns a list of the number/s of participation by disposition code/s and/or split-variable. Valid values for field_link: IN, BETWEEN, LIKE, NOT LIKE, =, !=, <>, <, <=, >, >=. Values LIKE, NOT LIKE should only be applied to text variables and to search for a substring, append “%”: E.g. “%world” will map “Hello World” but not “World, Hello”, search for “%world%” will find both occurrences. POST /survey/statistics/{surveyId}/abs/all and POST /survey/statistics/{surveyId}/abs are similar to this call, but return only a single total value. Please note, contrary to the RAML and WSDL documentations, the use of splitVariable in criteria is not supported and returns erroneous result. An updated service will be provided shortly. Request body {
"criteria": {
"dispositionCodes": [
"31", "32"
]
},
"restriction": [
{
"field_name": "v_2",
"field_link": "IN",
"field_value": "1, 2, 3"
}
]
} Response body [
{
"code": 1,
"count": 10
},
{
"code": 2,
"count": 8
},
{
"code": 3,
"count": 4
}
] URI Parameters Name Type Required Description surveyId integer true The survey ID Examples: 2.
POST /survey/statistics/{surveyId}/gross Returns the total sample (Gross 1) for the project. Valid values for field_link: IN, BETWEEN, LIKE, NOT LIKE, =, !=, <>, <, <=, >, >=. Values LIKE, NOT LIKE should only be applied to text variables and to search for a substring, append “%”: E.g. “%world” will map “Hello World” but not “World, Hello”, search for “%world%” will find both occurrences. Please note, contrary to the RAML and WSDL documentations, the use of splitVariable is not supported and returns erroneous result. An updated service will be provided shortly. Request body {
"restriction": [
{
"field_name": "v_2",
"field_link": "IN",
"field_value": "1, 2, 3"
}
]
} Response body 1234 URI Parameters Name Type Required Description surveyId integer true The survey ID Examples: 2.
POST /survey/statistics/{surveyId}/gross2 Returns the adjusted total sample (Gross 2) for the project. Valid values for field_link: IN, BETWEEN, LIKE, NOT LIKE, =, !=, <>, <, <=, >, >=. Values LIKE, NOT LIKE should only be applied to text variables and to search for a substring, append “%”: E.g. “%world” will map “Hello World” but not “World, Hello”, search for “%world%” will find both occurrences. Please note, contrary to the RAML and WSDL documentations, the use of splitVariable is not supported and returns erroneous result. An updated service will be provided shortly. Request body {
"restriction": [
{
"field_name": "v_2",
"field_link": "IN",
"field_value": "1, 2, 3"
}
]
} Response body 1234 URI Parameters Name Type Required Description surveyId integer true The survey ID Examples: 2.
POST /survey/statistics/{surveyId}/net Returns the net-participation for the project. Valid values for field_link: IN, BETWEEN, LIKE, NOT LIKE, =, !=, <>, <, <=, >, >=. Values LIKE, NOT LIKE should only be applied to text variables and to search for a substring, append “%”: E.g. “%world” will map “Hello World” but not “World, Hello”, search for “%world%” will find both occurrences. Please note, contrary to the RAML and WSDL documentations, the use of splitVariable is not supported and returns erroneous result. An updated service will be provided shortly. Request body {
"restriction": [
{
"field_name": "v_2",
"field_link": "IN",
"field_value": "1, 2, 3"
}
]
} Response body 1234 URI Parameters Name Type Required Description surveyId integer true The survey ID Examples: 2.
POST /survey/statistics/{surveyId}/disposition/filter Returns the absolute number of participation for a list of disposition codes, limited by restriction, split by a variable. This service allows use of u_ variables for filtering or splits. Valid values for field_link: IN, BETWEEN, LIKE, NOT LIKE, =, !=, <>, <, <=, >, >=. Values LIKE, NOT LIKE should only be applied to text variables and to search for a substring, append “%”: E.g. “%world” will map “Hello World” but not “World, Hello”, search for “%world%” will find both occurrences. Request body {
"criteria": {
"dispositionCodes":["11","12","22","31","32"],
"splitVariable":"u_gender"
},
"restriction": [
{
"field_name": "v_2",
"field_link": "IN",
"field_value": "1, 2, 3"
}
]
} Response body [
{
"value": "-1",
"total": 19,
"participation": [
{
"code": "11",
"count": 1
},
{
"code": "12",
"count": 6
},
{
"code": "22",
"count": 1
},
{
"code": "31",
"count": 11
}
]
},
{
"value": "Not available",
"total": 1,
"participation": [
{
"code": "11",
"count": 1
}
]
},
{
"value": "-1",
"total": 1,
"participation": [
{
"code": "31",
"count": 1
}
]
}
] URI Parameters Name Type Required Description surveyId integer true The survey ID Examples: 2.
Surveys
GET /survey/surveys/ Get a list of surveys the user has access to Response body [
{
"id": 1234,
"title": "Example title",
"description": "Example description",
"marked": true,
"author": "Example",
"staff": "",
"comment": "",
"isMarked": false,
"url": "http://example.questback.com/uc/main/1234/",
"createTime": "2020-07-02T12:53:50+00:00",
"fieldTime": {
"startTime": "2020-07-02T12:53:50+00:00",
"endTime": "2020-08-02T12:53:50+00:00"
},
"status": "ACTIVE",
"type": "ANONYMOUS",
"numberOfParameters": 0,
"bonusPoints": {
"label": "",
"value": 0
}
}
]
POST /survey/surveys/find Returns a list of surveys the user has access to, based on search criteria. See filtering results with conditions for help on building conditions. Request body {
"logicalCondition": {
"comparison": {
"variable": "title",
"operator": "CONTAINS",
"value": "Example"
}
}
} Response body [
{
"id": 1234,
"title": "Example title",
"description": "Example description",
"marked": true,
"author": "Example",
"staff": "",
"comment": "",
"isMarked": false,
"url": "http://example.questback.com/uc/main/1234/",
"createTime": "2020-07-02T12:53:50+00:00",
"fieldTime": {
"startTime": "2020-07-02T12:53:50+00:00",
"endTime": "2020-08-02T12:53:50+00:00"
},
"status": "ACTIVE",
"type": "ANONYMOUS",
"numberOfParameters": 0,
"bonusPoints": {
"label": "",
"value": 0
}
}
]
GET /survey/surveys/find/active Get a list of active surveys the user has access to Response body [
{
"id": 1234,
"title": "Example title",
"description": "Example description",
"marked": true,
"author": "Example",
"staff": "",
"comment": "",
"isMarked": false,
"url": "http://example.questback.com/uc/main/1234/",
"createTime": "2020-07-02T12:53:50+00:00",
"fieldTime": {
"startTime": "2020-07-02T12:53:50+00:00",
"endTime": "2020-08-02T12:53:50+00:00"
},
"status": "ACTIVE",
"type": "ANONYMOUS",
"numberOfParameters": 0,
"bonusPoints": {
"label": "",
"value": 0
}
}
]
GET /survey/surveys/{surveyId} Get basic information about a survey Response body {
"id": 1234,
"title": "Example title",
"description": "Example description",
"marked": true,
"author": "Example",
"staff": "",
"comment": "",
"isMarked": false,
"url": "http://example.questback.com/uc/main/1234/",
"createTime": "2020-07-02T12:53:50+00:00",
"fieldTime": {
"startTime": "2020-07-02T12:53:50+00:00",
"endTime": "2020-08-02T12:53:50+00:00"
},
"status": "ACTIVE",
"type": "ANONYMOUS",
"numberOfParameters": 0,
"bonusPoints": {
"label": "",
"value": 0
}
} URI Parameters Name Type Required Description surveyId integer true id of survey to delete Examples: 2.
POST /survey/surveys/ Creates a new survey, returns project id. Valid options for type: ANONYMOUS, PERSONALIZED, ES, LOFT, PANEL, GEN_MASTERDATA, DIARY. Request body {
"surveyData": {
"title": "Example title",
"author": "Example",
"type": "ANONYMOUS",
"description": "Example description",
"staff": "",
"comment": ""
}
} Response body 1234
PATCH /survey/surveys/{surveyId} Change a survey's field period and status. Valid options for surveyStatus: GENERATED, ACTIVE, CLOSING, FINISHED, ARCHIVED Request body {
"surveyStatus": "ACTIVE",
"surveyFieldTime": {
"startTime": "2020-07-02T12:53:50+00:00",
"endTime": "2020-08-02T12:53:50+00:00"
}
} Response body true URI Parameters Name Type Required Description surveyId integer true id of survey to delete Examples: 2.
PUT /survey/surveys/{surveyId} Change a survey's descriptive data (survey title, survey comment etc.) Request body {
"title": "New Title",
"description": "Example description",
"author": "Example author",
"staff": "Example staff field",
"comment": "Example comment",
"isMarked": true
} URI Parameters Name Type Required Description surveyId integer true id of survey to delete Examples: 2.
DELETE /survey/surveys/{surveyId} Deletes a survey Response body true URI Parameters Name Type Required Description surveyId integer true id of survey to delete Examples: 2.
PATCH /survey/surveys/{surveyId}/compile Compiles the survey. Creates all missing variable names and resets the participants if requested. You need the write ACL right to perform this action. Options for surveyCompilationType: keep_results, delete_results, delete_tester. Request body { "surveyCompilationType": "keep_results" } Response body true URI Parameters Name Type Required Description surveyId integer true id of survey Examples: 2.
POST /survey/surveys/{surveyId}/copy Copies a survey Request body { "title": "Copy of Example" } Response body 1234 URI Parameters Name Type Required Description surveyId integer true id of survey to copy Examples: 2.
PATCH /survey/surveys/{surveyId}/type Change the type of a survey. Valid types for surveyType: ANONYMOUS, PERSONALIZED, ES, LOFT, PANEL, GEN_MASTERDATA, DIARY Request body { "surveyType": "ANONYMOUS" } Response body true URI Parameters Name Type Required Description surveyId integer true survey to change Examples: 2.
GET /survey/surveys/{surveyId}/previewlink Uses the admin session in the url Response body "Example" URI Parameters Name Type Required Description surveyId integer true id of survey Examples: 2.
POST /survey/variables/{surveyId} Returns description of survey's variables, machine readable version of the code book. Valid options for surveyVariableTypes: STANDARD, PARTICIPANT, QUESTIONNAIRE, QUESTIONNAIRE_WITH_LOOPS, PARTICIPATION, INTERNAL. Request body { "surveyVariableTypes": [ "STANDARD" ] } Response body [
{
"varname": "quota_rejected_id",
"label": "Rejection quota ID of participant",
"type": "int",
"typeGroup": "numeric"
},
{
"varname": "language",
"label": "Language",
"type": "int",
"typeGroup": "numeric",
"categories": [
{
"code": 1,
"label": "English",
"isMissing": false
},
{
"code": 2,
"label": "German",
"isMissing": false
},
{
"code": 3,
"label": "French",
"isMissing": false
}
]
},
[...]
] URI Parameters Name Type Required Description surveyId integer true survey id Examples: 2.
POST /survey/surveys/export Exports survey results according to the given configuration. Please note, that the example is showing all possible options, and is therefore not working. Only surveyId, compression, exportType, exportFileFormat and exportTemplate are required parameters. For full description of export options, see the project export mask in the EFS user interface and the relevant documentation. The returned data is always base64 encoded and in addition, depending on the gzCompression boolean parameter, the data will be compressed using the zlib format (if true, gzcompress PHP function) or encoded using the gzip format (if false, gzencode PHP function). When handling the returned data, you first need to base64 decode it, then apply the equivalent to PHP's gzuncompress() or gzdecode() functions for your platform, then you will receive your data in the specified format, which depending on the compression parameter might additionally be compressed. Please note, that not all exportConfig parameters are supported by all export types, where in doubt, please consult the relevant export user interfaces in EFS Admin area. E.g. for exportType=PARTICIPANT_DATA and exportTemplate=PARTICIPANT, startDate and endDate will be ignored, since they are not available in the export UI of EFS. Name Valid options compression NONE, ZIP, TAR protected ALL, PROTECTED_ONLY, UNPROTECTED_ONLY exportType ALL_ANSWERS, RAW_LOOP_DATA, TEXT_ANSWERS, PARTICIPANT_DATA exportFileFormat CSV, XLS, XLSX, TRIPLE_S, TOP_STUD, XML, HTML, SPSS, SPSS_PORTABLE, SAS, FIXED_FORMAT, QUANTUM exportTemplate COMPLETE_SURVEY, WITHOUT_TIMESTAMP, TEXT_ONLY, NUMBER_ONLY, PARTICIPANT, PARTICIPANT_RESULT, PARTICIPANT_MASTER_RESULT, LOFT_COMBINED, LOFT_COMBINED_ANONYM varNameType INTERNAL, EXTERNAL quantumTextOption NONE, ALL, SURVEY', 'INTERNAL Request body {
"exportConfig": {
"surveyId": 1234,
"sampleId": 1,
"languageId": 1,
"compression": "NONE",
"skipMissings": true,
"restrict": "Example",
"anonymize": true,
"trimNewlines": true,
"substituteCode": true,
"displayMetaInfo": true,
"shrinkColumnWidth": true,
"adjustColumnWidth": true,
"includeSysMissings": true,
"consecutiveNrFrom": 0,
"consecutiveNrTo": 0,
"protected": "ALL",
"dispositionCodeList": [
"31"
],
"exportType": "ALL_ANSWERS",
"exportFileFormat": "CSV",
"exportTemplate": "COMPLETE_SURVEY",
"charset": "UTF-8",
"missingValueText": "-66",
"missingValueTextEmpty": "-",
"missingValueNumeric": "-77",
"missingValueTimestamp": "0",
"missingValueDatetime": "0000-00-00 00:00:00",
"startDate": "2020-07-02T12:53:50+00:00",
"endDate": "2020-07-02T12:53:50+00:00",
"varNameType": "INTERNAL",
"quantumTextOption": "NONE",
"panelGroup": 1,
"panelistStatusList": [
1
],
"gzCompression": true,
"modifiedOnly": true,
"trackModification": true,
"varNameRestriction": [
"v_1", "v_2"
],
"skipLoopVars": true,
"cutPsppColumns": true,
"useCommaDelimiter": true
}
} Response body "QmFzZTY0IGVuY29kZWQgYmluYXJ5IGRhdGE="
GET /survey/timelog/{surveyId} Returns a performance data structure for a survey. Response body [
{
"pgid": 1094,
"log_date": "2020-01-21T10:34:05+00:00",
"servertime": 0.61,
"serverload": 0,
"include_time": 0.0240839,
"db_time": 0.106218,
"output_time": 0.39797
}
] URI Parameters Name Type Required Description surveyId integer true Id of a survey Examples: 2.
PUT /survey/timelog/{surveyId} Resets all performance data used when accessing the OSPE time log. Response body true URI Parameters Name Type Required Description surveyId integer true Id of a survey Examples: 2.
Translations
GET /survey/translations/{surveyId}/{languageId} Gets a list of all translations for the specified language Response body [
{
"typeId": 0,
"textType": "msg_title",
"text": "Survey"
},
[...]
{
"typeId": 0,
"textType": "msg_submit",
"text": "Continue"
},
[...]
{
"typeId": 1380,
"textType": "q_instruct",
"text": "Here you explain how the question has to be filled in (optional)."
},
[...]
] URI Parameters Name Type Required Description surveyId integer true surveyId Examples: 2. languageId integer true languageId Examples: 2.
PATCH /survey/translations/{surveyId}/{languageId} Changes a translation Request body {
"textType": "q_instruct",
"typeId": 1234,
"text": "New Example"
} Response body true URI Parameters Name Type Required Description surveyId integer true surveyId Examples: 2. languageId integer true languageId Examples: 2.