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

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.

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

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

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

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

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
}

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

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

GET /efs/teams/{teamId}

Retrieves the data of an EFS team

Response body

{
  "teamId": 1,
  "teamName": "Example",
  "teamTitle": "Example",
  "teamDesription": "Example description"
}

URI Parameters

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

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

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

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

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

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

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

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

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

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

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

DELETE /gdpr/survey/{surveyId}

Deletes personal data of all participants for given surveyId

Response body

true

URI Parameters

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

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

GET /loft/participants/{project_id}/{fid}

Get feedback center user data

Response body

"Encoded Feedback Center data"

URI Parameters

GET /loft/participants/{project_id}/{fid}/{token}

Check if user has access to feedback center for project

Response body

true

URI Parameters

PATCH /mysight/groups/{instanceId}

Updates additional data of configured panel groups for given mySight instance

Response body

true

URI Parameters

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

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

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

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

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

POST /panel/groups/categoryByName

returns group category data

Request body

{
  "categoryName": "Example"
}

Response body

{
  "categoryId": 2,
  "categoryName": "Example",
  "categoryDescription": "Example description"
}

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

PATCH /panel/groups/{id}

add panelists to an existing panel group

Request body

{
  "identifierType": "uid",
  "identifierValues": [
    123, 124, 125
  ]
}

Response body

true

URI Parameters

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

PUT /panel/groups/{id}

empty a panel group by deleting all members from it

Response body

true

URI Parameters

POST /panel/lotteries/{gid}

Create prize draw, returns id

Request body

{ "title": "Example", "description": "Description" }

Response body

1234

URI Parameters

DELETE /panel/lotteries/{id}

Delete prize draw. Includes deletion of prizes and winners.

Response body

true

URI Parameters

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

PATCH /panel/lotteries/{id}

Update status of prize draw with given prize draw ID.

Request body

{ "status": "ARCHIVED" }

Response body

true

URI Parameters

DELETE /panel/lotteries/{id}/winners

Delete winner

Response body

true

URI Parameters

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

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

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

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

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

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

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

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

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

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

GET /portal/portal/export/{portalId}

Get portal export by portalId

Response body

"{\"isPortalCopy\":true,\"metaData\":{\"name\":\"[...]"

URI Parameters

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

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

GET /survey/languages/{surveyId}/{languageId}

get a language

Response body

{
  "label": "German",
  "localestring": "de_DE",
  "languageId": 1,
  "isStandard": true
}

URI Parameters

POST /survey/languages/{surveyId}

adds a new language

Request body

{
  "language": {
    "label": "English",
    "localestring": "en_GB",
    "adoptTranslationFromId": 1
  }
}

Response body

1

URI Parameters

PATCH /survey/languages/{surveyId}

change language data

Request body

{
  "language": {
    "label": "Deutsch",
    "localestring": "de_DE",
    "languageId": 1
  }
}

Response body

true

URI Parameters

DELETE /survey/languages/{surveyId}

deletes a language

Request body

{ "languageId": 1 }

Response body

true

URI Parameters

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

GET /survey/lists/{surveyId}

Returns the list of available static lists for a survey

Response body

[ { "listId": 1234, "label": "Example" } ]

URI Parameters

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

DELETE /survey/lists/{surveyId}/{listId}

Deletes a list

URI Parameters

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

PUT /survey/lists/{surveyId}/{listId}

Adds a static list element

Request body

{
  "label": "Pears",
  "number": 3
}

Response body

1

URI Parameters

DELETE /survey/lists/{surveyId}/{listId}/elements

Clears a list

URI Parameters

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

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

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

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

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

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

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

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

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

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

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

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

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

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

POST /survey/samples/{pid}

Add a sample to a survey

Request body

{ "title": "Example", "description": "Example sample" }

Response body

1234

URI Parameters

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

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

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

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

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

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

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

DELETE /survey/questionnaire/{surveyId}

delete a questionnaire page

Request body

{ "pageId": 1, "force": true }

Response body

true

URI Parameters

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

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

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

POST /survey/reports/{surveyId}

Create a standard Reporting+ report for a survey

Request body

{ "title": "Example", "description": "Example" }

Response body

1

URI Parameters

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

DELETE /survey/reports/{reportId}

Delete a Reporting+ export

Response body

true

URI Parameters

GET /survey/reports/{reportId}/publication/{reportPublicationId}

return the data for a publication

Response body

Base64 encoded binary data

URI Parameters

GET /survey/reports/{reportId}/published/{reportPublicationId}

Check if report is available

Response body

true

URI Parameters

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

Base64 encoded binary data

URI Parameters

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

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

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

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

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

Base64 encoded binary data

URI Parameters

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

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

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

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

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

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

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

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

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

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

DELETE /survey/surveys/{surveyId}

Deletes a survey

Response body

true

URI Parameters

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

POST /survey/surveys/{surveyId}/copy

Copies a survey

Request body

{ "title": "Copy of Example" }

Response body

1234

URI Parameters

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

GET /survey/surveys/{surveyId}/previewlink

Uses the admin session in the url

Response body

"Example"

URI Parameters

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

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.

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

Base64 encoded binary data

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

PUT /survey/timelog/{surveyId}

Resets all performance data used when accessing the OSPE time log.

Response body

true

URI Parameters

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

PATCH /survey/translations/{surveyId}/{languageId}

Changes a translation

Request body

{
  "textType": "q_instruct",
  "typeId": 1234,
  "text": "New Example"
}

Response body

true

URI Parameters