This page contains examples for the most common use cases.
Read members of a panel or sample
The simplest case is to read the whole sample at one. This works up to 10k members, afterwards paging is required. For filtering and paging see Filtering & Paging
POST /publicapi/Panel/v3/ReadMemberList
Content-Type: application/json
{
"tenant": "{tenant}",
"panelId": {panel id}
}Response:
{
"members": [
{
"id": 5,
"fields": {
"Email": {
"name": "Email",
"fieldType": "String",
"value": "max.musterman@company.com"
},
"FirstName": {
"name": "FirstName",
"fieldType": "String",
"value": "Max"
},
"LastName": {
"name": "LastName",
"fieldType": "String",
"value": "Musterman"
},
"Language": {
"name": "Language",
"fieldType": "String",
"value": "en"
},
"Gender": {
"name": "Gender",
"fieldType": "Number",
"value": null
},
"CellPhoneNumber": {
"name": "CellPhoneNumber",
"fieldType": "Number",
"value": null
}
},
"createdAt": "2020-12-18T12:09:18.64Z",
"createdBy": "...",
"updatedAt": null,
"updatedBy": null,
"interviews": []
}
],
"totalCount": 0,
"isSuccess": true,
"errorMessage": null,
"errorCode": null
}If only a few fields of the sample / panel are needed, the performance can dramatically being improved by specifying which fields shall be returned. Especially if it is a broad sample / panel with a lot of fields.
{
"tenant": "{tenant}",
"panelId": {panel id},
"fieldsToDownload": [
"Email","FirstName","LastName"
]
}With the members, also the members interviews can be retrieved.
{
"tenant": "{tenant}",
"panelId": {panel id},
"interviewsRequired": true,
}Response:
{
"members": [
{
...
"interviews": [
{
"id": "445446ce-2ae0-4b50-871a-1728718a4380",
"state": "NotResponded",
"surveyId": 12345,
"surveyVersionId": 3,
"surveyName": "My Example",
"surveyState": "Published",
"answersLink": "https://...",
"interviewLink": "https://...",
"startDate": null,
"endDate": null,
"samplingProjectId": 1234,
"distributorId": 1234
}
]
}
],
"totalCount": 0,
"isSuccess": true,
"errorMessage": null,
"errorCode": null
}The interviews contain all information to create relations or download the PDF.
Never hotlink the survey- or PDF-link in 3rd party systems. The links are not permanent. If the survey is deleted links are gone. Especially PDFs shall be downloaded and the document being stored in the 3rd party system. By hotlinking it’s not guaranteed that the links stop working from one day to another without notification.
Add members to an existing panel or sample
Members can be created one by one or in a batch providing more objects in the array.
POST /publicapi/Panel/v3/CreateMembers
Content-Type: application/json
{
"tenant": "{tenant}",
"panelId": {panel id},
"members": [{
"fields": {
"Email": {
"name": "Email",
"fieldType": "String",
"value": "max.musterman@company.com"
},
"FirstName": {
"name": "FirstName",
"fieldType": "String",
"value": "Max"
},
"LastName": {
"name": "LastName",
"fieldType": "String",
"value": "Musterman"
},
"Language": {
"name": "Language",
"fieldType": "String",
"value": "en"
}
}
}
]
}
Response:
{
"membersIds": [
7
],
"validationIssues": [],
"isSuccess": true,
"errorMessage": null,
"errorCode": null
}The member IDs which are returned have the same order than the sent members in the member array of the request. All members which are not created are mentioned in the validationIssues. Please be aware that the same validation rules like the email validation as in the UI will be applied.
Invite existing members to a survey
Members of an existing panel or sample can be invited.
POST /publicapi/Distribute/v3/InviteMembers
Content-Type: application/json
{
"surveyId": {survey id},
"panelId": {panel or sample id},
"messageTemplateId": {message id},
"channel": "Email",
"asyncProcess": true
}Response:
{
"samplingProjectId": 45,
"distributorId": 18,
"isSuccess": true,
"errorMessage": null,
"errorCode": null
}Advanced Example:
Additionally the participants of the panel or sample can be filtered using the conditions property. Also the invitation message can be customized using the textBlocks property. The following example is more sophisticated and combines the approaches to invite a partial sample, with a customized message and schedule the invitation to the 01.01.2025 00:00 UTC.
{
"surveyId": 10206,
"panelId": 353,
"messageTemplateId": 1199,
"textBlocks": [
{
"name": "7a5e9abb-3d8e-31ac-8f21-1a763b09a299",
"type": "editarea",
"text": [
{
"languageCode": "en",
"text": "My customizable Text"
}
]
}
],
"scheduleDateTime": "2025-01-01T00:00:00.000Z",
"conditions": [
{
"conjunction": "And",
"conditionType": "Panel",
"identifier": "Division",
"conditionOperator": "IsEqualTo",
"value": "HR"
}
],
"channel": "Email",
"asyncProcess": true
}The Guid from the text block needs to be taken from the message layout.
Invite new members to a survey
This is a convenience method and combines the CreateMembers with the InviteMembers function.
POST /publicapi/Distribute/v3/CreateAndInviteMembers
Content-Type: application/json
{
"surveyId": {survey id},
"panelId": {panel or sample id},
"messageTemplateId": {message id},
"channel": "Email",
"asyncProcess": true,
"members": [{
"fields": {
"Email": {
"name": "Email",
"fieldType": "String",
"value": "max.musterman@company.com"
},
"FirstName": {
"name": "FirstName",
"fieldType": "String",
"value": "Max"
},
"LastName": {
"name": "LastName",
"fieldType": "String",
"value": "Musterman"
},
"Language": {
"name": "Language",
"fieldType": "String",
"value": "en"
}
}
}
]
}Response:
{
"samplingProjectId": 45,
"distributorId": 18,
"validationIssues": [],
"isSuccess": true,
"errorMessage": null,
"errorCode": null
}Download interviews
Survalyzer offers two possibilities to download interviews for the following scenarios:
ReadSurveyData:
- In Web Application Firewall (WAF) scenarios
- If data is processed from a contract based system (Exporter)
ReadSurveyDataCompact:
- In BI Tools like PowerBI or QlikView
- In JavaScript Portals or Dashboards
The request interface is identical only the response differs to satisfy the different use cases.
POST /publicapi/Interview/v3/ReadInterviewList(Compact)
Content-Type: application/json
{
"surveyId": {survey id},
"fieldsToDownload": ["q1"],
"loadCodePlan": true|false
}
Response ReadInterviewList:
{
"surveyName": "Test",
"surveyDefaultLanguage": "en",
"surveyLanguages": [
"en"
],
"interviews": [
{
"columns": [
{
"id": "q1",
"value": 2
}
]
},
{
"columns": [
{
"id": "q1",
"value": 2
}
]
}
],
"codePlan": [...],
"totalCount": 0,
"isSuccess": true,
"errorMessage": null,
"errorCode": null
}Response ReadInterviewListCompact:
{
"surveyName": "Test",
"surveyDefaultLanguage": "en",
"surveyLanguages": [
"en"
],
"interviews": [
{
"q1": 2
},
{
"q1": 2
}
],
"codePlan": [...],
"totalCount": 0,
"isSuccess": true,
"errorMessage": null,
"errorCode": null
}Both formats have their advantages, while the ReadInterviewList is structured if a contract based approach is needed, the ReadInterviewListCompact is unstructured and more suitable for JavaScript processing.
For both formats is important to only read what is really required. For recuring jobs for example the code plan is normally not required and shouldn’t be requested. Also most of the fields are not required. Therefore, always use fieldsToDownload to only get what you really need.
For filtering and paging see the reference here.