his article provides comprehensive information about the EFS Service-Layer (API) services. It covers various aspects of the API, including authentication, REST status codes, and detailed descriptions of different service endpoints.

Information

The EFS Service-Layer offers a wide range of API services for managing surveys, participants, and other related functionalities. This guide will help you understand and utilize these services effectively.

As mentioned in the EFS Service-Layer overview, all requests should use the token URL parameter to authenticate the service user, for example GET https://your-efs.com/service/survey/surveys/?token=1234567890. An alternative to using the provided token, is to create a basic authentication request as specified in the HTTP protocol.

REST status codes

When using REST to access the Service Layer, the service will use the following HTTP status codes, 500 being the most common error status code and 200 being used for all successful requests.

Status	Description
200	The request has been processed, see end point description for expected response body
400	The validation of the entity given in the body of the request failed. Can also be caused by a malformed JSON request.
401	Can be caused by missing, invalid or expired token or username/password combination.
403	The user does not have the permission to execute this service or service is unknown or not enabled/available.
500	All regular errors and exceptions will use this status code, please see the message for additional information. In some rare exceptions, the returned value may not be json encoded.

Example for response body of a error status code:

{
  "error": {
    "message": "REST route [efs/test] not found, not activated or no access",
    "code": 403
  }
}

The title of the expandable area uses the following format:
Description | {REST method} | {SOAP method}

The examples provided are REST requests, our recommended method for accessing the Service-Layer. The list of services omits the mandatory /service/ base path. All service layer requests need to use this base path, e.g. GET /survey/surveys/ should be GET https://efs-installation.com/service/survey/surveys/ in your application.

When requesting services to be activated through the support, it is best to provide the SOAP method names, as these are unique and avoid confusion.

EFS

Email blocklist, global and survey based

DELETE /efs/mailblacklist/

Deletes a list of email addresses from blocklist

Request body

{
  "emailList": [
    {
      "email": "example@domain.tld",
      "surveyId": 1234
    }
  ]
}

Response body

[
    {
        "email": "example@domain.tld",
        "surveyId": 1234,
        "result": 1
    }
]

GET /efs/mailblacklist/

Get a list of all blocklisted email addresses (both global and survey). Global entries have surveyId 0.

Response body

[
  {
    "email": "example@domain.tld",
    "surveyId": 0,
    "createdAt": "2020-07-02T12:53:50+00:00",
    "createdBy": "SERVICE"
  }
]

POST /efs/mailblacklist/

Add a list of email addresses to blocklist. If surveyId is specified the email will be blocked for given survey, otherwise if omitted or if surveyId is 0, the email will be added to global blocklist.

Request body

{
  "emailList": [
    {
      "email": "example@domain.tld",
      "surveyId": 1234
    }
  ]
}

Response body

[
    {
        "email": "example@domain.tld",
        "surveyId": 1234,
        "result": 1
    }
]

POST /efs/mailblacklist/check

If surveyId is not specified, or the id is 0, only the global blocklist will be checked. By providing a surveyId, the system will check if the email is blocked in the given survey only. The return value is a boolean.

Request body

{
  "emailAddress": "example@domain.tld",
  "surveyId": 1234
}

Response body

true

POST /efs/mailblacklist/getListByDateRange

Get a list of blocklisted email addresses (both global and survey related) restricted by date range.

Request body

{
  "dateRange": {
    "from": "2020-07-01T12:53:50+00:00",
    "to": "2020-07-03T12:53:50+00:00"
  }
}

Response body

[
    {
        "email": "example@domain.tld",
        "surveyId": 1234,
        "result": 1
    }
]

POST /efs/mailblacklist/getListByEmailAddress

Returns a list of all surveys where given email is blacklisted. In case of global blacklist the surveyId is 0.

Request body

{
  "emailAddress": "example@domain.tld"
}

Response body

[
    {
        "email": "example@domain.tld",
        "surveyId": 0,
        "createdAt": "2020-08-26T11:01:22+00:00",
        "createdBy": "SERVICE"
    }
]

Mail templates

POST /efs/mailtemplates/

Add mail template. Please see the mail template form in EFS for required and optional information. Returns the id of the newly created mail template. Use GET /efs/mailtemplates/{id} on an existing template, if unsure about the correct parameters and also have a look at the mail template editor in EFS for optional and required parameters and supported wildcards, specific to your mail template type.

Option	Valid values
`type`	default_mail, invitation_mail, reminder_mail, survey_ends_mailtype, welcome_mail, pwrecovery_mail, doub_check_mail, register_check_mail, md_invitation_mail, md_reminder_mail, winner_mail, promotion_mail, bonus_mail, exchange_mail, orgprocessor_mail, website_notifications, system_mail, eat_your_own_dogfood, result_mail, reportnotification_mail
`site_id`	ID of Panel Website language version, on installations without Panel Website, please use 0.
`format`	TEXT, HTML, TEXT_AND_HTML
`charset`	UTF-8, UTF-16, ISO-8859-1, ISO-8859-2, ISO-8859-3, ISO-8859-4, ISO-8859-5, ISO-8859-6, ISO-8859-7, ISO-8859-8, ISO-8859-9, ISO-8859-13, ISO-8859-15, US-ASCII, KOI8-R, GB18030, x-EUC-CN, GBK, x-EUC-TW, Big5, Big5-HKSCS, EUC-JP, Shift_JIS, ISO-2022-JP, EUC-KR, ISO-2022-KR, TIS-620
`priority`	NO_PRIORITY, HIGHEST, HIGH, NORMAL, LOW, LOWEST
`sensitivity`	NORMAL, PRIVATE, PERSONAL, COMPANY
`notify`	NO_NOTIFICATION, WITH_RETURN_PATH, WITH_FROM_PATH
`localeString`	See EFS mail template interface for a current list of locales.
`from`	`from` needs to be one of registered sender email addresses in EFS. See: Libraries > Mail templates > Mail senders.

Request body

{
  "mailtemplate": {
    "meta": {
      "description": "Example description",
      "type": "default_mail",
      "site_id": "123",
      "active": true
    },
    "content": {
      "from": "example@domain.tld",
      "subject": "Example",
      "format": "TEXT_AND_HTML",
      "text_content": "Example",
      "html_content": "<h1>Example</h1>"
    },
    "options": {
      "charset": "UTF-8",
      "reply_to": "example@domain.tld",
      "return_path": "example@domain.tld",
      "to_realname": true,
      "send_copy": true,
      "cc": "example@domain.tld",
      "bcc": "example@domain.tld",
      "priority": "NO_PRIORITY",
      "sensitivity": "NORMAL",
      "notify": "NO_NOTIFICATION",
      "sms_from": "+491234567890",
      "sms_content": "Example"
    },
    "translations": [
      {
        "localeString": "de_DE",
        "subject": "Beispiel",
        "text_content": "Beispiel",
        "html_content": "<h1>Beispiel</h1>",
        "sms_content": "Beispiel"
      }
    ]
  }
}

Response body

DELETE /efs/mailtemplates/{id}

Delete mail template by id. Successful requests have no response body.

URI Parameters

Name	Type	Required	Description
id	integer	true	The mail-template id Examples: `2`.

GET /efs/mailtemplates/{id}

Get mail template by id

Response body

{
  "meta": {
    "description": "Example message",
    "type": "default_mail",
    "site_id": "7",
    "active": true
  },
  "content": {
    "from": "example@domain.tld",
    "subject": "Example message",
    "format": "TEXT",
    "text_content": "Dear #u_firstname#, \r\n\r\nyou have a new message.",
    "attachments": false
  },
  "options": {
    "charset": "ISO-8859-1",
    "reply_to": "example@domain.tld",
    "return_path": "example@domain.tld",
    "to_realname": false,
    "send_copy": false,
    "priority": "NO_PRIORITY",
    "sensitivity": "NORMAL",
    "notify": "NO_NOTIFICATION"
  },
  "id": 1234
}

URI Parameters

Name	Type	Required	Description
id	integer	true	The mail-template id Examples: `2`.

GET /efs/mailtemplates/withAttachments/{id}

Get mail template by id with attachments. The content of attachment is gzip and base64 encoded.

Response body

{
  "meta": {
    "description": "Example message",
    "type": "default_mail",
    "site_id": "7",
    "active": true
  },
  "content": {
    "from": "example@domain.tld",
    "subject": "Example message",
    "format": "TEXT",
    "text_content": "Dear #u_firstname#, \r\n\r\nyou have a new message.",
    "attachments": false
  },
  "options": {
    "charset": "ISO-8859-1",
    "reply_to": "example@domain.tld",
    "return_path": "example@domain.tld",
    "to_realname": false,
    "send_copy": false,
    "priority": "NO_PRIORITY",
    "sensitivity": "NORMAL",
    "notify": "NO_NOTIFICATION"
  },
  "attachments": [
   {"name":"example.jpg", "content":"skkfdsjksdjkfsd..."}
  ]
  "id": 1234
}

URI Parameters

Name	Type	Required	Description
id	integer	true	The mail-template id Examples: `2`.

PUT /efs/mailtemplates/{id}

Change mail template data, returns the mail id

Request body

{
  "mailtemplate": {
    "meta": {
      "description": "Example message",
      "type": "default_mail",
      "site_id": "7",
      "active": true
    },
    "content": {
      "from": "example@domain.tld",
      "subject": "Example message",
      "format": "TEXT",
      "text_content": "Dear #u_firstname#, \r\n\r\nyou have a new message.",
      "attachments": false
    },
    "options": {
      "charset": "ISO-8859-1",
      "reply_to": "example@domain.tld",
      "return_path": "example@domain.tld",
      "to_realname": false,
      "send_copy": false,
      "priority": "NO_PRIORITY",
      "sensitivity": "NORMAL",
      "notify": "NO_NOTIFICATION"
    }
  }
}

Response body

URI Parameters

Name	Type	Required	Description
id	integer	true	The mail-template id Examples: `2`.

POST /efs/mailtemplates/list

Get a list of mailtemplates. You can restrict the list of templates, by providing a POST body with the list of types.

Request body

{
  "mailTemplateTypes": [
    "default_mail"
  ]
}

Response body

[
  {
    "meta": {
      "description": "Example message",
      "type": "default_mail",
      "site_id": "7",
      "active": true
    },
    "content": {
      "from": "example@domain.tld",
      "subject": "Example message",
      "format": "TEXT",
      "text_content": "Dear #u_firstname#, \r\n\r\nyou have a new message.",
      "attachments": false
    },
    "options": {
      "charset": "ISO-8859-1",
      "reply_to": "example@domain.tld",
      "return_path": "example@domain.tld",
      "to_realname": false,
      "send_copy": false,
      "priority": "NO_PRIORITY",
      "sensitivity": "NORMAL",
      "notify": "NO_NOTIFICATION"
    },
    "id": 1234
  }
]

POST /efs/mailtemplates/listWithAttachments

Get a list of mailtemplates. You can restrict the list of templates, by providing a POST body with the list of types.

Request body

{
  "mailTemplateTypes": [
    "default_mail"
  ]
}

Response body

[
  {
    "meta": {
      "description": "Example message",
      "type": "default_mail",
      "site_id": "7",
      "active": true
    },
    "content": {
      "from": "example@domain.tld",
      "subject": "Example message",
      "format": "TEXT",
      "text_content": "Dear #u_firstname#, \r\n\r\nyou have a new message.",
      "attachments": false
    },
    "attachments": [
    ]
    "options": {
      "charset": "ISO-8859-1",
      "reply_to": "example@domain.tld",
      "return_path": "example@domain.tld",
      "to_realname": false,
      "send_copy": false,
      "priority": "NO_PRIORITY",
      "sensitivity": "NORMAL",
      "notify": "NO_NOTIFICATION"
    },
    "id": 1234
  }
]

POST /efs/mailtemplates/send

Send a preview email. Similar to the mail template preview send functionality in the EFS UI.

Request body

{
    "id": 353,
    "recieverMails":"example@example.tld",
    "localeString":"de_DE",
    "placeholders": [
        {"placeholderName":"#test#", "placeholderValue":"Test"}
    ]
}

Response body

{
    "success": true
}

Management of EFS organisations

DELETE /efs/organizations/

Deletes an EFS admin organisation.

Request body

{
  "adminOrgIdentifierType": "id",
  "adminOrgIdentifierValue": "1234"
}

Response body

true

PATCH /efs/organizations/

Sets an organization’s value. See POST /efs/organizations/ for possible adminOrgField names.

Request body

{
  "adminOrgIdentifierType": "id",
  "adminOrgIdentifierValue": "1234",
  "adminOrgField": "customer_no_common",
  "adminOrgValue": "KD1234"
}

Response body

true

POST /efs/organizations/

Adds an EFS admin organization.

Request body

