| GET | 3/surveys/{surveyid}/questions |
| POST | 3/surveys/{surveyid}/respondents |
Build the survey interface in your own application (web, mobile, desktop) and send us the responses. The question type, list of responses and configured validation limit the possibilities of data which will be accepted by our system. When retrieving the question, you will get this information. We recommend to build the required validation client site and show clear information to your users. We also perform the validations on our end and return the related result code in our response.
From the moment we have at least one correct response, we will register the respondent. Our response contains a Data.Succeeded property which you can use to check if the respondent was created. The Data.Results.HasErrors property can be used to check the validation of the responses.
To avoid a request for each question separately, you can pass all responses with one request. You can't add responses for a respondent later on, you should gather all data and send them to our system with only one call.
First retrieve all questions for your survey to be sure you got the correct question id's and options. You can retrieve this data for each page using the filter, in below example we are requesting the questions for the first page of your survey.
curl -X "https://api-eu.agileresearch.medallia.com/3/surveys/{SurveyId}/questions?filter=PageNumber%20eq%201"
-H "X-Master-Key: {MasterKey}"
-H "X-Key: {Key}"
-H "Content-type: application/json"
System.Net.Http.HttpClient client = new System.Net.Http.HttpClient();
client.BaseAddress = new Uri("https://api-eu.agileresearch.medallia.com/");
client.DefaultRequestHeaders.Add("X-Master-Key", "{MasterKey}");
client.DefaultRequestHeaders.Add("X-Key", "{Key}");
client.DefaultRequestHeaders.Add("Content-type", "application/json");
System.Net.Http.HttpResponseMessage response = client.GetAsync($"3/surveys/{SurveyId}/questions?filter=pageNumber%20eq%201").Result;
Create a new respondent and the response for the single question in this survey. In the example we are passing the required parameters LanguageCode and RespondentStatusId. You can find a list of all supported options in the Full API Reference. In below example the respondent picked the first response option for the question. This statement can be used for most question types.
curl -X POST "https://api-eu.agileresearch.medallia.com/3/surveys/{SurveyId}/respondents"
-H "X-Master-Key: {MasterKey}"
-H "X-Key: {Key}"
-H "Content-type: application/json"
-d "{'LanguageCode': 'en', 'RespondentStatusId': 0, 'Preview': false, 'QuestionResponses': { 'QuestionId': 1, 'Responses': [{'ResponseId':1}]}}"
{
"Meta": {
"Status": 200,
"Timestamp": "2024-04-16T04:23:00.8505129Z",
},
"Data": {
"RespondentId": 1,
"Succeeded": true
}
}
System.Net.Http.HttpClient client = new System.Net.Http.HttpClient();
client.BaseAddress = new Uri("https://api-eu.agileresearch.medallia.com/");
client.DefaultRequestHeaders.Add("X-Master-Key", "{MasterKey}");
client.DefaultRequestHeaders.Add("X-Key", "{Key}");
client.DefaultRequestHeaders.Add("Content-type", "application/json");
string requestUri = $"3/surveys/{SurveyId}/respondents";
var newRespondent = new NewRespondent()
{
LanguageCode = "en",
RespondentStatusId = 0,
Preview = false
QuestionResponses = new NewQuestionResponse[] {
new NewQuestionResponse {
QuestionId = 1,
Responses = new NewResponse[] {
new NewResponse { ResponseId = 2 }
}
}
}
};
System.Net.Http.HttpResponseMessage response = client.PostAsJsonAsync(requestUri, jsonObject).Result;
{
"Meta": {
"Status": 200,
"Timestamp": "2024-04-16T04:23:00.8505129Z",
},
"Data": {
"RespondentId": 1,
"Succeeded": true
}
}
The following example will show how to add a list of responses to multiple questions for the new respondent. Below you can see an example for the special question types.
Register the responses for an open answer: a list of 2 textboxes in which we ask for the Firstname and the Lastname. When you are using a single textbox, you should only pass a value for ResponseId 1.
{ 'QuestionId': 1, 'Responses': [{'ResponseId':1, 'Value': 'John'}, {'ResponseId':2, 'Value':'Doe'}]}
new QuestionResponse{
QuestionId = 1,
Responses = new NewResponse[]{
new NewResponse {ResponseId = 1, Value = 'John'}
},{
new NewResponse {ResponseId = 2, Value = 'Doe'}
}
}
Now we would like to register responses for a multiselect question of 8 options for which the last option is the other option. We would like to respond with option 2 and the other option with the value My other response.
{ 'QuestionId': 2, 'Responses': [{'ResponseId':2 },{'ResponseId':8, 'Value': 'My other response'}]}
new QuestionResponse{
QuestionId = 2,
Responses = new NewResponse[]{
new NewResponse {ResponseId = 2}
},{
new NewResponse {ResponseId = 8, Value = "My other response"}
}
}
When using a rank order scale, slider or constant sum, you should not use the Value property since this is only valid for open responses. For these specific questions, we use the PointValue to indicate the position (in a rank order scale or slider) or the entered number for a constant sum. In below example we have a rank order scale question with at least 8 possible responses for which we want a top 3. Our respondent has the following order: option 1, option 5 and option 8.
{ 'QuestionId': 3, 'Responses': [{'ResponseId':1, 'PointValue': 1},{'ResponseId':5, 'PointValue': 2},{'ResponseId':8, 'PointValue':3}]}
new QuestionResponse{
QuestionId = 3,
Responses = new NewResponse[]{
new NewResponse {ResponseId = 1, PointValue = 1}
},{
new NewResponse {ResponseId = 5, PointValue = 2}
},{
new NewResponse {ResponseId = 8, PointValue = 3}
}
}
Now we know the answers and are ready to send them. Since the survey is final, we will mark the respondent as completed and pass the elapsed time.
curl -X POST "https://api-eu.agileresearch.medallia.com/3/surveys/{SurveyId}/respondents"
-H "X-Master-Key: {MasterKey}"
-H "X-Key: {Key}"
-H "Content-type: application/json"
-d "{'LanguageCode': 'en', 'RespondentStatusId': 1, 'ElapsedTime' : 150, 'QuestionResponses': [{ 'QuestionId': 1, 'Responses': [{'ResponseId':1, 'Value': 'John'}, {'ResponseId':2, 'Value':'Doe'}]},{ 'QuestionId': 2, 'Responses': [{'ResponseId':2 },{'ResponseId':8, 'Value': 'My other response'}]},{ 'QuestionId': 3, 'Responses': [{'ResponseId':1, 'PointValue': 1},{'ResponseId':5, 'PointValue': 2},{'ResponseId':8, 'PointValue':3}]}]}"
System.Net.Http.HttpClient client = new System.Net.Http.HttpClient();
client.BaseAddress = new Uri("https://api-eu.agileresearch.medallia.com/");
client.DefaultRequestHeaders.Add("X-Master-Key", "{MasterKey}");
client.DefaultRequestHeaders.Add("X-Key", "{Key}");
client.DefaultRequestHeaders.Add("Content-type", "application/json");
string requestUri = $"3/surveys/{SurveyId}/respondents";
var newRespondent = new NewRespondent()
{
RespondentStatusId = 1,
ElapsedTime = 150
QuestionResponses = new NewQuestionResponse[]{
new QuestionResponse{
QuestionId = 1,
Responses = new NewResponse[]{
new NewResponse {ResponseId = 1, Value = 'John'}
},{
new NewResponse {ResponseId = 2, Value = 'Doe'}
}
}, new QuestionResponse{
QuestionId = 2,
Responses = new NewResponse[]{
new NewResponse {ResponseId = 2}
},{
new NewResponse {ResponseId = 8, Value = "My other response"}
}
}, new QuestionResponse{
QuestionId = 3,
Responses = new NewResponse[]{
new NewResponse {ResponseId = 1, PointValue = 1}
},{
new NewResponse {ResponseId = 5, PointValue = 2}
},{
new NewResponse {ResponseId = 8, PointValue = 3}
}
}
}
}
System.Net.Http.HttpResponseMessage response = client.PostAsJsonAsync(requestUri, jsonObject).Result;
We have used the following methods in this example. You can find all details regarding each request in the API Reference.
| GET | 3/surveys/{surveyid}/questions |
| POST | 3/surveys/{surveyid}/respondents |