Retrieving and adding opt-outs

This tutorial will show you how to get opt-outs from your CheckMarket account and how to add new ones to your account so that future surveys are not sent to those contacts. When a contact in your account opts out, it means they do not want to receive anymore surveys from you. These contacts are automatically added to your global opt-out list. Contacts on your global opt-out list can no longer be imported or sent any emails or SMS through CheckMarket.

Retrieving optouts

The retrieve call lets you get all of the opt-outs in your account and you can set a filter and get only opt-outs after a certain date. The workflow that we often see is that all opt-outs are retrieved the first time in an initial call and then after that, opt-outs from only the last 24 hours are retrieved each day. This information can be passed to your CRM or other platform from which you conduct surveys. To get informed about opt-outs even faster, use our opt-out webhook (recommended). Once the webhook is set up, our system will automatically send a call to your system in real time, each time someone opts out. Just set up an endpoint on your end to receive the call from our system. That way you do not needlessly poll our system.

• cURL

• C# .NET

curl -X "https://api-us.agileresearch.medallia.com/3/surveys/{SurveyId}/contacts/optouts?filter==DateOptOut%20ge%20DateTime'2019-01-01'" 
-H "X-Master-Key: {MasterKey}" 
-H "X-Key: {Key}" 
-H "Content-type: application/json" 

{
    "Meta": {
        "Status": 200,
        "Timestamp": "2024-11-21T15:27:59.0914548Z",
    },
    "Data": [
        {
            "DateOptOut": "2019-01-13T08:31:01.033Z",
            "LangCode": "en",
            "ContactId": 53934305,
            "FirstName": "John",
            "LastName": "Doe",
            "Email": "john.doe@mail.com",
        },{
            "DateOptOut": "2019-01-13T08:31:01.033Z",
            "LangCode": "en",
            "ContactId": 53934306,
            "FirstName": "Jane",
            "LastName": "Doe",
            "Email": "jane.doe@mail.com",
        },
        {...}
    ],
    "Links": {
        "Next": {
            "Href": "https://api-eu.checkmarket.com/3/contacts/optouts?$top=25&$skip=25",
            "Method": "GET"
        }
    }
}

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");
System.Net.Http.HttpResponseMessage response = client.GetAsync("3/contacts/optouts?filter==DateOptOut%20ge%20DateTime'2019-01-01'")).Result;

{
    "Meta": {
        "Status": 200,
        "Timestamp": "2024-11-21T15:27:59.0914548Z",
    },
    "Data": [
        {
            "DateOptOut": "2019-01-13T08:31:01.033Z",
            "LangCode": "en",
            "ContactId": 53934305,
            "FirstName": "John",
            "LastName": "Doe",
            "Email": "john.doe@mail.com",
        },{
            "DateOptOut": "2019-01-13T08:31:01.033Z",
            "LangCode": "en",
            "ContactId": 53934306,
            "FirstName": "Jane",
            "LastName": "Doe",
            "Email": "jane.doe@mail.com",
        },
        {...}
    ],
    "Links": {
        "Next": {
            "Href": "https://api-eu.checkmarket.com/3/contacts/optouts?$top=25&$skip=25",
            "Method": "GET"
        }
    }
}

As with all our response, the default paging size is 25. If you have more than 25 optouts your result will contain the Hateoas next link. Use this link in your next request to get your next set of opt-outs.

Add your opt outs to our platform

The second function discussed here let's you add opt-outs to your CheckMarket account that come from your own systems. Say that someone opts out of all emails from you, then you pass that information to your CheckMarket account so that you do not send them anymore surveys.

• cURL

• C# .NET

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

-d "{{
  "EmailAddresses": [
    "john.doe@mail.com",
    "jane.doe@mail.com"
  ],
  "PhoneNumbers": [
    "+1-202-555-0117",
    "+1-202-555-0118"
]}}" 

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 = $"3/contacts/optouts/";
var jsonObject = new 
{
	EmailAddresses= new string[]{
		"john.doe@mail.com",
		"jane.doe@mail.com"
	},
	PhoneNumbers= new string[]{
		"+1-202-555-0117",
		"+1-202-555-0118",
	}
};
System.Net.Http.HttpResponseMessage response = client.PostAsJsonAsync(requestUri, jsonObject).Result;

Used Method(s)

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