Add a new contact to a survey

This example will show you the possibilities to add a new contact. This contact will immediately be added to a survey. We will return a ContactCreateResult which indicates if the request was successful and the contact id or failure message. With the contact id you can retrieve the panelist information.

You can find an overview of all available properties for a new contact.

Request

curl -X POST "https://api-us.agileresearch.medallia.com/3/contacts?SurveyId={SurveyId}" 
-H "X-Master-Key: {MasterKey}" 
-H "X-Key: {Key}" 
-H "Content-type: application/json" 

-d "{'FirstName': 'John', 'LastName': 'Doe', 'Email': 'john.doe@mail.com'}"

curl -X POST "https://api-us.agileresearch.medallia.com/3/contacts?SurveyId={SurveyId}" 
-H "X-Master-Key: {MasterKey}" 
-H "X-Key: {Key}" 
-H "Content-type: application/json" 

-d "{'FirstName': 'John', 'LastName': 'Doe', 'Email': 'john.doe@mail.com'}"

Response

{"Meta":{"Status":200,"Timestamp":"2024-11-23T12:23:12.5570861Z"},"Data":{"Succeeded":true,"ContactId":20921043}}

Request

System.Net.Http.HttpClient client = new System.Net.Http.HttpClient();
client.BaseAddress = new Uri("https://api-us.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 = string.Format("3/contacts?SurveyId={0}", "{SurveyId}");
var jsonObject = new { FirstName = "John", LastName = "Doe", Email = "john.doe@mail.com" };

System.Net.Http.HttpResponseMessage response = client.PostAsJsonAsync(requestUri, jsonObject).Result;

System.Net.Http.HttpClient client = new System.Net.Http.HttpClient();
client.BaseAddress = new Uri("https://api-us.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 = string.Format("3/contacts?SurveyId={0}", "{SurveyId}");
var jsonObject = new { FirstName = "John", LastName = "Doe", Email = "john.doe@mail.com" };

System.Net.Http.HttpResponseMessage response = client.PostAsJsonAsync(requestUri, jsonObject).Result;

Response

{"Meta":{"Status":200,"Timestamp":"2024-11-23T12:23:12.5570861Z"},"Data":{"Succeeded":true,"ContactId":20921043}}

Role: Contact(Write)

In order to avoid a 403 Forbidden response, please make sure you have the required roles as indicated in the API Reference.

2. Check the ContactCreateResult

Afer creating a contact, you can check the resulting data by using the ContactCreateResult.

First you should check if the Succeeded is true. Otherwise the request failed. You can find the failure reason in the FailureMessage, which can be one of the following:

Invalid e-mail address specified
Invalid phone (E.164)
Invalid date (ISO 8601 format)
Unkown country code (ISO 3166-1)
Unknown state code (US State code)
Invalid language code specified (ISO 639-1)
E-mail address is on the bounce suppression list
E-mail address is on the optout list
The survey with the given SurveyId doesn't exists
The survey should have the status In Development (1) or Live (2).

If the request wa successsful, the ContactId will be available. This contact id can be used to retrieve the contact information with the request below.

cURL
C# .NET

Request

curl -X GET "https://api-us.agileresearch.medallia.com/3/contacts/{ContactId}" 
-H "X-Master-Key: {MasterKey}" 
-H "X-Key: {Key}" 
-H "Content-type: application/json"

curl -X GET "https://api-us.agileresearch.medallia.com/3/contacts/{ContactId}" 
-H "X-Master-Key: {MasterKey}" 
-H "X-Key: {Key}" 
-H "Content-type: application/json"

Response

{"Meta":{"Status":200,"Timestamp":"2024-11-23T12:23:12.5630855Z"},"Data":{"ContactId":20960745,"FirstName":"Jane","Email":"john.doe@mail.com","Gender":"F"}}

Request

System.Net.Http.HttpClient client = new System.Net.Http.HttpClient();
client.BaseAddress = new Uri("https://api-us.agileresearch.medallia.com/");
client.DefaultRequestHeaders.Add("X-Master-Key", "{MasterKey}");
client.DefaultRequestHeaders.Add("X-Key", "{Key}");
client.DefaultRequestHeaders.Accept.Add(new System.Net.Http.Headers.MediaTypeWithQualityHeaderValue("application/json"));

string requestUri = string.Format("3/contacts/{0}", "{ContactId}");

System.Net.Http.HttpResponseMessage response = client.GetAsync(requestUri).Result;

System.Net.Http.HttpClient client = new System.Net.Http.HttpClient();
client.BaseAddress = new Uri("https://api-us.agileresearch.medallia.com/");
client.DefaultRequestHeaders.Add("X-Master-Key", "{MasterKey}");
client.DefaultRequestHeaders.Add("X-Key", "{Key}");
client.DefaultRequestHeaders.Accept.Add(new System.Net.Http.Headers.MediaTypeWithQualityHeaderValue("application/json"));

string requestUri = string.Format("3/contacts/{0}", "{ContactId}");

System.Net.Http.HttpResponseMessage response = client.GetAsync(requestUri).Result;

Response

{"Meta":{"Status":200,"Timestamp":"2024-11-23T12:23:12.5630855Z"},"Data":{"ContactId":20960745,"FirstName":"Jane","Email":"john.doe@mail.com","Gender":"F"}}

Or retrieve the contact from the survey and immediately get the survey urls.

cURL
C# .NET

Request

curl -X "https://api-us.agileresearch.medallia.com/3/surveys/{SurveyId}/panelists/{ContactId}" 
-H "X-Master-Key: {MasterKey}" 
-H "X-Key: {Key}" 
-H "Content-type: application/json"

curl -X "https://api-us.agileresearch.medallia.com/3/surveys/{SurveyId}/panelists/{ContactId}" 
-H "X-Master-Key: {MasterKey}" 
-H "X-Key: {Key}" 
-H "Content-type: application/json"

Response

{
	"Meta" : {
		"Status" : 200,
		"Timestamp" : "2024-11-23T12:23:12.5630855Z"
	},
	"Data" : {
		"PreviewUrl" : "https://s.chkmkt.com/?e={SurveyId}&l=&c=20960745&h=6F00B98B3738C94&v=1&m=PREVIEW",
		"LiveUrl" : "https://s.chkmkt.com/?e={SurveyId}&l=&c=20960745&h=6F00B98B3738C94",
		"PanelistStatusId" : 1,
		"DateAdded" : "2024-11-23T12:23:12.5630855Z",
		"Password" : "F628D3",
		"ContactId" : 20960745,
		"FirstName" : "Jane",
		"Email" : "john.doe@mail.com"
	}
}

Request

System.Net.Http.HttpClient client = new System.Net.Http.HttpClient();
client.BaseAddress = new Uri("https://api-us.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 = string.Format("3/surveys/{0}/panelists/{1}", "{SurveyId}", "{ContactId}");

System.Net.Http.HttpResponseMessage response = client.GetAsync(requestUri).Result;

System.Net.Http.HttpClient client = new System.Net.Http.HttpClient();
client.BaseAddress = new Uri("https://api-us.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 = string.Format("3/surveys/{0}/panelists/{1}", "{SurveyId}", "{ContactId}");

System.Net.Http.HttpResponseMessage response = client.GetAsync(requestUri).Result;

Response

{
	"Meta" : {
		"Status" : 200,
		"Timestamp" : "2024-11-23T12:23:12.5630855Z"
	},
	"Data" : {
		"PreviewUrl" : "https://s.chkmkt.com/?e={SurveyId}&l=&c=20960745&h=6F00B98B3738C94&v=1&m=PREVIEW",
		"LiveUrl" : "https://s.chkmkt.com/?e={SurveyId}&l=&c=20960745&h=6F00B98B3738C94",
		"PanelistStatusId" : 1,
		"DateAdded" : "2024-11-23T12:23:12.5630855Z",
		"Password" : "F628D3",
		"ContactId" : 20960745,
		"FirstName" : "Jane",
		"Email" : "john.doe@mail.com"
	}
}

Used Method(s)

We have used the following methods in this example. You can find all details regarding each request in the API Reference.

POST	3/contacts
GET	3/surveys/{SurveyId}/panelists/{ContactId}
GET	3/contacts/{ContactId}

Example variables

Add a new contact to a survey

1. Add a new contact to your survey

cURL

C# .NET

Role: Contact(Write)

2. Check the ContactCreateResult

cURL

C# .NET

cURL

C# .NET

Used Method(s)