{
  "adminOrgRecord": {
    "name": "Example",
    "description": "Example org",
    "contract_start": "2020-07-02T12:53:50+00:00",
    "contract_end": "2022-07-02T12:53:50+00:00",
    "customer_no_common": "Example",
    "max_active_projects_allowed": "Example",
    "max_archived_projects_allowed": "Example",
  },
  "adminOrgIdentifierReturnType": "id"
}

Response body

PUT /efs/organizations/

Add an existing staff member to an organization.

Request body

{
  "adminUserIdentifierType": "u_email",
  "adminUserIdentifierValue": "example@domain.tld",
  "adminOrgIdentifierType": "id",
  "adminOrgIdentifierValue": "1234"
}

Response body

true

POST /efs/organizations/details

Returns an organization.

Request body

{
  "adminOrgIdentifierType": "id",
  "adminOrgIdentifierValue": "1234"
}

Response body

{
  "name": "Example",
  "description": "Example org",
  "contract_start": "2019-07-01T00:00:00+00:00",
  "contract_end": "2023-12-30T00:00:00+00:00",
  "customer_no_common": "KD1234"
}

POST /efs/organizations/list

Returns a list of organizations specified by a search value.

Request body

{
  "adminOrgField": "name",
  "adminOrgValue": "Example",
  "pageFrom": 0,
  "pageLimit": 100
}

Response body

[
  {
    "name": "Example",
    "description": "Example org",
    "contract_start": "2019-07-01T00:00:00+00:00",
    "contract_end": "2023-12-30T00:00:00+00:00",
    "customer_no_common": "KD1234"
  }
]

PATCH /efs/organizations/templates

Changes an admin organization’s Reporting+ export templates configuration for one file type format. Possible values for reportingExportFormat are: html, ppt, pdf, pptx and pptxpdf. To disable an export, send "reportingExportTemplates": [], otherwise provide a list of export template ids to be enabled.

Request body

{
  "adminOrgIdentifierType": "id",
  "adminOrgIdentifierValue": "1234",
  "reportingExportFormat": "pptxpdf",
  "reportingExportTemplates": [
    123,
    124
  ]
}

Response body

true

Management of EFS teams

POST /efs/teams/

Adds a new EFS team, returns the id of the team.

Request body

{
  "team": {
    "teamName": "Example",
    "teamTitle": "Example",
    "teamDesription": "Example description",
    "teamAccessability": [
      1
    ],
    "areasAccessable": [
      "www"
    ],
    "rightTemplateId": 1
  }
}

Response body

POST /efs/teams/list

Retrieves a list of teams matching given search criteria

Request body

{
  "identifierType": "teamName",
  "identifierValue": "Example",
  "page": 0,
  "limit": 100
}

Response body

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

DELETE /efs/teams/{teamId}

Deletes an EFS team

Response body

true

URI Parameters

Name	Type	Required	Description
teamId	integer	true	team id Examples: `2`.

GET /efs/teams/{teamId}

Retrieves the data of an EFS team

Response body

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

URI Parameters

Name	Type	Required	Description
teamId	integer	true	team id Examples: `2`.

PATCH /efs/teams/{teamId}

Changes the EFS team details

Request body

{
  "team": {
    "teamName": "Example",
    "teamTitle": "Example",
    "teamDescription": "Example",
    "teamAccessability": [
      1
    ],
    "areasAccessable": [
      "www"
    ],
    "rightTemplateId": 1
  }
}

Response body

true

URI Parameters

Name	Type	Required	Description
teamId	integer	true	team id Examples: `2`.

Object rights

DELETE /efs/privileges/

Removes the right from the object for the given team.

Request body

{
  "objectId": 1,
  "groupId": 1,
  "right": "read"
}

Response body

true

PATCH /efs/privileges/

Sets a right on an object for given team, replaces any existing condition

Request body

{
  "objectId": 1,
  "groupId": 1,
  "right": "read"
}

Response body

true

POST /efs/privileges/addright

Adds the right to the object for the given team.

Request body

{
  "objectId": 1,
  "groupId": 1,
  "right": "read"
}

Response body

true

POST /efs/privileges/features

Tells if current user has access to a specific access right (team rights). Valid parameters for right: read, write. The parameter feature accepts a string containing the name of an act right, please see team rights management in System > Users > Teams in EFS or the online manual.

Request body

{
  "feature": "ct42partadm",
  "right": "read"
}

Response body

true

POST /efs/privileges/object

Tells if current user has access to an object. See Options > ACL Rights > Object instances

Request body

{
  "objectId": 1,
  "right": "read"
}

Response body

true

EFS admin user management

DELETE /efs/staff/

Deletes a staff member. A successful request has no response body.

Request body

{
  "identifierType": "email",
  "identifier": "example@domain.tld"
}

GET /efs/staff/

Return information about the current admin user thats using the service. This method also keeps admin-session alive.

Response body

{
  "adminUserId": 1234,
  "accountName": "Example",
  "firstName": "First",
  "lastName": "Last",
  "email": "example@domain.tld",
  "language": "EN",
  "expireDate": "2020-07-02T12:53:50+00:00",
  "organisation": 1,
  "primaryGroup": 1,
  "groups": [
    1
  ]
}

PATCH /efs/staff/

Changes a staff members data. You only need to provide the fields you want to change.

Request body

{
  "identifierType": "email",
  "identifier": "example@domain.tld",
  "changes": {
    "firstName": "First",
    "lastName": "Last",
    "email": "example@domain.tld",
    "password": "New Password",
    "gender": "NOT_SPECIFIED",
    "street": "None",
    "zip": "12345",
    "city": "Example",
    "phone": "+491234567890",
    "country": "Germany",
    "mobile": "+491234567890",
    "language": "EN",
    "expireDate": "2024-07-02T12:53:50+00:00",
    "organisation": 1,
    "primaryTeam": 1,
    "teams": [
      1
    ],
    "enabled": true,
    "mobile2": "+491234567891",
    "www": "Some URL",
    "comment": "Additional Comment",
    "department": "Department info"
  }
}

POST /efs/staff/

Create a new staff member for the EFS admin interface. To set the staff members organization you need to have the appropriate right. If no organization is set the staff member will inherit the creating staff members organization. Returns the user id.

Request body

{
  "staffMember": {
    "identifierType": "email",
    "identifier": "example@domain.tld",
    "changes": {
      "account": "Example",
      "firstName": "First",
      "lastName": "Last",
      "email": "example@domain.tld",
      "password": "New Password",
      "gender": "NOT_SPECIFIED",
      "street": "None",
      "zip": "12345",
      "city": "Example",
      "phone": "+491234567890",
      "country": "Germany",
      "mobile": "+491234567890",
      "language": "EN",
      "expireDate": "2024-07-02T12:53:50+00:00",
      "organisation": 1,
      "primaryTeam": 1,
      "teams": [
        1
      ],
      "enabled": true,
      "mobile2": "+491234567891",
      "www": "Some URL",
      "comment": "Additional Comment",
      "department": "Department info"
    }
  }
}

Response body

POST /efs/staff/details

Return information about a staff member

Request body

{
  "identifierType": "email",
  "identifier": "example@domain.tld"
}

Response body

{
  "userId": 1234,
  "account": "Example",  
  "firstName": "First",
  "lastName": "Last",
  "email": "example@domain.tld",
  "password": "New Password",
  "gender": "NOT_SPECIFIED",
  "street": "None",
  "zip": "12345",
  "city": "Example",
  "phone": "+491234567890",
  "country": "Germany",
  "mobile": "+491234567890",
  "language": "EN",
  "expireDate": "2020-07-02T12:53:50+00:00",
  "organisation": 1,
  "primaryTeam": 1,
  "teams": [
    1
  ],
  "enabled": true,
  "mobile2": "Example",
  "www": "Example",
  "comment": "Example",
  "department": "Example"
}

GET /efs/staff/list

Returns a list of all EFS staff members

Response body

[
  {
    "adminUserId": 1234,
    "accountName": "Example",
    "firstName": "First",
    "lastName": "Last",
    "email": "example@domain.tld",
    "language": "EN",
    "expireDate": "2020-07-02T12:53:50+00:00",
    "organisation": 1,
    "primaryGroup": 1,
    "groups": [
      1
    ]
  }
]

POST /efs/staff/mail

Sends email to the specified EFS admin user

Request body

{
  "identifierType": "email",
  "identifierValue": "example@domain.tld",
  "mailTemplateData": {
    "meta": {
      "description": "Example message",
      "type": "default_mail",
      "site_id": "7",
      "active": true
    },
    "content": {
      "from": "example@domain.tld",
      "subject": "Example message",
      "format": "TEXT",
      "text_content": "Dear user, \r\n\r\nyou have a new message.",
      "attachments": false
    },
    "options": {
      "charset": "ISO-8859-1",
      "reply_to": "example@domain.tld",
      "return_path": "example@domain.tld",
      "to_realname": false,
      "send_copy": false,
      "priority": "NO_PRIORITY",
      "sensitivity": "NORMAL",
      "notify": "NO_NOTIFICATION"
    }
  }
}

Response body

true

PATCH /efs/staff/role

Alters a staff members role within a given team

Request body

{
  "userId": 1,
  "teamId": 1,
  "newRole": "MEMBER",
  "newOwnerUserId": 1
}

Response body

true

System information

GET /efs/system/

determine the version number of the EFS installation

Response body

"20.1"

POST /efs/system/

Returns the current server time, use format to provide a formatting string (see PHP date() formatting options), otherwise the current unix timestamp will be returned.

Request body

{ "format": "Y-m-d H:i:s" }

Response body

"2020-08-26 13:35:26"

GET /efs/system/load

query the current system’s 1-minute load average

Response body

1.345

Other

GET /efs/session/{sessionId}

Get the admin user id for an admin session id Will throw an exception if the session id is invalid or the session is expired

Response body

URI Parameters

Name	Type	Required	Description
sessionId	string	true	id of admin session.

GET /efs/taskqueue/{taskId}

Returns json encoded array with either execution-status or (if available) result of asynchronous service-calls for given taskId. Possible values for status: 1 – Task is pending for execution, 2 – Task is currently running, 3 – Task execution failed;

Response body

"2"

URI Parameters

Name	Type	Required	Description
taskId	integer	true	id of taskqueue task Examples: `2`.

GET /efs/jobs/{jobId}

Query the status of a single EFS job maker job. This service is only enabled in certain use cases for customers.

Response body

"2"

URI Parameters

Name	Type	Required	Description
jobId	string	true	job id, Example: `10898768285f48e49c0d49f`.

Employee

POST /employee/reports/

Adds a report

Request body

{
  "report": {
    "report_definition_id": 1234,
    "pid": 1234,
    "lang_id": 1234,
    "report_type": "pdf",
    "unit_metaname": "Example",
    "file_content": "QmFzZTY0IGVuY29kZWQgYmluYXJ5IGRhdGE=",
    "report_label": "Example",
    "replace": true,
    "report_filename": "Example.pdf"
  }
}

Response body

{
  "report_definition_id": 1234,
  "pid": 1234,
  "lang_id": 1234,
  "report_type": "pdf",
  "unit_metaname": "Example",
  "file_content": "QmFzZTY0IGVuY29kZWQgYmluYXJ5IGRhdGE=",
  "report_label": "Example",
  "replace": true,
  "report_filename": "Example.pdf",
  "rid": "1234"
}

GET /employee/reports/{surveyId}

Returns the List of Report definitions including report versions for surveyId

Response body

[
  {
    "report_id": 1234,
    "pid": 1234,
    "name": "Example",
    "title_pattern": "Example",
    "template": "Example",
    "cat": "Example",
    "download_status": "Example",
    "file_download_pattern": "Example",
    "report_type": 1234,
    "number_of_reports": 1234,
    "min_participants": 1234,
    "min_item": 1234
  }
]

URI Parameters

Name	Type	Required	Description
surveyId	integer	true	id of the panel or masterdata survey Examples: `2`.

GDPR

GET /gdpr/panel/getConsentForm/{localeString}

Returns GDPR consent for given locale string

Response body

{
  "content_value": "Example",
  "welcome_text_value": "Example",
  "title_headline": "Example",
  "contact_us_headline_headline": "Example",
  "company_name_value": "Example",
  "contact_detail_value": "Example",
  "representative_headline": "Example",
  "representative_value": "Example",
  "data_scope_headline": "Example",
  "data_scope_value": "Example",
  "data_category_headline": "Example",
  "data_category_value": "Example",
  "legal_basis_headline": "Example",
  "legal_basis_value": "Example",
  "recipient_headline": "Example",
  "recipient_value": "Example",
  "transfer_data_headline": "Example",
  "transfer_data_value": "Example",
  "contractual_requirement_headline": "Example",
  "contractual_requirement_value": "Example",
  "auto_decision_headline": "Example",
  "auto_decision_value": "Example",
  "info_subject_headline": "Example",
  "info_subject_value": "Example",
  "info_withdrawal_headline": "Example",
  "info_withdrawal_value": "Example",
  "info_supervisor_headline": "Example",
  "info_supervisor_value": "Example",
  "contact_officer_headline": "Example",
  "contact_officer_value": "Example",
  "data_retention_headline": "Example",
  "data_retention_value": "Example"
}

