The List Manager API

Current version: 10.2

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.

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.

RequestResponse
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.

RequestResponse
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.

RequestResponse
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.

RequestResponse
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.

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

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

RequestResponse
segmentedListRepository.Add(newSegmentedList);

This example shows you how to update a segmented list.

RequestResponse
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.

RequestResponse
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.

RequestResponse
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.

RequestResponse
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.

RequestResponse
contactListRepository.Add(newContactList);

This example shows you how to update a contact list.

RequestResponse
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.

RequestResponse
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:

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

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

RequestResponse
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:

RequestResponse
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:

RequestResponse
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.

Do you have some feedback for us?

If you have suggestions for improving this article,