The List Manager API

Current version: 9.0

Sitecore stores contact lists as marketing definitions. On a Content Manager (CM) instance, you can access contact lists programmatically with the List Manager API.

Note

You cannot use the List Manager API on a Content Delivery (CD) instance because the List Manager application is disabled in this case.

Important

The code snippets in this topic apply to Sitecore 9.0.1 and later. The table below lists the equivalent commands for Sitecore 9.0.

Sitecore 9.0.1 and later	Sitecore 9.0
GetService<IFetchRepository<SegmentModel>>()	GetService<SegmentRepository>()
GetService<IFetchRepository<SegmentedListModel>>()	GetService<SegmentedListRepository>()
GetService<IFetchRepository<ContactListModel>>()	GetService< ContactListRepository>()

Add, update, and delete a segment

This example shows you how to add a segment using the List Manager API.

Note

The creation and modification of the segment rules can only be done through the List Manager interface.

RequestResponseshell

var segmentRepository = ServiceLocator.ServiceProvider.GetService< SegmentRepository>();

var newSegment = new SegmentModel
      {
         Id = Guid.NewGuid().ToString("B"),
         Name = "New Segment",
         Description = "New Description",
         UseAsAnalyticsFilter = true
      };

segmentRepository.Add(newSegment);

This example shows you how to update a segment.

RequestResponseshell

var segmentRepository = ServiceLocator.ServiceProvider.GetService< SegmentRepository>();

//Find existing segment by ID. ID must be vali
var segmentToUpdate =  segmentRepository.FindById("{00000000-0000-0000-0000-000000000000}");
segmentToUpdate.Description = "New Description";
segmentRepository.Update(segmentToUpdate);

This example shows you how to delete a segment.

RequestResponseshell

var segmentRepository = ServiceLocator.ServiceProvider.GetService<IFetchRepository<SegmentModel>>();

//Find existing segment by ID. ID must be valid.

var segmentToDelete =  segmentRepository.FindById("{00000000-0000-0000-0000-000000000000}");
segmentRepository.Delete(segmentToDelete);

Add, update, and delete a segmented list

This example shows you how to add a segmented list.

RequestResponseshell

var segmentedListRepository = ServiceLocator.ServiceProvider.GetService< SegmentedListRepository>();

var newSegmentedList = new SegmentedListModel()
            {
                Id = Guid.NewGuid().ToString("B"),
                Name = "New Contact List",
                Description = "Description of the contact list",
                Owner = "Administrator"
            };

To add segments to the list you want to create, use this code snippet.

RequestResponseshell

newSegmentedList .SegmentIds = new[] {“<Guid of the Segment>”};

To save the new segmented list, use this code snippet.

RequestResponseshell

segmentedListRepository.Add(newSegmentedList);

This example shows you how to update a segmented list.

RequestResponseshell

var segmentedListRepository = ServiceLocator.ServiceProvider.GetService< SegmentedListRepository>();

//Find existing list by ID. ID must be valid.

var listToUpdate =  segmentedListRepository.FindById("{00000000-0000-0000-0000-000000000000}");
listToUpdate.Description = "New Description";
segmentedListRepository.Update(listToUpdate);

This example shows you how to delete a segmented list.

RequestResponseshell

var segmentedListRepository = ServiceLocator.ServiceProvider.GetService<IFetchRepository<SegmentedListModel>>();

//Find existing list by ID. ID must be valid.

var listToDelete =  segmentedListRepository.FindById("{00000000-0000-0000-0000-000000000000}");
segmentedListRepository.Delete(listToDelete);

Add, update, and delete a contact list

This example shows you how to add a contact list.

RequestResponseshell

var contactListRepository = ServiceLocator.ServiceProvider.GetService<IFetchRepository< ContactListModel>>();
var newContactList = new ContactListModel()
       {
           Id = Guid.NewGuid().ToString("B"),
           Name = "New Contact List",
           Description = "Description of the contact list",
           Owner = "Administrator"
        };

To add an included list to the one you want to create, use this code snippet.

RequestResponseshell

newContactList.Subscriptions.Add(new SubscriptionViewModel
            {
               Id = Guid.NewGuid(),
               ListId = <Guid of the List>, 
               Name= "Name of the included list"
            });

To save the new contact list, use this code snippet.

RequestResponseshell

contactListRepository.Add(newContactList);

This example shows you how to update a contact list.

RequestResponseshell

var contactListRepository = ServiceLocator.ServiceProvider.GetService<IFetchRepository< ContactListModel>>();

//Find existing list by ID. ID must be valid.
var listToUpdate =  contactListRepository.FindById("{00000000-0000-0000-0000-000000000000}");
listToUpdate.Description = "New Description";
contactListRepository.Update(listToUpdate);

This example shows you how to delete a contact list.

RequestResponseshell

var contactListRepository = ServiceLocator.ServiceProvider.GetService<IFetchRepository< ContactListModel>>();

//Find existing list by ID. ID must be valid.

var listToDelete =  contactListRepository.FindById("{00000000-0000-0000-0000-000000000000}");
contactListRepository.Delete(listToDelete);

Add and remove contacts

This example shows you how to add one contact to a contact list:

RequestResponseshell

var subscriptionService = ServiceLocator.ServiceProvider.GetService<ISubscriptionService>();
subscriptionService.Subscribe(contactListId, contactId);

This example shows you how to add multiple contacts to a contact list:

RequestResponseshell

var contacts = new List<Contact>(); // List of contacts
var subscriptionService = ServiceLocator.ServiceProvider.GetService<ISubscriptionService>();
subscriptionService.Subscribe(contactListId, contacts);

To remove a contact association and call the corresponding methods from ISubscriptionService:

RequestResponseshell

var subscriptionService = ServiceLocator.ServiceProvider.GetService<ISubscriptionService>();
subscriptionService.Unsubscribe(contactListId, contactId);
subscriptionService.Unsubscribe(contactListId, contacts);

Retrieve contacts associated with a list

This example shows how you retrieve contacts from a contact list:

RequestResponseshell

int batchSize = 200; // Size of the batch
string[] facets =
{
    CollectionModel.FacetKeys.PersonalInformation,    
    CollectionModel.FacetKeys.ListSubscriptions
}; // Contact facets to retrieve
var contactListProvider = ServiceLocator.ServiceProvider.GetService<IContactListProvider>();
var contactProvider = ServiceLocator.ServiceProvider.GetService<IContactProvider>();
var contactList = contactListProvider.Get(contactListId, cultureInfo);
var contactBatchEnumerator = contactProvider.GetContactBatchEnumerator(
    contactList,     
    batchSize,
     facets);
while (contactBatchEnumerator.MoveNext())
{    
var contacts = contactBatchEnumerator.Current;
    // write your logic here
    contacts.ToList();
}

The example uses a batch enumerator as the most efficient and the fastest way to iterate over contacts. See the xConnect documentation for more information.