URI Parameters

Name	Type	Required	Description
localeString	string	true	Language string, Examples: `de_DE`, `en_GB`.

POST /gdpr/panel/setConsentForm

Set content of GDPR consent for given locale string

Request body

{
  "localeString": "de_DE",
  "consentData": {
    "content_value": "Example",
    "welcome_text_value": "Example",
    "title_headline": "Example",
    "contact_us_headline_headline": "Example",
    "company_name_value": "Example",
    "contact_detail_value": "Example",
    "representative_headline": "Example",
    "representative_value": "Example",
    "data_scope_headline": "Example",
    "data_scope_value": "Example",
    "data_category_headline": "Example",
    "data_category_value": "Example",
    "legal_basis_headline": "Example",
    "legal_basis_value": "Example",
    "recipient_headline": "Example",
    "recipient_value": "Example",
    "transfer_data_headline": "Example",
    "transfer_data_value": "Example",
    "contractual_requirement_headline": "Example",
    "contractual_requirement_value": "Example",
    "auto_decision_headline": "Example",
    "auto_decision_value": "Example",
    "info_subject_headline": "Example",
    "info_subject_value": "Example",
    "info_withdrawal_headline": "Example",
    "info_withdrawal_value": "Example",
    "info_supervisor_headline": "Example",
    "info_supervisor_value": "Example",
    "contact_officer_headline": "Example",
    "contact_officer_value": "Example",
    "data_retention_headline": "Example",
    "data_retention_value": "Example"
  }
}

Response body

true

GET /gdpr/survey/{surveyId}/{languageId}

Returns GDPR consent for given surveyId and languageId

Response body

{
  "content_value": "Example",
  "welcome_text_value": "Example",
  "title_headline": "Example",
  "contact_us_headline_headline": "Example",
  "company_name_value": "Example",
  "contact_detail_value": "Example",
  "representative_headline": "Example",
  "representative_value": "Example",
  "data_scope_headline": "Example",
  "data_scope_value": "Example",
  "data_category_headline": "Example",
  "data_category_value": "Example",
  "legal_basis_headline": "Example",
  "legal_basis_value": "Example",
  "recipient_headline": "Example",
  "recipient_value": "Example",
  "transfer_data_headline": "Example",
  "transfer_data_value": "Example",
  "contractual_requirement_headline": "Example",
  "contractual_requirement_value": "Example",
  "auto_decision_headline": "Example",
  "auto_decision_value": "Example",
  "info_subject_headline": "Example",
  "info_subject_value": "Example",
  "info_withdrawal_headline": "Example",
  "info_withdrawal_value": "Example",
  "info_supervisor_headline": "Example",
  "info_supervisor_value": "Example",
  "contact_officer_headline": "Example",
  "contact_officer_value": "Example",
  "data_retention_headline": "Example",
  "data_retention_value": "Example",
  "data_retention_type": "YEAR",
  "data_retention_amount": 1
}

URI Parameters

Name	Type	Required	Description
surveyId	integer	true	Survey Id Examples: `2`.
languageId	integer	true	Language Id Examples: `2`.

POST /gdpr/survey/{surveyId}/{languageId}

Set content of GDPR consent for given surveyId and languageId

Request body

{
  "consentData": {
    "content_value": "Example",
    "welcome_text_value": "Example",
    "title_headline": "Example",
    "contact_us_headline_headline": "Example",
    "company_name_value": "Example",
    "contact_detail_value": "Example",
    "representative_headline": "Example",
    "representative_value": "Example",
    "data_scope_headline": "Example",
    "data_scope_value": "Example",
    "data_category_headline": "Example",
    "data_category_value": "Example",
    "legal_basis_headline": "Example",
    "legal_basis_value": "Example",
    "recipient_headline": "Example",
    "recipient_value": "Example",
    "transfer_data_headline": "Example",
    "transfer_data_value": "Example",
    "contractual_requirement_headline": "Example",
    "contractual_requirement_value": "Example",
    "auto_decision_headline": "Example",
    "auto_decision_value": "Example",
    "info_subject_headline": "Example",
    "info_subject_value": "Example",
    "info_withdrawal_headline": "Example",
    "info_withdrawal_value": "Example",
    "info_supervisor_headline": "Example",
    "info_supervisor_value": "Example",
    "contact_officer_headline": "Example",
    "contact_officer_value": "Example",
    "data_retention_headline": "Example",
    "data_retention_value": "Example",
    "data_retention_type": "YEAR",
    "data_retention_amount": 1
  }
}

Response body

true

URI Parameters

Name	Type	Required	Description
surveyId	integer	true	Survey Id Examples: `2`.
languageId	integer	true	Language Id Examples: `2`.

DELETE /gdpr/survey/{surveyId}

Deletes personal data of all participants for given surveyId

Response body

true

URI Parameters

Name	Type	Required	Description
surveyId	integer	true	Survey Id Examples: `2`.

Leadership

POST /loft/participants/pool/{sampleId}

add multiple feedback-participants from a CSV file to the participants pool using data from a CSV file. note this operation works on surveys of type “leadership” only

Request body

{
  "csvData": "CSV content",
  "returnIdentifierType": "u_email",
  "mappingColumn": "u_email"
}

Response body

{
  "successful": 1,
  "failed": 1,
  "failedRows": [
    {
      "line": 1234,
      "value": "Example",
      "errors": [
        {
          "column": "Example",
          "value": "Example",
          "details": [
            {
              "code": "Example",
              "translated": "Example",
              "type": 1234
            }
          ]
        }
      ]
    }
  ],
  "returnIdentifiers": [
    {
      "internalReturnValue": "u_email",
      "externalReturnValue": "u_email"
    }
  ]
}

URI Parameters

Name	Type	Required	Description
sampleId	integer	true	id of sample to add the participants to Examples: `2`.

POST /loft/participants/{sampleId}

add multiple feedback-provider and -receiver from a CSV file to a feedback-wave using data from a CSV file. note this operation works on surveys of type “leadership” only

Request body

{
  "waveId": 1,
  "csvData": "CSV Import data",
  "returnIdentifierType": "u_email",
  "mappingColumn": "Mail"
}

Response body

{
  "successful": 1,
  "failed": 1,
  "failedRows": [
    {
      "line": 1,
      "value": "Example",
      "errors": [
        {
          "column": "Example",
          "value": "Example",
          "details": [
            {
              "code": "Example",
              "translated": "Example",
              "type": 1234
            }
          ]
        }
      ]
    }
  ],
  "returnIdentifiers": [
    {
      "internalReturnValue": "u_email",
      "externalReturnValue": "Mail"
    }
  ]
}

URI Parameters

Name	Type	Required	Description
sampleId	integer	true	id of sample to add the participants to Examples: `2`.

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

Get feedback center user data

Response body

"Encoded Feedback Center data"

URI Parameters

Name	Type	Required	Description
project_id	integer	true	Efs project id Examples: `2`.
fid	integer	true	Feedback center user id Examples: `2`.

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

Check if user has access to feedback center for project

Response body

true

URI Parameters

Name	Type	Required	Description
project_id	integer	true	Efs project id Examples: `2`.
fid	integer	true	Feedback center user id Examples: `2`.
token	string	true	token to validate request at data voyager Examples: `Example`.

MySight

PATCH /mysight/groups/{instanceId}

Updates additional data of configured panel groups for given mySight instance

Response body

true

URI Parameters

Name	Type	Required	Description
instanceId	integer	true	mySight instanceId Examples: `2`.

People Module / Panel

Panel circles

POST /panel/circles/

Adds a new panel circle (portals group), used in Portals

Request body

{
  "circleInitData": {
    "title": "People in my organization",
    "circleAccessType": "PRIVATE",
    "matchVar": "m_gcid_recode",
    "matchAgainstVar": "m_gcid_recode",
    "panelGroupId": 1,
    "startDateTime": "2021-01-09 09:00:00",
    "intervalType": "DAY",
    "intervalValue": 1
  }
}

Response body

{
  "circleId": 123,
  "title": "People in my organization",
  "circleType": "COMPANY_MANAGED",
  "circleAccessType": "PRIVATE",
  "circleProcessStatus": "IDLE"
}

POST /panel/circles/generate/{id}

Generates a company managed panel circle (portals group)

Response body

true

URI Parameters

Name	Type	Required	Description
id	integer	true	id of panel circle Examples: `2`.

POST /panel/circles/listByCondition

Returns a list of panel circle objects to given logical condition. See filtering results with conditions for help on building conditions.

Request body

{
  "condition": {
    "join": {
      "operator": "AND",
      "condition1": {
        "comparison": {
                    "variable" : "circleType",
                    "operator" : "EQUAL",
                    "value" : "USER_MANAGED"
        }
      },
      "condition2": {
        "inComparison": {
            "variable": "circleAccessType",
            "operator": "IN",
            "value": ["PUBLIC", "PRIVATE"]
        }
      }
    }
  },
  "offset": 0,
  "limit": 10
}

Response body

[
  {
    "circleId": 1,
    "title": "Example",
    "circleType": "USER_MANAGED",
    "circleAccessType": "PRIVATE",
    "circleProcessStatus": "IDLE"
  }
]

DELETE /panel/circles/{id}

Deletes a panel circle

Response body

true

URI Parameters

Name	Type	Required	Description
id	integer	true	id of panel circle Examples: `2`.

GET /panel/circles/{id}

Returns panel circle object to given circle ID

Response body

{
  "circleId": 1,
  "title": "Example",
  "circleType": "USER_MANAGED",
  "circleAccessType": "PRIVATE",
  "circleProcessStatus": "IDLE"
}

URI Parameters

Name	Type	Required	Description
id	integer	true	id of panel circle Examples: `2`.

External surveys management

DELETE /panel/externalsurveys/

Deletes an external study with all its participation data.

Request body

{
  "identifierType": "internal_id",
  "identifierValue": "Example"
}

Response body

true

GET /panel/externalsurveys/

Retrieves a list of all external surveys.

Response body

[
  {
    "externalSurveyId": 1,
    "externalSurveyExternalId": "1234",
    "externalSurveyTitle": "Example",
    "externalSurveyType": 1234,
    "externalSurveyAttributes": [
      {
        "attributeName": "Name",
        "attributeValue": "Example"
      }
    ],
    "externalSurveyModificationDate": "2020-07-02T12:53:50+00:00"
  }
]

PATCH /panel/externalsurveys/

Updates an existing external survey with new attributes. The survey’s external ID cannot be changed.

Request body

{
  "identifierType": "internal_id",
  "identifierValue": "Example",
  "title": "Example",
  "type": 1234,
  "attributes": [
    {
      "attributeName": "Name",
      "attributeValue": "Example"
    }
  ]
}

Response body

true

POST /panel/externalsurveys/

Retrieves a list of external surveys that were modified since a given timestamp

Request body

{
  "timestamp": "2020-07-02T12:53:50+00:00"
}

Response body

[
  {
    "externalSurveyId": 1,
    "externalSurveyExternalId": "1234",
    "externalSurveyTitle": "Example",
    "externalSurveyType": 1234,
    "externalSurveyAttributes": [
      {
        "attributeName": "Name",
        "attributeValue": "Example"
      }
    ],
    "externalSurveyModificationDate": "2020-07-02T12:53:50+00:00"
  }
]

POST /panel/externalsurveys/add

Adds a new external survey, returns ID

Request body

{
  "title": "Example",
  "type": 1234,
  "attributes": [
    {
      "attributeName": "some_attribute",
      "attributeValue": "Example"
    }
  ]
}

Response body

POST /panel/externalsurveys/data

Retrieves the data of the external survey

Request body

{
  "identifierType": "internal_id",
  "identifierValue": "Example"
}

Response body

{
  "externalSurveyId": 1,
  "externalSurveyExternalId": "123",
  "externalSurveyTitle": "Example",
  "externalSurveyType": 1234,
  "externalSurveyAttributes": [
    {
      "attributeName": "Name",
      "attributeValue": "Example"
    }
  ],
  "externalSurveyModificationDate": "2020-07-02T12:53:50+00:00"
}

POST /panel/externalsurveys/participants

Adds or updates the participation status of multiple participants in an external survey

Request body

{
  "identifierType": "internal_id",
  "identifierValue": "Example",
  "panelistIdentifierType": "u_email",
  "surveyParticipations": [
    {
      "panelistIdentifierValue": "example@domain.tld",
      "participationStatus": "10",
      "participationDate": "2020-07-02T12:53:50+00:00",
      "participationPoints": 1.345,
      "participationScore": 1.345
    }
  ]
}

Response body

true

Group categories

POST /panel/groups/category

adds a new panel group category

Request body

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

Response body

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

GET /panel/groups/category/{categoryId}

returns group category data

Response body

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

URI Parameters

