| POST | 3/contacts/import/config |
| POST | 3/contacts/import/{ImportConfigId} |
| GET | 3/contacts/import/{QueueItemId} |
This example will show you the possibilities when adding contacts in bulk. With the import request, you can add thousands of contacts in one call. Unlike adding contacts, this call is handled asynchronously.
Only 4 steps are required to get your data into our system:
With the import configuration, you define how the contacts will be added. An import configuration is created once and reused across different imports.
Since the import configuration is the main component when importing contacts in bulk, there are Create/Read/Update/Delete requests for it. The import configurations are shared between the API and the Tool, use a consistent and descriptive name so that it is obvious where and how your data will be imported.
An import configuration is a required parameter when adding contacts in bulk. You can find all the options of the import configuration in the API reference
In the example below we will use the most common ones.
curl -X POST "https://api-eu.agileresearch.medallia.com/3/contacts/import/configs"
-H "X-Master-Key: {MasterKey}"
-H "X-Key: {Key}"
-H "Content-type: application/json"
-d "{'Name': 'My import settings', 'SurveySettings': {'SurveyId': {SurveyId}, 'InvitationDelayInDays': 2, 'ExpirationAfterDays': 14}, 'EmailIsRequired': true, 'UpdateTypeId': 1, 'SendNotificationMail': true, 'IsReusable': true, 'DefaultLanguageCode': 'en'}"
{"Meta":{"Status":200,"Timestamp":"2024-04-20T10:04:20.3238366Z"},"Data":{"ImportConfigId":290,"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/contacts/import/configs";
var jsonObject = new
{
Name = "My import settings",
SurveySettings = new { SurveyId = {SurveyId}, InvitationDelayInDays = 2, ExpirationAfterDays = 14 },
EmailIsRequired = true,
UpdateTypeId = 1,
SendNotificationMail = true,
IsReusable = true,
DefaultLanguageCode = "en"
};
System.Net.Http.HttpResponseMessage response = client.PostAsJsonAsync(requestUri, jsonObject).Result;
{"Meta":{"Status":200,"Timestamp":"2024-04-20T10:04:20.3238366Z"},"Data":{"ImportConfigId":290,"Succeeded":true}}
var Swagger = require('swagger-client');
var client = new Swagger({
url: 'https://api-eu.agileresearch.medallia.com/docs/api/v3/swagger',
authorizations: {
"MasterKey": new Swagger.ApiKeyAuthorization("X-Master-Key", "{MasterKey}", "header"),
"ApiKey": new Swagger.ApiKeyAuthorization("X-Key", "{Key}", "header")
},
success: function () {
client.Contacts.Contacts_AddImportConfig({
ImportConfig: {
Name: "My import settings",
SurveySettings: {
SurveyId: {SurveyId},
InvitationDelayInDays: 2,
ExpirationAfterDays: 14
},
EmailIsRequired: true,
UpdateTypeId: 1,
SendNotificationMail: true,
IsReusable: true,
DefaultLanguage: "en"
}
}, function (response) {
var importConfigResult = JSON.parse(response.data).Data;
console.log('New import config with ID: ' + importConfigResult.ImportConfigId);
});
}
});
New import config with ID: 290
This property should be used if you would like to add your imported contacts immediately to a existing survey. You can specify
SurveyId to which the contacts will be added.InvitationDelayInDays is relevant if the invitations are send using CheckMarket email channel or SMS, you can specifiy how many days after your import the invitations will be send.InvitationTime to configure when the invitations will be send. ExpirationAfterDays allows you to define how much time your contacts get to respond to your request.This property defines how to handle existing contacts.
When activated, we will send you a e-mail notification after every import. In this mail, you will get an quick overview of the import result
Once your import configuration is ready, importing contacts gets easy! Only one parameters is required to send your contacts to our API.
After receiving your request, we will read, clean, validate and import your contacts asynchronously. We provide a QueueItemId which you can use to follow the progress. Here is an example of how you can start importing.
curl -X POST "https://api-eu.agileresearch.medallia.com/3/contacts/import/{ImportConfigId}"
-H "X-Master-Key: {MasterKey}"
-H "X-Key: {Key}"
-H "Content-type: application/json"
-d "[{'FirstName':'John','LastName':'Doe','Email':'john.doe@mail.com','LangCode':'en'},
{'FirstName':'Jane','LastName':'Doe','Email':'jane.doe@mail.com','LangCode':'en'}]"
{"Meta":{"Status":200,"Timestamp":"2024-04-20T10:04:20.3268382Z"},"Data":{"QueueItemId":152776}}
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/contacts/import/{ImportConfigId}";
var jsonObject = new [] {
new { FirstName = "John", LastName = "Doe", Email = "john.doe@mail.com", LangCode = "en"},
new { FirstName = "Jane", LastName = "Doe", Email = "jane.doe@mail.com", LangCode = "en"}
};
System.Net.Http.HttpResponseMessage response = client.PostAsJsonAsync(requestUri, jsonObject).Result;
{"Meta":{"Status":200,"Timestamp":"2024-04-20T10:04:20.3268382Z"},"Data":{"QueueItemId":152776}}
var Swagger = require('swagger-client');
var client = new Swagger({
url: 'https://api-eu.agileresearch.medallia.com/docs/api/v3/swagger',
authorizations: {
"MasterKey": new Swagger.ApiKeyAuthorization("X-Master-Key", "{MasterKey}", "header"),
"ApiKey": new Swagger.ApiKeyAuthorization("X-Key", "{Key}", "header")
},
success: function () {
client.Contacts.Contacts_ImportContacts({
ImportConfigId: {ImportConfigId},
Contacts: [{
FirstName : "John",
LastName : "Doe",
Email: 'john.doe@mail.com',
LangCode: 'en'
},
{
FirstName : "Jane",
LastName : "Doe",
Email: 'jane.doe@mail.com',
LangCode: 'en'
}]
}, function (result) {
var importResult = JSON.parse(result.data).Data;
console.log('Import started (PQ ' + importResult.QueueItemId + ')');
});
}
});
Import started (PQ 152776)
Don't send and forget, stay in the loop! Track how your import is being handled. With the queueitemid you can request the status (Queued, Started, Complete or Failed) of your import. Once Started, we will show you the progress. Once Complete, we give you the result and if activated, send you an e-mail notification.
curl -X "https://api-eu.agileresearch.medallia.com/3/contacts/import/{QueueItemId}"
-H "X-Master-Key: {MasterKey}"
-H "X-Key: {Key}"
-H "Content-type: application/json"
{"Meta":{"Status":200,"Timestamp":"2024-04-20T10:04:20.3268382Z"},"Data":{"QueueItemId":152776,"StatusId":2,"DateQueued":"2024-04-20T10:04:20.3268382Z","DateStarted":"2024-04-20T10:04:20.3268382Z","ProgressPercent":25,"ProgressText":"Importing data"}}
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(string.Format("3/contacts/import/{0}", "{QueueItemId}")).Result;
{"Meta":{"Status":200,"Timestamp":"2024-04-20T10:04:20.3268382Z"},"Data":{"QueueItemId":152776,"StatusId":2,"DateQueued":"2024-04-20T10:04:20.3268382Z","DateStarted":"2024-04-20T10:04:20.3268382Z","ProgressPercent":25,"ProgressText":"Importing data"}}
var Swagger = require('swagger-client');
var client = new Swagger({
url: 'https://api-eu.agileresearch.medallia.com/docs/api/v3/swagger',
authorizations: {
"MasterKey": new Swagger.ApiKeyAuthorization("X-Master-Key", "{MasterKey}", "header"),
"ApiKey": new Swagger.ApiKeyAuthorization("X-Key", "{Key}", "header")
},
success: function () {
(function loop() {
client.Contacts.Contacts_ImportResult({ QueueItemId: {QueueItemId} }, function (qResult) {
var queueResult = JSON.parse(qResult.data).Data;
if (queueResult.StatusId == 4) {
console.log('Import completed with results: ');
for (var i = 0; i < queueResult.Result.ImportResult.length; i++) {
console.log('Status ' + queueResult.Result.ImportResult[i].ResultCode + ': ' + queueResult.Result.ImportResult[i].ContactCount + ' contacts');
};
} else {
setTimeout(loop, 2000);
}
});
}());
}
});
Import started (PQ 152776) Import completed with results: Status R0301: 2 contacts
Once your import is Complete, the same request will return the details regarding your import:
ImportResult gives an global overview of the different ResultCode's with the amount of contacts. The resultcode will give you a clear description of what's wrong.ResultUrl. This url is only valid for 7-days and should be used by the application. For end users, you can use the excel file which is available on XlsxAnswerFileUrl, but this url requires an active user in our Tool.curl -X "https://api-eu.agileresearch.medallia.com/3/contacts/import/{QueueItemId}"
-H "X-Master-Key: {MasterKey}"
-H "X-Key: {Key}"
-H "Content-type: application/json"
{"Meta":{"Status":200,"Timestamp":"%%%N%%%"},"Data":{"Result":{"ImportResult":[{"ResultCode":"R0301","ContactCount":1}],"XlsxAnswerFileUrl":"{ToolUrl}",},"QueueItemId":152776,"StatusId":4,"DateQueued":"2024-04-20T10:04:20.3268382Z","DateStarted":"2024-04-20T10:04:20.3268382Z","DateComplete":"2024-04-20T10:04:20.3268382Z","ProgressPercent":100,"ProgressText":"Completed","ResultUrl":"{7DaysValidUrl}"}}
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(string.Format("3/contacts/import/{0}", "{QueueItemId}")).Result;
{"Meta":{"Status":200,"Timestamp":"%%%N%%%"},"Data":{"Result":{"ImportResult":[{"ResultCode":"R0301","ContactCount":1}],"XlsxAnswerFileUrl":"{ToolUrl}",},"QueueItemId":152776,"StatusId":4,"DateQueued":"2024-04-20T10:04:20.3268382Z","DateStarted":"2024-04-20T10:04:20.3268382Z","DateComplete":"2024-04-20T10:04:20.3268382Z","ProgressPercent":100,"ProgressText":"Completed","ResultUrl":"{7DaysValidUrl}"}}
var Swagger = require('swagger-client');
var client = new Swagger({
url: 'https://api-eu.agileresearch.medallia.com/docs/api/v3/swagger',
authorizations: {
"MasterKey": new Swagger.ApiKeyAuthorization("X-Master-Key", "{MasterKey}", "header"),
"ApiKey": new Swagger.ApiKeyAuthorization("X-Key", "{Key}", "header")
},
success: function () {
(function loop() {
client.Contacts.Contacts_ImportResult({ QueueItemId: {QueueItemId} }, function (qResult) {
var queueResult = JSON.parse(qResult.data).Data;
if (queueResult.StatusId == 4) {
console.log('Import completed with results: ');
for (var i = 0; i < queueResult.Result.ImportResult.length; i++) {
console.log('Status ' + queueResult.Result.ImportResult[i].ResultCode + ': ' + queueResult.Result.ImportResult[i].ContactCount + ' contacts');
};
} else {
setTimeout(loop, 2000);
}
});
}());
}
});
Import started (PQ 152776) Import completed with results: Status R0301: 2 contacts
We have used the following methods in this example. You can find all details regarding each request in the API Reference.
| POST | 3/contacts/import/config |
| POST | 3/contacts/import/{ImportConfigId} |
| GET | 3/contacts/import/{QueueItemId} |