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.
Validation & Error codes
Validation Codes
VAL10000: Survey is required
VAL10001: Sample name is required
VAL10002: Country must be specified
VAL10003: Interview length must be a positive integer number
VAL10004: Incidence rate must be a positive integer number, at maximum 100
VAL10005: Field Period in days should be between 1 and 1000
VAL10006: Panel is required
VAL10007: Message template is required
VAL10008: Invitation e-mail message template is not available
VAL10009: Sample size should be a positive integer number
VAL10010: Survey is not valid
VAL10011: End date and time cannot be “older” than start date and time
VAL10012: Field period is required
VAL10013: The field phase must be at least 5 days
VAL10014: The field period start time shall be in the future
VAL10015: Invalid e-mail address
VAL10016: Invalid cell phone number
VAL10017: Distributor channel is required
VAL10018: Member code should be unique across the workspace
VAL10019: Path of custom link invalid
VAL10020: Account domain invalid
VAL10021: Account domain and custom path cannot be joined
VAL10022: Maximum length of URL path part is {maxLength} characters
VAL10023: Path part cannot contain such character ‘{char}’
VAL10024: Maximum length of query part of URL is {maxLength} characters
VAL10025: Query part cannot contain such character ‘{char}’
VAL10026: Link is already in use for survey id {surveyId}, survey name ‘{surveyName}’.
VAL10027: No such language ‘{language}’ in the survey.
VAL10028: Language parameter ‘l={wrong}’ incorrect, only ‘l={correct}’ is valid.
VAL10029: This username already in use.
VAL10030: 8888888 and 9999999 are reserved values and cannot be chosen as regular values.
VAL10031: Member e-mail should be unique across panel
VAL10032: The password does not meet the password policy, since it was used before
VAL10033: The password reset code has been expired.
VAL10034: Feasibility Check expired. You need to redo the feasibility check.
VAL10035: The quota groups are inconsistent, please correct them.
VAL10036: Field phase end date cannot be later than survey end date.
VAL10037: Attribute configuration not allowed for Dynata: {message}
VAL10038: Language code is valid
VAL10039: Gender variable value is not valid
Error Codes
SUR10000: The URL is not valid
SUR10001: Unknown survey
SUR10002: The survey has already ended
SUR10003: Unknown distributor
SUR10004: Unknown message template
SUR10005: Unknown panel
SUR10006: No panel is attached
SUR10007: Invalid username or password
SUR10008: Panel member is required
SUR10009: The panel member does not belong to the interview
SUR10010: Invalid token code
SUR10011: No suitable interview found
SUR10012: Trial users are not allowed to use file manager
SUR10013: Unknown survey link
SUR10014: PSID or MED is empty
SUR10015: Unknown authentication type
SUR10016: Element not found
SUR10017: Duplicated element
SUR10018: Element ID = 0
SUR10019: Survey is published. Update with breaking changes is restricted.
SUR10020: Unknown field phase start or end date
SUR10021: Operation is not allowed at this location
SUR10022: File extension is not allowed
SUR10023: Cannot read user ID
SUR10024: Cannot read user panel ID
SUR10025: Reached limit of 20 sampling projects for survey
SUR10026: Unknown sampling project
SUR10027: Unknown reminder
SUR10028: Unknown e-mail body
SUR10029: Unknown e-mail subject
SUR10030: Unknown account
SUR10031: Unknown incentive
SUR10032: Unknown user profile
SUR10033: Code required
SUR10034: User name and password required
SUR10035: Token code should be unique across the workspace
SUR10036: Unknown report
SUR10037: Unknown color template
SUR10038: Unknown survey layout
SUR10039: Unknown workspace group
SUR10040: Unknown opt-out
SUR10041: You cannot remove default message template
SUR10042: Unknown subscription
SUR10043: Unknown subscription item
SUR10044: Unknown workspace
SUR10045: You cannot remove default message layout
SUR10046: Member is not unique
SUR10047: Unknown panel member
SUR10048: Unfortunately, an error occurred, please try again or create a support ticket
SUR10049: Unknown voucher code
SUR10050: Interviews can only be reset if no active interview is in place
SUR10051: You cannot remove the default layout.
SUR10052: Template is not valid
SUR10053: Member e-mail address should be unique across panel
SUR10054: There are no transitions for this state
SUR10055: Workspace name should be unique
SUR10056: Opt-out already exists
SUR10057: No suitable sampling project is available
SUR10058: System workspace group could not be deleted
SUR10059: System workspace could not be deleted
SUR10060: System workspace could not be renamed or moved
SUR10061: System workspace group could not be renamed or moved
SUR10062: Personal interview is deleted
SUR10063: The reset password link is already expired
SUR10064: The product to upgrade does not exist
SUR10065: The new product does not exist
SUR10066: Another subscription exists in the time span
SUR10067: Subscription for this product already exists
SUR10068: The sampling project is not in draft mode. The update is restricted.
SUR10069: Dynata Sampling Project creation failed.
SUR10070: Can not read Dynata project.
SUR10071: Update Dynata project failed.
SUR10072: Read countries list from Dynata failed.
SUR10073: Read topics list from Dynata failed.
SUR10074: Read attribute list from Dynata failed.
SUR10075: Dynata Sampling Project feasibility check failed.
SUR10076: Can not buy Dynata project.
SUR10077: Can not close Dynata project.
SUR10078: Update LineItem state failed.
SUR10079: Can not read Dynata project report.
SUR10080: Dynata Access Token could not be renewed
SUR10081: Unknown question catalog
SUR10082: Subscription expired.
SUR10083: Unknown dashboard layout
SUR10084: Not enough user licenses available
SUR10085: You cannot remove default dashboard layout
SUR10086: The payment was not successful
SUR10087: The product was not found
SUR10088: You cannot modify or remove system color template
SUR10089: Gender variable value is not valid
SUR10090: Language code is not valid
SUR10091: E-mail address is not valid
SUR10092: Cell phone number is not valid