Name	Type	Required	Description
categoryId	integer	true	id of panel group category Examples: `2`.

POST /panel/groups/categoryByName

returns group category data

Request body

{
  "categoryName": "Example"
}

Response body

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

Groups

DELETE /panel/groups/

Removes panelist from group (id)

Request body

{
  "id": 1234,
  "identifierType": "u_email",
  "identifierValues": [
    "example@domain.tld"
  ]
}

Response body

true

POST /panel/groups/

add a new panel group, returns id of group

Request body

{
  "name": "Example",
  "description": "Example",
  "categoryId": 1
}

Response body

POST /panel/groups/list

gets a list of panel groups, optionally restricted to a specific panel group category

Request body

{
  "restrictCategoryId": 2
}

Response body

[
  {
    "groupId": 123,
    "name": "Example",
    "description": "Example description",
    "size": 1234,
    "categoryId": 2,
    "categoryName": "Example"
  }
]

DELETE /panel/groups/{id}

Delete a panel group along with any panelist-group membership records plus any update rules for group. Panelist data of group members will not be deleted.

Response body

true

URI Parameters

Name	Type	Required	Description
id	integer	true	id of the panel group to be deleted Examples: `2`.

PATCH /panel/groups/{id}

add panelists to an existing panel group

Request body

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

Response body

true

URI Parameters

Name	Type	Required	Description
id	integer	true	id of the panel group to be deleted Examples: `2`.

POST /panel/groups/{id}

Supplies a list of panelists which are members in a given group

Request body

{
  "returnIdentifierType": "uid"
}

Response body

[ "123", "124", "125" ]

URI Parameters

Name	Type	Required	Description
id	integer	true	id of the panel group to be deleted Examples: `2`.

PUT /panel/groups/{id}

empty a panel group by deleting all members from it

Response body

true

URI Parameters

Name	Type	Required	Description
id	integer	true	id of the panel group to be deleted Examples: `2`.

Lotteries

POST /panel/lotteries/{gid}

Create prize draw, returns id

Request body

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

Response body

URI Parameters

Name	Type	Required	Description
gid	integer	true	Panel group id Examples: `2`.

DELETE /panel/lotteries/{id}

Delete prize draw. Includes deletion of prizes and winners.

Response body

true

URI Parameters

Name	Type	Required	Description
id	integer	true	Lottery id Examples: `2`.

GET /panel/lotteries/{id}

Get prize draw by prize draw ID. Provides prize draw object to access gratification and other parameters.

Response body

{
  "id": 2,
  "title": "Example",
  "description": "Example",
  "status": "Created",
  "groupId": 1
}

URI Parameters

Name	Type	Required	Description
id	integer	true	Lottery id Examples: `2`.

PATCH /panel/lotteries/{id}

Update status of prize draw with given prize draw ID.

Request body

{ "status": "ARCHIVED" }

Response body

true

URI Parameters

Name	Type	Required	Description
id	integer	true	Lottery id Examples: `2`.

DELETE /panel/lotteries/{id}/winners

Delete winner

Response body

true

URI Parameters

Name	Type	Required	Description
id	integer	true	Lottery id Examples: `2`.

GET /panel/lotteries/{id}/winners

Get winners by prize draw id

Response body

[
  {
    "grid": 1234,
    "prid": 1234,
    "uid": 1234,
    "status": "Example",
    "u_firstname": "Example",
    "u_name": "Example",
    "u_email": "example@domain.tld",
    "pricetitle": "Example"
  }
]

URI Parameters

Name	Type	Required	Description
id	integer	true	Lottery id Examples: `2`.

Master data

GET /panel/masterdata/

returns the panel’s master data variables along with their predefined answer codes

Response body

[
  {
    "varname": "m_0000",
    "label": "Country",
    "type": "int",
    "typeGroup": "numeric",
    "recoded": false,
    "categories": [
      {
        "code": 3,
        "label": "USA"
      },
      {
        "code": 2,
        "label": "United Kingdom"
      },
      {
        "code": 1,
        "label": "Germany"
      },
      {
        "code": 0,
        "label": "Please select"
      }
    ]
  },
  {...}
]

POST /panel/masterdata/

add masterdata variable

Request body

{
  "name": "m_9988",
  "label": "m_9988 Label",
  "type": "tinyint",
  "category": 1,
  "optional": true
}

Response body

"m_9988"

GET /panel/masterdata/{modificationDate}/list

returns the panel’s master data variables along with their predefined answer codes, which were modified after modificationDate.

Response body

[
  {
    "varname": "m_9988",
    "label": "Example",
    "type": "smallint",
    "typeGroup": "Example",
    "recoded": true,
    "categories": [
      {
        "code": 1234,
        "label": "Example",
        "isMissing": true
      }
    ]
  }
]

URI Parameters

Name	Type	Required	Description
modificationDate	integer	true	variables with modification date newer than given parameter will be respected (timestamp) Examples: `1599147158`.

Panelists

DELETE /panel/panelists/

Delete panelist

Request body

{
  "identifierType": "uid",
  "identifierValue": "123"
}

Response body

true

PATCH /panel/panelists/

change multiple panelists’ account data from a CSV file (batch operation)

Request body

{
  "identifierType": "u_email",
  "csvData": "csv content"
}

Response body

{
  "successful": 1,
  "failed": 1,
  "failedRows": [
    {
      "line": 2,
      "errors": [
        {
          "column": "Example",
          "value": "Example",
          "details": [
            {
              "code": "Example",
              "translated": "Example",
              "type": 1234
            }
          ]
        }
      ]
    }
  ],
  "returnIdentifiers": [
    {
      "internalReturnValue": "Example",
      "externalReturnValue": "Example"
    }
  ]
}

POST /panel/panelists/v1

Adds a panelist to the panel. Fields u_email, u_firstname, u_name, u_passwd are required.
Please note, that POST /panel/panelists (without v1) is deprecated and should no longer be used.

Request body

{
  "returnIdentifierType": "uid",
  "panelistData": {
    "u_account": "Example",
    "u_firstname": "First",
    "u_name": "Last",
    "u_street": "Example",
    "u_zip": "12345",
    "u_city": "Example",
    "u_phone": "+4912345",
    "u_email": "example@domain.tld",
    "u_www": "Example",
    "u_address": "Example",
    "u_country": "Example",
    "u_other_id": "123",
    "u_gender": "NOT_SPECIFIED",
    "u_address2": "Example",
    "u_address3": "Example",
    "u_mobile": "Example",
    "u_mobile2": "Example",
    "pci": 127,
    "masterDataValues": [
      {
        "key": "m_0000",
        "value": "12"
      }
    ],
    "u_sec_quest": "Example",
    "u_sec_quest_answer": "Example",
    "site_id": 1,
    "u_timezone": "+0:00",
    "gc_id": 1,
    "u_passwd": "Example",
    "gid": 1
  }
}

Response body

"123"

POST /panel/panelists/csv

add multiple panelists from a CSV file to the panel (batch operation)

Request body

{
  "returnIdentifierType": "uid",
  "csvData": "Csv Data here",
  "mappingColumn": "email"
}

Response body

{
  "successful": 1,
  "failed": 1,
  "failedRows": [
    {
      "line": 2,
      "errors": [
        {
          "column": "Email",
          "value": "example@domain.tld",
          "details": [
            {
              "code": "Example",
              "translated": "Example",
              "type": 1234
            }
          ]
        }
      ]
    }
  ],
  "returnIdentifiers": [
    {
      "internalReturnValue": "123",
      "externalReturnValue": "example@domain.tld"
    }
  ]
}

POST /panel/panelists/details

get information about a panelist

If no panelist is found, this service will return a 500 error.

Request body

{
  "identifierType": "uid",
  "identifierValue": "123"
}

Response body

{
  "u_account": "Example",
  "u_firstname": "First",
  "u_name": "Last",
  "u_street": "Example",
  "u_zip": "12345",
  "u_city": "Example",
  "u_phone": "+4912345",
  "u_email": "example@domain.tld",
  "u_www": "Example",
  "u_address": "Example",
  "u_country": "Example",
  "u_other_id": "12345",
  "u_gender": "NOT_SPECIFIED",
  "u_address2": "Example",
  "u_address3": "Example",
  "u_mobile": "+4912345",
  "u_mobile2": "+4912345",
  "masterDataValues": [
    {
      "key": "m_0000",
      "value": "1"
    }
  ],
  "site_id": 1,
  "u_timezone": "+0:00",
  "gc_id": 10,
  "uid": 123
}

PUT /panel/panelists/details

Change an existing panelist’s data

Request body

{
  "identifierType": "uid",
  "identifierValue": "123",
  "panelistData": {
    "u_firstname": "NewFirst",
    "u_name": "NewLast",
    "masterDataValues": [
      {
        "key": "m_0001",
        "value": "2"
      }
    ]
  }
}

Response body

true

DELETE /panel/panelists/external

Deletes an external authentication mapping from EFS. Please note: Only the mapping will be deleted. The panelist will not be removed from EFS.

Request body

{
  "externalServiceId": 1234,
  "externalAuthenticationValue": "Example"
}

Response body

true

POST /panel/panelists/external

Establishes a mapping between a member of an external system (specified by the external_service_id and the external_service_authentication_value) and an EFS panelist. This can be used to implement seamless logins for EFS panelists coming from external web applications.

Request body

{
  "externalServiceId": 1,
  "externalAuthenticationValue": "Example",
  "identifierType": "uid",
  "identifierValue": "123"
}

Response body

true

POST /panel/panelists/external/{externalServiceId}

Returns the EFS identifier for a member of an external system. If the member has not been registered in EFS using the save_external_panelist_authentication web service before, this service will throw an exception.

Request body

{
  "externalAuthenticationValue": "Example",
  "identifierReturnType": "Example"
}

Response body

"Example"

URI Parameters

Name	Type	Required	Description
externalServiceId	integer	true	The external ID. Examples: `2`.

POST /panel/panelists/group/{groupId}/list

returns a list of panelists in a specific panel group

Request body

{ "returnDataFields": [ "Example" ] }

Response body

[ [ "Example" ] ]

URI Parameters

Name	Type	Required	Description
groupId	integer	true	id of panel group Examples: `2`.

POST /panel/panelists/groups

Returns a list of panel groups in which the panelist is a member

Request body

{
  "identifierType": "uid",
  "identifierValue": "123"
}

Response body

[
  {
    "panelGroupId": 10,
    "panelGroupName": "Example",
    "panelGroupStatus": "ACTIVE"
  }
]

POST /panel/panelists/list

returns a list of panelists matched by a specific panel survey sample

Request body

{
  "sampleId": 1,
  "returnDataFields": [
    "u_email",
    "uid"
  ]
}

Response body

[
  [
    "example@domain.tld",
    "123"
  ]
]

POST /panel/panelists/list/find

returns a list of actual panelists from a list of possible panelist identifiers using this service it can be checked if specific panelists are already contained in the panel or not

Request body

{
  "identifierType": "u_email",
  "identifierList": [
    "example@domain.tld", "example2@domain.tld"
  ],
  "returnDataFields": [
    "uid",
    "u_email"
  ]
}

Response body

[
    [
        "215",
        "example2@domain.tld"
    ],
    [
        "214",
        "example@domain.tld"
    ]
]

POST /panel/panelists/login

Checks whether a panelist can login to the panel website with the login data specified.

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

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

PATCH /panel/panelists/setstatus

Updates the panel status of a panelist.

Request body

{
  "identifierType": "u_email",
  "identifierValue": "example@domain.tld",
  "status": 2
}

Response body

true

POST /panel/panelists/survey/{surveyId}

Add a panelist to a panel or master data survey. Valid options for resetParticipation: reset_if_completed, reset_always, reset_delete_if_completed, reset_delete_always, reset_no_change

Request body

{
  "identifierType": "uid",
  "identifierValue": "123",
  "resetParticipation": "reset_if_completed"
}

Response body

{
  "sampleId": 1,
  "dispositionCode": "10",
  "code": "Example",
  "isTester": false,
  "link": "http://Example"
}

URI Parameters

Name	Type	Required	Description
surveyId	integer	true	id of the panel or masterdata survey Examples: `2`.

POST /panel/panelists/{sampleId}

Add a panelist to a sample. Valid options for resetParticipation: reset_if_completed, reset_always, reset_delete_if_completed, reset_delete_always, reset_no_change

Request body

{
  "identifierType": "uid",
  "identifierValue": "123",
  "resetParticipation": "reset_if_completed"
}

Response body

{
  "sampleId": 1,
  "dispositionCode": "10",
  "code": "Example",
  "isTester": false,
  "link": "http://Example"
}

URI Parameters

Name	Type	Required	Description
sampleId	integer	true	id of panel survey sample Examples: `2`.

POST /panel/panelists/{filterId}/list

returns a list of panelists matched by a specific panel grouping filter

Request body

{ "returnDataFields": [ "u_email" ] }

Response body

[ [ "example@domain.tld" ] ]

URI Parameters

Name	Type	Required	Description
filterId	integer	true	id of panel grouping filter Examples: `2`.

Bonus points

PATCH /panel/panelists/bonuspoints

Reset the bonus points of one or multiple panelists to zero. This action will also add a note to each panelists’ bonus points balance so panelists get informed about the nullification. If a panelist already has a balance of zero points, no additional note will be added to his/her points log

Request body

{
  "identifierType": "uid",
  "identifierList": [
    "123"
  ],
  "description": "Example bonus points reset"
}

POST /panel/panelists/bonuspoints

Returns the bonus points of a given panelist.

Request body

{
  "identifierType": "uid",
  "identifierValue": "123"
}

Response body

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

POST /panel/panelists/bonuspoints/balance

Returns the account balance/bonus points positions for all panelists of the installation that happened since the last call to the service. This method can be used to do a regular, incremental replication of the panel’s bonus points to another application (where EFS is used as the master system for managing the points). The panelist identifier for the returned balance positions can be uid, panelist code, pseudonym etc.

Request body

{
  "returnIdentifierType": "uid",
  "fetchAll": true,
  "logTransfer": true
}

Response body

[
  {
    "panelist_identifier_value": "123",
    "item_type": 0,
    "survey_id": 1701,
    "points_id": 6,
    "description": "Participation in survey Demo",
    "credit_points": 10,
    "date": "2018-07-05T08:37:57+00:00",
    "paid": 0,
    "paid_date": "",
    "alt_address": ""
  }
]

POST /panel/panelists/bonuspoints/balance/find

Returns the account balance/bonus points positions for a panelist that happened in the last months. The panelist can be identified by different criteria (user_id, panelist code, pseudonym etc.).

Request body

{
  "identifierType": "uid",
  "identifierValue": "123,
  "monthsRange": 1,
  "skipEmpty": true
}

Response body

[
  {
    "panelist_identifier_value": "123",
    "item_type": 0,
    "survey_id": 1701,
    "points_id": 6,
    "description": "Participation in survey Demo",
    "credit_points": 10,
    "date": "2018-07-05T08:37:57+00:00",
    "paid": 0,
    "paid_date": "",
    "alt_address": ""
  }
]

POST /panel/panelists/bonuspoints/{surveyId}

Manually grants bonus points to a list of panelists for participation in a panel or master data survey. Successful requests have no response body.

Request body

{
  "identifierType": "uid",
  "identifierList": [
    "123", "124", "125"
  ],
  "points": 10,
  "description": "Example bonus points"
}

URI Parameters

Name	Type	Required	Description
surveyId	integer	true	Id of the panel or master data survey. Examples: `2`.

POST /panel/panelists/redemption

Returns the bonus points redemption positions for all panelists of the installation that happened since the last call to the service. This method can be used to do a regular, incremental replication of the panel’s bonus points redemption to another application (where EFS is used as the master system for managing the points). The panelist identifier for the returned redemption can be user_id, panelist code, pseudonym etc.

Request body

{
  "identifierType": "uid",
  "fetchAll": true,
  "logTransfer": true
}

Response body

[
  {
    "panelist_identifier_value": "Example",
    "item_type": 1234,
    "survey_id": 1234,
    "points_id": 1234,
    "description": "Example",
    "credit_points": 1.345,
    "date": "Example",
    "paid": 1234,
    "paid_date": "Example",
    "alt_address": "Example",
    "voucher_code": "Example"
  }
]

POST /panel/promotions/

This service can be used to check whether an e-mail address has already been entered into the promotional system and what its status is. Invited only or already converted into a panelist.

Request body

{ "recipientEmail": "example@domain.tld" }

Response body

[
  {
    "status": 1234,
    "code": "Example",
    "date_invited": "2018-07-05T08:37:57+00:00",
    "date_converted": "2018-07-05T08:40:00+00:00"
  }
]

PUT /panel/promotions/

Sends an invitation as e-mail to a friend.

Request body

{
  "promotionId": 1234,
  "recipientEmail": "example@domain.tld",
  "header": "Example text",
  "footer": "Example text",
  "panelistUid": 123
}

Response body

true

POST /panel/samples/

Sends mails to every panelist in the sample

Request body

{
  "sampleId": 1,
  "mailTemplate": {
    "subject": "Example",
    "textContent": "Example",
    "htmlContent": "Example",
    "charset": "UTF-8",
    "replyTo": "Example",
    "returnPath": "Example",
    "priority": "NO_PRIORITY",
    "sensitivity": "NORMAL",
    "notify": "NO_NOTIFICATION",
    "toRealname": true,
    "from": "Example",
    "sms_from": "Example",
    "sms_content": "Example",
    "cc": "Example",
    "bcc": "Example",
    "fromRealname": "Example"
  },
  "dispcodes": [
    "10"
  ],
  "sendOptions": {
    "sendDate": "2020-07-02T12:53:50+00:00",
    "useRecipientTimezone": true
  }
}

Response body

true

Panel statistics

GET /panel/statistics/status

Panel status distribution

Response body

[
    {
        "code": "1",
        "label": "Admitted temporarily",
        "value": 26,
        "ratio": 0.19259259259259
    },
    {
        "code": "2",
        "label": "Active",
        "value": 93,
        "ratio": 0.68888888888889
    }, ...
]

POST /panel/statistics/status

Dynamic panel status distribution

Request body

{
  "panelStatisticsFilter": {
    "panelCategoryId": 1234,
    "panelGroupId": 1234,
    "siteId": 1234,
    "filterId": 1234,
    "from": "2020-07-01T12:53:50+00:00",
    "to": "2020-07-03T12:53:50+00:00",
    "panelistStatus": [
      1234
    ],
    "attributes": [
      "Example"
    ],
    "masterdata": [
      "Example"
    ]
  }
}

Response body

[
  [
    {
      "code": "Example",
      "label": "Example",
      "value": 1234,
      "ratio": 1.345
    }
  ]
]

POST /panel/surveys/

get the list of surveys for a panelist

Request body

{ "identifierType": "uid", "identifierValue": "123" }

Response body

[
  {
    "id": 1234,
    "title": "Example",
    "titleGlobal": "Example",
    "description": "Example",
    "author": "Example",
    "staff": "Example",
    "comment": "Example",
    "url": "http://qb-feedback.com/",
    "fieldTime": {
      "startTime": "2020-07-02T12:53:50+00:00",
      "endTime": "2020-07-02T12:53:50+00:00"
    },
    "type": "ANONYMOUS",
    "bonusPoints": {
      "label": "Example",
      "value": 1.345
    },
    "participantsLeft": 1234
  }
]

POST /panel/surveys/list

Returns the list of EFS Panel surveys (surveys of type panel survey or master data survey) a panelist has completed so far

Request body

{ "identifierType": "uid", "identifierValue": "123" }

Response body

[
  {
    "surveyId": 1234,
    "surveyTitle": "Some Title",
    "surveyDescription": "Example",
    "surveyType": "ANONYMOUS",
    "completionReward": 1.345,
    "completionDate": "2020-07-02T12:53:50+00:00"
  }
]

GET /panel/variables/

returns the panel’s variables along with their predefined answer codes (if any)

Response body

[
    {
        "varname": "m_0000",
        "label": "Country",
        "type": "int",
        "typeGroup": "numeric",
        "recoded": false,
        "categories": [
            {
                "code": 3,
                "label": "USA"
            },
            {
                "code": 2,
                "label": "United Kingdom"
            },
            {
                "code": 1,
                "label": "Germany"
            },
            {
                "code": 0,
                "label": "Please select"
            }
        ]
    }, ...
]

GET /panel/websites/

Returns a list of panel websites

Response body

[
    {
        "id": 4,
        "name": "Panel Website",
        "description": "",
        "isDefault": true,
        "languages": [
            {
                "id": 7,
                "name": "english",
                "isDefault": true
            }
        ]
    }
]

Portals

GET /portal/portal/export/{portalId}

Get portal export by portalId

Response body

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

URI Parameters

Name	Type	Required	Description
portalId	integer	true	Export portal with this ID Examples: `2`.

POST /portal/portal/import

Import portal by using previous export

Request body

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

Response body

"123"

POST /portal/users/getUserDataByToken

Checks whether API-token is valid (not expired). Returns userId and portalId. Otherwise will throw an exception.

Request body

{ "apiToken": "Example123" }

Response body

{ "portalUserId": "123", "portalId": "123" }

PUT /portal/users/invitePanelistToPortal

Invite Panelists to Portal

Request body

{
  "identifierType": "uid",
  "identifierList": [
    "123"
  ],
  "portalId": 1234,
  "mailTemplateId": 1234
}

Response body

true

POST /portal/users/logincode

Get tmp login code

Request body

{ "identifierType": "uid", "identifierValue": "123" }

Response body

"1233ffaa123..."

POST /portal/users/setUserRoles

Set role(s) for user(s) in portal

Request body

{
  "portalUsersRolesList": [
    {
      "portalUserId": "123",
      "userRoleList": [
        "1", "3"
      ]
    }
  ],
  "portalId": "1"
}

Response body

true

Survey

Languages

GET /survey/languages/{surveyId}

get a list of all languages in a survey

Response body

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

URI Parameters

Name	Type	Required	Description
surveyId	integer	true	surveyId Examples: `2`.

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

get a language

Response body

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

URI Parameters

Name	Type	Required	Description
surveyId	integer	true	surveyId Examples: `2`.
languageId	integer	true	languageId Examples: `2`.

POST /survey/languages/{surveyId}

adds a new language

Request body

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

Response body

URI Parameters

Name	Type	Required	Description
surveyId	integer	true	surveyId Examples: `2`.

PATCH /survey/languages/{surveyId}

change language data

Request body

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

Response body

true

URI Parameters

Name	Type	Required	Description
surveyId	integer	true	surveyId Examples: `2`.

DELETE /survey/languages/{surveyId}

deletes a language

Request body

{ "languageId": 1 }

Response body

true

URI Parameters

Name	Type	Required	Description
surveyId	integer	true	surveyId Examples: `2`.

Layouts

GET /survey/layouts/

returns a list of all survey layouts the user has access to

Response body

[ { "layoutId": 1, "name": "Example" } ]

POST /survey/layouts/find

returns a list of survey layouts the user has access to, based on search criteria. See filtering results with conditions for help on building conditions.

Request body

{
  "logicalCondition": {
    "comparison": {
      "variable": "title",
      "operator": "CONTAINS",
      "value": "Example"
    }
  }
}

Response body

[ { "layoutId": 1, "name": "Example Layout" } ]

PATCH /survey/layouts/{surveyId}

Applies a survey layout in a specific survey.

Request body

{ "layoutId": 1 }

Response body

true

URI Parameters

Name	Type	Required	Description
surveyId	integer	true	survey id Examples: `2`.

Static lists

GET /survey/lists/{surveyId}

Returns the list of available static lists for a survey

Response body

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

URI Parameters

Name	Type	Required	Description
surveyId	integer	true	id of survey Examples: `2`.

POST /survey/lists/{surveyId}

Returns the ID of the created static list

Request body

{
  "label": "Example",
  "placeholder": "example",
  "delimiter": ", ",
  "lastDelimiter": " and "
}

Response body

URI Parameters

Name	Type	Required	Description
surveyId	integer	true	id of survey Examples: `2`.

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

Deletes a list

URI Parameters

Name	Type	Required	Description
surveyId	integer	true	id of survey Examples: `2`.
listId	integer	true	list id Examples: `2`.

PUT /survey/lists/{surveyId}

Adds an array of static list elements

Request body

{
  "listId": 1,
  "items": [
    {
      "number": 1,
      "label": "Apples"
    },
    {
      "number": 2,
      "label": "Oranges"
    }
  ]
}

Response body

[ 1, 2 ]

URI Parameters

Name	Type	Required	Description
surveyId	integer	true	id of survey Examples: `2`.

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

Adds a static list element

Request body

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

Response body

URI Parameters

Name	Type	Required	Description
surveyId	integer	true	id of survey Examples: `2`.
listId	integer	true	list id Examples: `2`.

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

Clears a list

URI Parameters

Name	Type	Required	Description
surveyId	integer	true	id of survey Examples: `2`.
listId	integer	true	id of list Examples: `2`.

Participants

POST /survey/participants/v2/{sampleId}

Add multiple participants to a survey. Only u_email is required and you can skip all other fields. Additional participant variables can be filled through additionalFields. When providing u_passwd, please note that this field needs to be unique. Valid options for returnIdentifierType are u_email, code and uid. u_email is only available if allowDuplicateEmails is set to false.

POST /survey/participants/{sampleId}, without v2, should no longer be used, as it was replaced with this call. To migrate your application to the new call, add allowDuplicateEmails to the old request and change the end point to …/v2/.

Also, in personalised projects, the sampleId is the surveyId plus 1.

Request body

{
  "returnIdentifierType": "code",
  "participantList": [
    {
      "u_passwd": "123456",
      "u_firstname": "First",
      "u_name": "Last",
      "u_email": "example@domain.tld",
      "u_mobile": "0049123456",
      "u_title": "Dr.",
      "u_gender": "NOT_SPECIFIED",
      "u_group": 1,
      "u_language": 1,
      "u_timezone": "+0:00",
      "additionalFields": [
        {
          "key": "u_example",
          "value": "test"
        }
      ]
    }
  ],
  "allowDuplicateEmails": true
}

Response body

[ "fd68114f34314916" ]

URI Parameters

Name	Type	Required	Description
sampleId	integer	true	id of sample to add the participants to Examples: `2`.

POST /survey/participants/v3/{sampleId}

Add multiple participants to a survey via task queue. Returns taskId which has to be used to get results via GET /efs/taskqueue/{taskId}.

This is the recommended call for importing bigger batches of participants to a survey and this call is request body compatible to /v2.

Request body

{
  "returnIdentifierType": "u_email",
  "participantList": [
    {
      "u_passwd": "123456",
      "u_firstname": "First",
      "u_name": "Last",
      "u_email": "example@domain.tld",
      "u_mobile": "0049123456",
      "u_title": "Dr.",
      "u_gender": "NOT_SPECIFIED",
      "u_group": 1,
      "u_language": 1,
      "u_timezone": "+0:00",
      "additionalFields": [
        {
          "key": "u_example",
          "value": "test"
        }
      ]
    }
  ],
  "allowDuplicateEmails": true
}

Response body

URI Parameters

Name	Type	Required	Description
sampleId	integer	true	id of sample to add the participants to Examples: `2`.

POST /survey/participants/{sampleId}/csv

Add multiple participants from a CSV file to a survey or update existing participants using data from a CSV file. Note: this operation works on surveys of type “personalized” only.

Unlike in the interface, the first row of the CSV data needs to have the correct column labels from the import template of the project. Only u_email is required.

This call corresponds to the participant import of the participant administration.

returnIdentifierType returns the specified identifier variable as internalReturnValue, usually you will want to know the “uid” of the participant.

mappingColumn returns the specified participant variable as externalReturnValue. This can used to store back information in your system, e.g. by uploading u_crm_id in your CSV data and using that variable as a mappingColumn.

Request body

{
  "csvData": "u_email,u_first,u_name\nexample@domain.tld,First,Last\nexample2@domain.tld,First2,Last2",
  "returnIdentifierType": "uid",
  "allowDuplicateEmails": true,
  "mappingColumn": "u_email"
}

Response body

{
    "successful": 3,
    "failed": -1,
    "failedRows": [],
    "returnIdentifiers": [
        {
            "internalReturnValue": "1",
            "externalReturnValue": "example@domain.tld"
        },
        {
            "internalReturnValue": "2",
            "externalReturnValue": "example2@domain.tld"
        }
    ]
}

URI Parameters

Name	Type	Required	Description
sampleId	integer	true	id of sample to add the participants to or to update the participants in Examples: `2`.

POST /survey/participants/{sampleId}/csv2

Add multiple participants and optionally survey results from a CSV file to a survey or update existing participants using data from a CSV file. Note: this operation works on surveys of type “personalized” or “employee” only.

Unlike in the interface, the first row of the CSV data needs to have the correct column labels from the import template of the project. Unless status is specified, the disposition code will be automatically set to 31 – Completed.

This call corresponds to the results import of the participant administration.

returnIdentifierType returns the specified identifier variable as internalReturnValue, usually you will want to know the “uid” of the participant.

Request body

{
  "csvData": "u_email,u_first,u_name,v_1\nexample@domain.tld,First,Last,2\nexample2@domain.tld,First2,Last2,1",
  "returnIdentifierType": "uid",
  "allowDuplicateEmails": true,
  "mappingColumn": "u_email"
}

Response body

{
    "successful": 3,
    "failed": -1,
    "failedRows": [],
    "returnIdentifiers": [
        {
            "internalReturnValue": "1",
            "externalReturnValue": "example@domain.tld"
        },
        {
            "internalReturnValue": "2",
            "externalReturnValue": "example2@domain.tld"
        }
    ]
}

URI Parameters

Name	Type	Required	Description
sampleId	integer	true	id of sample to add the participants to Examples: `2`.

PUT /survey/participants/{sampleId}/updateParticipantVariablesList

Updates user’s participant variables for given sample ID. Only available for personalized surveys. Returns list of participation data with updated values. Unknown participations and unknown variables are removed, invalid values will be replaced by standard values.

Request body

{
  "participantVariablesList": [
    {
      "uid": 1,
      "variables": [
        {
          "variable": "u_example",
          "value": "Example"
        }
      ]
    }
  ]
}

Response body

[
  {
    "uid": 1,
    "variables": [
      {
        "variable": "u_example",
        "value": "Example"
      }
    ]
  }
]

URI Parameters

Name	Type	Required	Description
sampleId	integer	true	id of survey Examples: `2`.

GET /survey/participants/v2/{sampleId}/{additionalInfo}

Returns a list of participants. The operation is allowed for personalized surveys only. If the parameter withAdditionalFields is set to true, additional variables for participant will be returned.

Response body

[
  {
    "uid": 1,
    "u_passwd": "ZDhjNDA2OGY=",
    "u_firstname": "First",
    "u_name": "Last",
    "u_email": "example@domain.tld",
    "u_mobile": "",
    "u_title": "",
    "u_gender": "NOT_SPECIFIED",
    "u_group": 0,
    "m_date": "2020-02-18T12:33:19+00:00",
    "c_date": "2020-02-18T11:39:29+00:00",
    "u_timezone": "+0:00"
  }, ...
]

URI Parameters

Name	Type	Required	Description
sampleId	integer	true	sample to query Examples: `2`.
additionalInfo	boolean	true	Flag for the additional information to participant Examples: `true`.

POST /survey/participants/{sampleId}/find

Returns a list of participants according to the specified sample. The operation is allowed for personalized surveys only. The size of result set can be limited by using parameter ‘offset’ and ‘limit’. Use parameter ‘withAdditionalFields’ in order to get the additional information for participant or suppress it.

See filtering results with conditions for help on building conditions.

Request body

{
  "logicalCondition": {
    "comparison": {
      "variable": "u_email",
      "operator": "CONTAINS",
      "value": "example"
    }
  },
  "offset": 0,
  "limit": 10,
  "additionalInfo": false
}

Response body

[
  {
    "uid": 19,
    "u_passwd": "MjRkM2ZiZWE=",
    "u_firstname": "First",
    "u_name": "Last",
    "u_email": "example@domain.tld",
    "u_mobile": "",
    "u_title": "",
    "u_gender": "NOT_SPECIFIED",
    "u_group": 0,
    "m_date": "2020-08-28T08:24:11+00:00",
    "c_date": "2020-08-28T08:24:11+00:00",
    "u_timezone": "+0:00"
  }
]

URI Parameters

Name	Type	Required	Description
sampleId	integer	true	sample to query Examples: `2`.

DELETE /survey/participants/{sampleId}

Deletes all participants from sample of a personalised or anonymous survey project, including their already collected survey results.

Response body

true

URI Parameters

Name	Type	Required	Description
sampleId	integer	true	id of sample Examples: `2`.

DELETE /survey/participants/{sampleId}/{userId}

delete a participant from a survey sample, along with any already collected survey results for the participant

Response body

true

URI Parameters

Name	Type	Required	Description
sampleId	integer	true	id of sample Examples: `2`.
userId	integer	true	id of participant Examples: `2`.

PATCH /survey/participants/{surveyId}/reset

Resets a survey participation for participant. Existing survey data can be kept or deleted. The operation is allowed for personalized surveys only. Valid options for resetType are keepData, deleteData.

Request body

{
  "participantIdentifierType": "u_email",
  "participantIdentifierValue": "example@domain.tld",
  "resetType": "keepData"
}

Response body

true

URI Parameters

Name	Type	Required	Description
surveyId	integer	true	Survey id Examples: `2`.

PATCH /survey/participants/{sampleId}

Sends mails to participants in a sample. Request is not available for anonymous surveys. With dis-codes you can decide which participants will receive the mail, e.g. when sending a reminder email, use codes 11 and 12 (and 10 in GDPR enabled projects).

Request body

{
  "uids": [
    1
  ],
  "mailTemplateId": 1234,
  "dispcodes": [
    "11", "12"
  ],
  "sendOptions": {
    "sendDate": "2020-07-02T12:53:50+00:00",
    "useRecipientTimezone": true
  }
}

URI Parameters

Name	Type	Required	Description
sampleId	integer	true	id of sample Examples: `2`.

PUT /survey/participants/{surveyId}

Sends mails to every participiant in a survey. Please note This service will fail on anonymous surveys and sending of SMS is not supported by this service.

Request body

{
    "mailTemplate": {
        "subject": "Example",
        "textContent": "Example",
        "htmlContent": "Example",
        "charset": "UTF-8",
        "replyTo": "Example",
        "returnPath": "Example",
        "priority": "NO_PRIORITY",
        "sensitivity": "NORMAL",
        "notify": "NO_NOTIFICATION",
        "toRealname": true,
        "from": "Example",
        "sms_from": "Example",
        "sms_content": "Example",
        "cc": "Example",
        "bcc": "Example",
        "fromRealname": "Example"
    },
    "uids": [
        1
    ],
    "dispcodes": [
        "10"
    ],
    "sendOptions": {
        "sendDate": "2020-07-02T12:53:50+00:00",
        "useRecipientTimezone": true
    }
}

URI Parameters

Name	Type	Required	Description
surveyId	integer	true	Survey id Examples: `2`.

Samples

GET /survey/samples/

return the list of samples for all surveys

Response body

[
    {
        "sampleId": 2287,
        "title": "(internal)",
        "desc": "",
        "cdate": "2020-02-13T10:11:11+00:00",
        "isInternal": true,
        "surveyId": 2286
    }, ...
]

GET /survey/samples/survey/{surveyId}

return the list of samples for a survey

Response body

[
    {
        "sampleId": 2287,
        "title": "(internal)",
        "desc": "",
        "cdate": "2020-02-13T10:11:11+00:00",
        "isInternal": true,
        "surveyId": 2286
    }
]

URI Parameters

Name	Type	Required	Description
surveyId	integer	true	id of survey Examples: `2`.

GET /survey/samples/sample/{sampleId}

return information about a survey sample

Response body

{
  "sampleId": 2287,
  "title": "(internal)",
  "desc": "",
  "cdate": "2020-02-13T10:11:11+00:00",
  "isInternal": true,
  "surveyId": 2286
}

URI Parameters

Name	Type	Required	Description
sampleId	integer	true	id of the sample Examples: `2`.

POST /survey/samples/{pid}

Add a sample to a survey

Request body

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

Response body

URI Parameters

Name	Type	Required	Description
pid	integer	true	project id Examples: `2`.

Placeholders

GET /survey/placeholders/{surveyId}

Returns a list of all survey wildcards for a given survey id, text is using default survey language.

Response body

[
    {
        "id": 3,
        "key": "#example#",
        "text": "Hello Example"
    }
]

URI Parameters

Name	Type	Required	Description
surveyId	integer	true	id of survey Examples: `2`.

GET /survey/placeholders/{surveyId}/{languageId}

Returns a list of all translated survey wildcards for a given survey id and survey language id

Response body

[
    {
        "id": 3,
        "key": "#example#",
        "text": "Hello Example"
    }
]

URI Parameters

Name	Type	Required	Description
surveyId	integer	true	id of survey Examples: `2`.
languageId	integer	true	survey language id the placeholder texts should be returned for Examples: `2`.

PATCH /survey/placeholders/{surveyId}/{id}

Change an existing survey wildcard text in the default survey language

Request body

{ "text": "Hallo Example" }

Response body

true

URI Parameters

Name	Type	Required	Description
surveyId	integer	true	id of survey Examples: `2`.
id	integer	true	id of placeholder to change Examples: `2`.

PUT /survey/placeholders/{surveyId}/{languageId}

Change an existings survey wildcards text in a certain survey language

Request body

{ "id": 1, "text": "Example" }

Response body

true

URI Parameters

Name	Type	Required	Description
surveyId	integer	true	id of survey Examples: `2`.
languageId	integer	true	survey language id the placeholder texts should be returned for Examples: `2`.

Questionnaire

GET /survey/questionnaire/{surveyId}

Return the questionnaire structure for a survey

Response body

[
  {
    "title": "System",
    "pgid": 1712,
    "type": "SYSTEM",
    "questions": [
      {
        "questiontext": "",
        "variables": []
      }
    ],
    "subPages": []
  },
  {
    "title": "End page",
    "pgid": 1714,
    "type": "ENDPAGE",
    "questions": [],
    "subPages": []
  }
]

URI Parameters

Name	Type	Required	Description
surveyId	integer	true	survey id Examples: `2`.

GET /survey/questionnaire/withIds/{surveyId}

Return the questionnaire structure for a survey with internal IDs for all elements

Response body

[
  {
    "title": "System",
    "pgid": 1712,
    "type": "SYSTEM",
    "questions": [
      {
        "questiontext": "",
        "variables": []
      }
    ],
    "subPages": []
  },
  {
    "title": "End page",
    "pgid": 1714,
    "type": "ENDPAGE",
    "questions": [],
    "subPages": []
  }
]

URI Parameters

Name	Type	Required	Description
surveyId	integer	true	survey id Examples: `2`.

POST /survey/questionnaire/{surveyId}

create a questionnaire page

Request body

{
  "pageTitle": "Example",
  "pageType": "STANDARD",
  "options": {
    "hideSubmit": false,
    "hideBackbutton": true,
    "autoPost": false,
    "parentPageId": -1,
    "previousPageId": 1
  }
}

Response body

URI Parameters

Name	Type	Required	Description
surveyId	integer	true	survey id Examples: `2`.

DELETE /survey/questionnaire/{surveyId}

delete a questionnaire page

Request body

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

Response body

true

URI Parameters

Name	Type	Required	Description
surveyId	integer	true	survey id Examples: `2`.

GET /survey/questionnaire/{surveyId}/list

Returns the configured bonus points for all end pages to the given surveyId, panel or master data surveys only.

Response body

[ { "pageId": 1234, "points": 10.0 } ]

URI Parameters

Name	Type	Required	Description
surveyId	integer	true	Survey ID Examples: `2`.

PUT /survey/questionnaire/{surveyId}/setPageBonusPoints

Applies bonus points to survey end-pages for the given surveyId, panel or master data surveys only.

Request body

{
  "pageBonusPoints": [
    {
      "pageId": 1234,
      "points": 10.0
    }
  ]
}

Response body

[ { "pageId": 1234, "points": 10.0 } ]

URI Parameters

Name	Type	Required	Description
surveyId	integer	true	id of survey Examples: `2`.

GET /survey/questions/{surveyId}/{varname}

Get response-categories by variable name and survey id

Response body

[
  {
    "code": 0,
    "rcat": "Unspecified"
  },
  {
    "code": 1,
    "rcat": "Male"
  },
  {
    "code": 2,
    "rcat": "Female"
  },
  {
    "code": 3,
    "rcat": "Other"
  }  
]

URI Parameters

Name	Type	Required	Description
surveyId	integer	true	id of survey Examples: `2`.
varname	string	true	variable name Examples: `Example`.

Reporting+

POST /survey/reports/{surveyId}

Create a standard Reporting+ report for a survey

Request body

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

Response body

URI Parameters

Name	Type	Required	Description
surveyId	integer	true	id of survey Examples: `2`.

POST /survey/reports/v2/{reportId}/publication

Create a Reporting+ export, valid options for reportType: html, xls, pdf, ppt, pptx, pptxpdf

Request body

{
  "reportType": "html",
  "fileName": "Example.html",
  "languageId": 1,
  "guiLanguage": "en"
}

Response body

URI Parameters

Name	Type	Required	Description
reportId	integer	true	id of survey report (to be created with createStandardReport) Examples: `2`.

DELETE /survey/reports/{reportId}

Delete a Reporting+ export

Response body

true

URI Parameters

Name	Type	Required	Description
reportId	integer	true	id of survey report (to be created with createStandardReport) Examples: `2`.

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

return the data for a publication

Response body

Base64 encoded binary data

URI Parameters

Name	Type	Required	Description
reportId	integer	true	id of report Examples: `2`.
reportPublicationId	integer	true	id of publication Examples: `2`.

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

Check if report is available

Response body

true

URI Parameters

Name	Type	Required	Description
reportId	integer	true	id of report Examples: `2`.
reportPublicationId	integer	true	id of publication Examples: `2`.

Survey participations

POST /survey/results/{surveyId}/configured

Returns the survey results as raw data in CSV format. dateRange, sort, config and individual config options are optional.
Valid options for exportTemplate: COMPLETE_SURVEY, WITHOUT_TIMESTAMP, TEXT_ONLY, NUMBER_ONLY, PARTICIPANT, PARTICIPANT_RESULT, PARTICIPANT_MASTER_RESULT, LOFT_COMBINED, LOFT_COMBINED_ANONYM.
Valid options for compression: NONE, ZIP, TAR.

Note: POST /survey/results/{surveyId}/completed and POST /survey/results/{surveyId} are deprecated. Please migrate to this call by adding /configured to your endpoint and supplying relevant config options.

Request body

{
  "exportTypes": [
    "QUESTIONNAIRE"
  ],
  "includeVariables": [
    "v_1", "v_2"
  ],
  "dateRange": {
    "from": "2020-07-01T12:53:50+00:00",
    "to": "2020-07-02T12:53:50+00:00"
  },
  "sort": [
    {
      "column": "lfdn",
      "direction": "ASC"
    }
  ],
  "config": {
    "exportTemplate": "COMPLETE_SURVEY",
    "charset": "UTF-8",
    "compression": "NONE",
    "missingValueText": "-66",
    "missingValueNumeric": "-77",
    "missingValueTimestamp": "0",
    "missingValueDatetime": "0000-00-00 00:00:00",
    "skipLoopVars": true,
    "dispositionCodeList": [
      "31"
    ],
    "useCommaDelimiter": true
  }
}

Response body

Base64 encoded binary data

URI Parameters

Name	Type	Required	Description
surveyId	integer	true	id of survey Examples: `2`.

GET /survey/results/{surveyId}/participations

Return frequencies for all disposition codes allocated in a survey, thus basic information about the survey’s participation statuses.

Response body

[
    {
        "code": 11,
        "count": 8
    },
    {
        "code": 12,
        "count": 2
    },
    {
        "code": 31,
        "count": 6
    }
]

URI Parameters

Name	Type	Required	Description
surveyId	integer	true	id of survey Examples: `2`.

GET /survey/results/{surveyId}/statistics

return frequency statistics for all closed-ended questions of a survey

Response body

[
    {
        "singleResultStatistic": {
            "varname": "v_2",
            "codeResultList": [
                {
                    "code": 1,
                    "count": 1,
                    "pct": 0
                },
                {
                    "code": 2,
                    "count": 1,
                    "pct": 0
                }
            ]
        }
    },
    {
        "multiResultStatistic": {
            "varname": "v_4",
            "codeResult": {
                "code": 1,
                "count": 3,
                "pct": 0
            }
        }
    }
]

URI Parameters

Name	Type	Required	Description
surveyId	integer	true	id of survey Examples: `2`.

POST /survey/results/{surveyId}/statistics

Get simple statistics for given panelist and variable list. Only available in panel and master data variables.

Request body

{
  "identifierType": "uid",
  "identifierValue": "123",
  "includeVariables": [
    "v_1"
  ]
}

Response body

[
    {
        "singleResultStatistic": {
            "varname": "v_1",
            "codeResultList": [
                {
                    "code": 1,
                    "count": 3,
                    "pct": 33
                },
                {
                    "code": 2,
                    "count": 3,
                    "pct": 33
                },
                {
                    "code": 3,
                    "count": 3,
                    "pct": 33
                }
            ],
            "mean": 2,
            "median": 2
        }
    }
]

URI Parameters

Name	Type	Required	Description
surveyId	integer	true	id of survey Examples: `2`.

PUT /survey/results/{surveyId}/updateSurveyResults

Updates participation data for given survey ID. Participations are matched by lfdn (id). Only available for anonymous, personalized and employee surveys. Supports update of user- and survey-variables and not loop-variables. If parameter executeTriggers is set to true, then only 100 records can be processed due to performance reasons, more records will cause an error. Returns list of participation data with updated values. Unknown participations or unknown variables will be removed, invalid values will be replaced by standard values.

Request body

{
  "surveyResults": [
    {
      "id": 1234,
      "results": [
        {
          "variable": "v_1",
          "value": "2"
        }
      ]
    }
  ],
  "executeTriggers": true
}

Response body

[
  {
    "id": 1234,
    "results": [
      {
        "variable": "v_1",
        "value": "2"
      }
    ]
  }
]

URI Parameters

Name	Type	Required	Description
surveyId	integer	true	id of survey Examples: `2`.

Field report / Statistics

POST /survey/statistics/{surveyId}/chart

Returns the png graph which represents the participation.

Valid values for lang: EN, DE, FR, FI, IT, NB, SV

Request body

{
  "lang": "EN",
  "restriction": [
    {
      "field_name": "v_2",
      "field_link": " IN ",
      "field_value": "1, 2, 3"
    }
  ]
}

Response body

Base64 encoded binary data

URI Parameters

Name	Type	Required	Description
surveyId	integer	true	The survey ID Examples: `2`.

POST /survey/statistics/{surveyId}/abs

Returns the absolute number of participation for a single disposition code and optionally limited by restriction.

Valid values for field_link: IN, BETWEEN, LIKE, NOT LIKE, =, !=, <>, <, <=, >, >=. Values LIKE, NOT LIKE should only be applied to text variables and to search for a substring, append “%”: E.g. “%world” will map “Hello World” but not “World, Hello”, search for “%world%” will find both occurrences.

Please note, contrary to the RAML and WSDL documentations, the use of splitVariable in criteria is not supported and returns erroneous result. An updated service will be provided shortly.

Request body

{
  "criteria": {
    "dispositionCodes": [
      "31"
    ]
  },
  "restriction": [
    {
      "field_name": "v_2",
      "field_link": "IN",
      "field_value": "1, 2, 3"
    }
  ]
}

Response body

URI Parameters

Name	Type	Required	Description
surveyId	integer	true	The survey ID Examples: `2`.

POST /survey/statistics/{surveyId}/abs/all

Returns the absolute number of participation for all disposition codes, optionally restricted by condition.
Valid values for field_link: IN, BETWEEN, LIKE, NOT LIKE, =, !=, <>, <, <=, >, >=. Values LIKE, NOT LIKE should only be applied to text variables and to search for a substring, append “%”: E.g. “%world” will map “Hello World” but not “World, Hello”, search for “%world%” will find both occurrences.

Request body

{
  "restriction": [
    {
      "field_name": "v_2",
      "field_link": "IN",
      "field_value": "1, 2, 3"
    }
  ]
}

Response body

[ { "code": "10", "count": 1234 } ]

URI Parameters

Name	Type	Required	Description
surveyId	integer	true	The survey ID Examples: `2`.

POST /survey/statistics/{surveyId}/abs/filter

Returns a list of the number/s of participation by disposition code/s and/or split-variable.

POST /survey/statistics/{surveyId}/abs/all and POST /survey/statistics/{surveyId}/abs are similar to this call, but return only a single total value.

Please note, contrary to the RAML and WSDL documentations, the use of splitVariable in criteria is not supported and returns erroneous result. An updated service will be provided shortly.

Request body

{
  "criteria": {
    "dispositionCodes": [
      "31", "32"
    ]
  },
  "restriction": [
    {
      "field_name": "v_2",
      "field_link": "IN",
      "field_value": "1, 2, 3"
    }
  ]
}

Response body

[
  {
    "code": 1,
    "count": 10
  },
  {
    "code": 2,
    "count": 8
  },
  {
    "code": 3,
    "count": 4
  }
]

URI Parameters

Name	Type	Required	Description
surveyId	integer	true	The survey ID Examples: `2`.

POST /survey/statistics/{surveyId}/gross

Returns the total sample (Gross 1) for the project.

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

URI Parameters

Name	Type	Required	Description
surveyId	integer	true	The survey ID Examples: `2`.

POST /survey/statistics/{surveyId}/gross2

Returns the adjusted total sample (Gross 2) for the project.

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

URI Parameters

Name	Type	Required	Description
surveyId	integer	true	The survey ID Examples: `2`.

POST /survey/statistics/{surveyId}/net

Returns the net-participation for the project.

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

URI Parameters

Name	Type	Required	Description
surveyId	integer	true	The survey ID Examples: `2`.

POST /survey/statistics/{surveyId}/disposition/filter

Returns the absolute number of participation for a list of disposition codes, limited by restriction, split by a variable. This service allows use of u_ variables for filtering or splits.

Request body

{
  "criteria": {
    "dispositionCodes":["11","12","22","31","32"],
    "splitVariable":"u_gender"
  },
  "restriction": [
      {
      "field_name": "v_2",
      "field_link": "IN",
      "field_value": "1, 2, 3"
    }
  ]
}

Response body

[
    {
        "value": "-1",
        "total": 19,
        "participation": [
            {
                "code": "11",
                "count": 1
            },
            {
                "code": "12",
                "count": 6
            },
            {
                "code": "22",
                "count": 1
            },
            {
                "code": "31",
                "count": 11
            }
        ]
    },
    {
        "value": "Not available",
        "total": 1,
        "participation": [
            {
                "code": "11",
                "count": 1
            }
        ]
    },
    {
        "value": "-1",
        "total": 1,
        "participation": [
            {
                "code": "31",
                "count": 1
            }
        ]
    }
]

URI Parameters

Name	Type	Required	Description
surveyId	integer	true	The survey ID Examples: `2`.

Surveys

GET /survey/surveys/

Get a list of surveys the user has access to

Response body

[
  {
    "id": 1234,
    "title": "Example title",
    "description": "Example description",
    "marked": true,
    "author": "Example",
    "staff": "",
    "comment": "",
    "isMarked": false,
    "url": "http://example.questback.com/uc/main/1234/",
    "createTime": "2020-07-02T12:53:50+00:00",
    "fieldTime": {
      "startTime": "2020-07-02T12:53:50+00:00",
      "endTime": "2020-08-02T12:53:50+00:00"
    },
    "status": "ACTIVE",
    "type": "ANONYMOUS",
    "numberOfParameters": 0,
    "bonusPoints": {
      "label": "",
      "value": 0
    }
  }
]

POST /survey/surveys/find

Returns a list of surveys the user has access to, based on search criteria. See filtering results with conditions for help on building conditions.

Request body

{
  "logicalCondition": {
    "comparison": {
      "variable": "title",
      "operator": "CONTAINS",
      "value": "Example"
    }
  }
}

Response body

[
  {
    "id": 1234,
    "title": "Example title",
    "description": "Example description",
    "marked": true,
    "author": "Example",
    "staff": "",
    "comment": "",
    "isMarked": false,
    "url": "http://example.questback.com/uc/main/1234/",
    "createTime": "2020-07-02T12:53:50+00:00",
    "fieldTime": {
      "startTime": "2020-07-02T12:53:50+00:00",
      "endTime": "2020-08-02T12:53:50+00:00"
    },
    "status": "ACTIVE",
    "type": "ANONYMOUS",
    "numberOfParameters": 0,
    "bonusPoints": {
      "label": "",
      "value": 0
    }
  }
]

GET /survey/surveys/find/active

Get a list of active surveys the user has access to

Response body

[
  {
    "id": 1234,
    "title": "Example title",
    "description": "Example description",
    "marked": true,
    "author": "Example",
    "staff": "",
    "comment": "",
    "isMarked": false,
    "url": "http://example.questback.com/uc/main/1234/",
    "createTime": "2020-07-02T12:53:50+00:00",
    "fieldTime": {
      "startTime": "2020-07-02T12:53:50+00:00",
      "endTime": "2020-08-02T12:53:50+00:00"
    },
    "status": "ACTIVE",
    "type": "ANONYMOUS",
    "numberOfParameters": 0,
    "bonusPoints": {
      "label": "",
      "value": 0
    }
  }
]

GET /survey/surveys/{surveyId}

Get basic information about a survey

Response body

{
  "id": 1234,
  "title": "Example title",
  "description": "Example description",
  "marked": true,
  "author": "Example",
  "staff": "",
  "comment": "",
  "isMarked": false,
  "url": "http://example.questback.com/uc/main/1234/",
  "createTime": "2020-07-02T12:53:50+00:00",
  "fieldTime": {
    "startTime": "2020-07-02T12:53:50+00:00",
    "endTime": "2020-08-02T12:53:50+00:00"
  },
  "status": "ACTIVE",
  "type": "ANONYMOUS",
  "numberOfParameters": 0,
  "bonusPoints": {
    "label": "",
    "value": 0
  }
}

URI Parameters

Name	Type	Required	Description
surveyId	integer	true	id of survey to delete Examples: `2`.

POST /survey/surveys/

Creates a new survey, returns project id. Valid options for type: ANONYMOUS, PERSONALIZED, ES, LOFT, PANEL, GEN_MASTERDATA, DIARY.

Request body

{
  "surveyData": {
    "title": "Example title",
    "author": "Example",
    "type": "ANONYMOUS",
    "description": "Example description",
    "staff": "",
    "comment": ""
  }
}

Response body

PATCH /survey/surveys/{surveyId}

Change a survey’s field period and status. Valid options for surveyStatus: GENERATED, ACTIVE, CLOSING, FINISHED, ARCHIVED

Request body

{
  "surveyStatus": "ACTIVE",
  "surveyFieldTime": {
    "startTime": "2020-07-02T12:53:50+00:00",
    "endTime": "2020-08-02T12:53:50+00:00"
  }
}

Response body

true

URI Parameters

Name	Type	Required	Description
surveyId	integer	true	id of survey to delete Examples: `2`.

PUT /survey/surveys/{surveyId}

Change a survey’s descriptive data (survey title, survey comment etc.)

Request body

{
  "title": "New Title",
  "description": "Example description",
  "author": "Example author",
  "staff": "Example staff field",
  "comment": "Example comment",
  "isMarked": true
}

URI Parameters

Name	Type	Required	Description
surveyId	integer	true	id of survey to delete Examples: `2`.

DELETE /survey/surveys/{surveyId}

Deletes a survey

Response body

true

URI Parameters

Name	Type	Required	Description
surveyId	integer	true	id of survey to delete Examples: `2`.

PATCH /survey/surveys/{surveyId}/compile

Compiles the survey. Creates all missing variable names and resets the participants if requested. You need the write ACL right to perform this action. Options for surveyCompilationType: keep_results, delete_results, delete_tester.

Request body

{ "surveyCompilationType": "keep_results" }

Response body

true

URI Parameters

Name	Type	Required	Description
surveyId	integer	true	id of survey Examples: `2`.

POST /survey/surveys/{surveyId}/copy

Copies a survey

Request body

{ "title": "Copy of Example" }

Response body

URI Parameters

Name	Type	Required	Description
surveyId	integer	true	id of survey to copy Examples: `2`.

PATCH /survey/surveys/{surveyId}/type

Change the type of a survey. Valid types for surveyType: ANONYMOUS, PERSONALIZED, ES, LOFT, PANEL, GEN_MASTERDATA, DIARY

Request body

{ "surveyType": "ANONYMOUS" }

Response body

true

URI Parameters

Name	Type	Required	Description
surveyId	integer	true	survey to change Examples: `2`.

GET /survey/surveys/{surveyId}/previewlink

Uses the admin session in the url

Response body

"Example"

URI Parameters

Name	Type	Required	Description
surveyId	integer	true	id of survey Examples: `2`.

POST /survey/variables/{surveyId}

Returns description of survey’s variables, machine readable version of the code book. Valid options for surveyVariableTypes: STANDARD, PARTICIPANT, QUESTIONNAIRE, QUESTIONNAIRE_WITH_LOOPS, PARTICIPATION, INTERNAL.

Request body

{ "surveyVariableTypes": [ "STANDARD" ] }

Response body

[
   {
        "varname": "quota_rejected_id",
        "label": "Rejection quota ID of participant",
        "type": "int",
        "typeGroup": "numeric"
    },
    {
        "varname": "language",
        "label": "Language",
        "type": "int",
        "typeGroup": "numeric",
        "categories": [
            {
                "code": 1,
                "label": "English",
                "isMissing": false
            },
            {
                "code": 2,
                "label": "German",
                "isMissing": false
            },
            {
                "code": 3,
                "label": "French",
                "isMissing": false
            }
        ]
    },
    [...]
]

URI Parameters

Name	Type	Required	Description
surveyId	integer	true	survey id Examples: `2`.

POST /survey/surveys/export

Exports survey results according to the given configuration. Please note, that the example is showing all possible options, and is therefore not working. Only surveyId, compression, exportType, exportFileFormat and exportTemplate are required parameters. For full description of export options, see the project export mask in the EFS user interface and the relevant documentation.

The returned data is always base64 encoded and in addition, depending on the gzCompression boolean parameter, the data will be compressed using the zlib format (if true, gzcompress PHP function) or encoded using the gzip format (if false, gzencode PHP function). When handling the returned data, you first need to base64 decode it, then apply the equivalent to PHP’s gzuncompress() or gzdecode() functions for your platform, then you will receive your data in the specified format, which depending on the compression parameter might additionally be compressed.

Please note, that not all exportConfig parameters are supported by all export types, where in doubt, please consult the relevant export user interfaces in EFS Admin area. E.g. for exportType=PARTICIPANT_DATA and exportTemplate=PARTICIPANT, startDate and endDate will be ignored, since they are not available in the export UI of EFS.

Name	Valid options
`compression`	NONE, ZIP, TAR
`protected`	ALL, PROTECTED_ONLY, UNPROTECTED_ONLY
`exportType`	ALL_ANSWERS, RAW_LOOP_DATA, TEXT_ANSWERS, PARTICIPANT_DATA
`exportFileFormat`	CSV, XLS, XLSX, TRIPLE_S, TOP_STUD, XML, HTML, SPSS, SPSS_PORTABLE, SAS, FIXED_FORMAT, QUANTUM
`exportTemplate`	COMPLETE_SURVEY, WITHOUT_TIMESTAMP, TEXT_ONLY, NUMBER_ONLY, PARTICIPANT, PARTICIPANT_RESULT, PARTICIPANT_MASTER_RESULT, LOFT_COMBINED, LOFT_COMBINED_ANONYM
`varNameType`	INTERNAL, EXTERNAL
`quantumTextOption`	NONE, ALL, SURVEY’, ‘INTERNAL

Request body

{
  "exportConfig": {
    "surveyId": 1234,
    "sampleId": 1,
    "languageId": 1,
    "compression": "NONE",
    "skipMissings": true,
    "restrict": "Example",
    "anonymize": true,
    "trimNewlines": true,
    "substituteCode": true,
    "displayMetaInfo": true,
    "shrinkColumnWidth": true,
    "adjustColumnWidth": true,
    "includeSysMissings": true,
    "consecutiveNrFrom": 0,
    "consecutiveNrTo": 0,
    "protected": "ALL",
    "dispositionCodeList": [
      "31"
    ],
    "exportType": "ALL_ANSWERS",
    "exportFileFormat": "CSV",
    "exportTemplate": "COMPLETE_SURVEY",
    "charset": "UTF-8",
    "missingValueText": "-66",
    "missingValueTextEmpty": "-",
    "missingValueNumeric": "-77",
    "missingValueTimestamp": "0",
    "missingValueDatetime": "0000-00-00 00:00:00",
    "startDate": "2020-07-02T12:53:50+00:00",
    "endDate": "2020-07-02T12:53:50+00:00",
    "varNameType": "INTERNAL",
    "quantumTextOption": "NONE",
    "panelGroup": 1,
    "panelistStatusList": [
      1
    ],
    "gzCompression": true,
    "modifiedOnly": true,
    "trackModification": true,
    "varNameRestriction": [
      "v_1", "v_2"
    ],
    "skipLoopVars": true,
    "cutPsppColumns": true,
    "useCommaDelimiter": true
  }
}

Response body

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

Name	Type	Required	Description
surveyId	integer	true	Id of a survey Examples: `2`.

PUT /survey/timelog/{surveyId}

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

Response body

true

URI Parameters

Name	Type	Required	Description
surveyId	integer	true	Id of a survey Examples: `2`.

Translations

GET /survey/translations/{surveyId}/{languageId}

Gets a list of all translations for the specified language

Response body

[
    {
        "typeId": 0,
        "textType": "msg_title",
        "text": "Survey"
    },
    [...]
    {
        "typeId": 0,
        "textType": "msg_submit",
        "text": "Continue"
    },
    [...]
    {
        "typeId": 1380,
        "textType": "q_instruct",
        "text": "Here you explain how the question has to be filled in (optional)."
    },
    [...]
]

URI Parameters

Name	Type	Required	Description
surveyId	integer	true	surveyId Examples: `2`.
languageId	integer	true	languageId Examples: `2`.

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

Changes a translation

Request body

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

Response body

true

URI Parameters

Name	Type	Required	Description
surveyId	integer	true	surveyId Examples: `2`.
languageId	integer	true	languageId Examples: `2`.

FAQ

How do I authenticate my requests to the EFS Service-Layer?

You can authenticate your requests by including a token URL parameter in your API calls. Alternatively, you can use basic authentication as specified in the HTTP protocol.

What do the different HTTP status codes mean in the EFS Service-Layer?

The EFS Service-Layer uses standard HTTP status codes to indicate the success or failure of requests. For example, 200 indicates a successful request, while 400, 401, 403, and 500 indicate various types of errors or permission issues.

How can I manage the email blocklist?

You can use the email blocklist services to add, remove, or retrieve blocked email addresses. These can be managed globally or for specific surveys using the appropriate API endpoints.

How do I add participants to a survey?

You can add participants to a survey using the POST /panel/participants/v2/{sampleId} endpoint. This allows you to add multiple participants to a survey sample in a single request.

How do I create a new survey?

To create a new survey, use the POST /survey/surveys/ endpoint. This will create a new survey and return the project ID, which you can use for further operations on that survey.